지난 장에서 우리는 첫 번째 버튼의 이름까지 왔다. 구조다.
이제 그 버튼을 누른다.
지난 장에서 본 것처럼, AI는 일을 시작할 때마다 프로젝트를 처음 읽는 작업자다. 그래서 AI에게 프로젝트는 한 권의 책과 같다. 목차가 잘 잡힌 책이라면 어디에 무엇이 있는지 훑어보는 것만으로 알 수 있어서, 필요한 쪽만 바로 펼치면 된다. 목차가 없는 책이라면 매번 첫 장부터 뒤지며 찾아야 한다.
프로젝트에서 이 목차 역할을 하는 것이 폴더와 파일 이름이다. 무엇이 어떤 이름으로 어디에 놓여 있는지가 AI에게는 곧 목차다. 구조 버튼을 누른다는 것은 AI가 읽을 이 목차를 정리하는 일이다.
구조 = AI가 읽는 프로젝트의 목차
그렇다면 목차가 없는 프로젝트에서 AI는 어떻게 일하게 될까.
예를 들어 비즈니스 대시보드 프로젝트 폴더를 하나 만들었다고 해보자. 그동안 대화창에 매번 붙여 넣던 판매 기록과 문의 기록, 말로 다시 일러주던 기준, 지난주에 만든 현황 정리, 검수 때마다 불러오던 확인 목록까지 전부 파일로 꺼내 이 폴더에 넣었다고 가정해보자.
my-business-dashboard/
├── 기준-메모.md # 환불은 매출에서 빼고, 광고 제안은 문의에서 제외한다
├── sales.csv
├── inquiries.csv
├── content-log.md
├── 지난주-현황정리.md
└── 검수-체크리스트.md
대화 안에 흩어져 있던 것들이 한 폴더에 나란히 들어갔다. 이제 자료가 한곳에 모였으니 일이 매끄러울 것 같다. 그래서 AI에게 이렇게 말한다.
이 폴더의 자료들을 참고해서
이번 주 비즈니스 대시보드를 만들어줘.
결과는 제법 잘 나온다. 목차가 없어도 책을 읽을 수 없는 것은 아니듯, AI는 파일을 하나하나 열어보며 역할을 알아낸다. sales.csv는 판매 자료로 읽고, 기준-메모.md는 기준이 적힌 파일로 읽어서, 시킨 대로 대시보드를 만들어냈다.
다만 자세히 읽어보면, 목차가 정해주지 않은 대목을 AI가 짐작으로 채운 흔적이 보인다. 지난주-현황정리.md는 형식만 참고하라고 넣어둔 파일인데, 그 안에 적힌 지난주 진단까지 이번 주 리포트에 그대로 옮겨 왔다. 이번 주는 매출 흐름이 달라졌는데도 리포트에는 지난주와 같은 코멘트가 붙어 있다. 그리고 판매 기록을 정리하면서 sales.csv 옆에 sales-updated.csv라는 파일을 새로 만들어 두어서, 다음에 폴더를 열면 어느 쪽이 진짜 원본인지부터 헷갈리게 생겼다. 하나하나는 그럴 수 있는 판단이지만, 내가 기대한 결과와는 조금씩 다르다.
자료가 부족했던 것이 아니다. AI가 알 수 없었던 것은 어느 파일이 형식만 빌리는 참고용이고, 어느 파일이 손대면 안 되는 원본이며, 새로 만든 결과는 어디에 두어야 하는지였다. 사람은 이런 구분을 굳이 적어두지 않아도 알지만, 폴더 어디에도 적혀 있지 않다. 그래서 애매한 자리가 나올 때마다 AI는 자기 짐작으로 메운다.
그리고 이 짐작은 대체로 그럴듯하지만, 반복 작업에서는 조금씩 흔들린다.
파일명은 짐작, 폴더는 약속
폴더에서 AI가 짐작의 근거로 삼을 수 있었던 것은 사실상 파일명뿐이었다. 파일명은 분명 단서가 된다. 하지만 단서는 약속이 아니다.
sales.csv라는 이름은 그 파일을 판매 자료처럼 보이게 하지만, "이것은 원본이니 고치지 말고 읽기만 하라"고까지는 말해주지 않는다. 지난주-현황정리.md라는 이름만으로는 이번 주에 따라 만들 양식인지, 끝난 결과물이라 손대면 안 되는 기록인지 분명하지 않다. 이름은 단서를 주지만, 역할을 고정하지는 못한다.
그 고정을 해주는 것이 폴더다. 폴더는 이름이 주던 약한 짐작을 눈에 보이는 약속으로 바꾼다. 사람들은 오랫동안 src에는 코드를, tests에는 검증을, inputs에는 원자료를 두는 식으로 프로젝트를 정리해왔고, AI도 이 관례를 단서로 읽는다. 그래서 파일명 하나보다, 역할별로 묶인 폴더가 더 분명한 맥락이 된다.
inputs/ 안에 있으면 원본 자료다.
context/ 안에 있으면 판단할 때 참고할 기준이다.
outputs/ 안에 있으면 작업 결과다.
tests/ 안에 있으면 검증이다.
같은 sales.csv라도 inputs/에 있으면 손대지 말아야 할 원본 자료로 읽힌다. 반대로 outputs/ 안에 있는 파일이라면 새로 만들거나 갱신되는 결과물에 가깝다.
파일 이름은 그대로여도, 놓인 폴더가 달라지면 AI가 다루는 방식도 달라진다. 이름과 폴더가 함께 그 파일의 쓰임을 정한다.
파일 이름은 "무엇에 대한 파일인지"를 말한다.
폴더는 "어떤 역할로 다뤄야 하는지"를 말한다.
폴더를 나누는 일은 개발자의 정리 습관이 아니다. AI에게 "여기는 기준, 여기는 자료, 여기는 결과"라고 미리 약속해두는 일이다.
이 약속이 있어야 AI는 매번 새로 짐작하지 않는다.
이 약속이 갖춰지면 프로젝트의 목차가 완성된다. 어디서 자료를 읽고, 어떤 기준을 따르고, 결과를 어디에 남길지를 AI는 목차를 통해 찾을 수 있게 된다. AI가 덜 헤맬수록 사람의 검수 부담도 줄어든다. 결과가 흔들릴 때 우리는 프롬프트부터 의심하지만, 먼저 봐야 할 것은 AI가 읽을 목차가 있는가다.
내 프로젝트에 맞게 구조 잡기
폴더 구조에는 정답이 없다.
프로젝트의 종류와 상태에 따라 필요한 폴더는 달라진다. 앱을 만드는 프로젝트인지, 글을 쓰는 프로젝트인지, 데이터를 분석하는 프로젝트인지에 따라 구조는 달라질 수밖에 없다.
중요한 것은 정해진 폴더 이름을 그대로 따라 하는 것이 아니다. 내 프로젝트 안에서 역할이 다른 것들을 구분하는 것이다. 무엇이 원본 자료인지, 무엇이 판단 기준인지, 무엇이 결과물인지, 무엇이 검증인지 나누어두는 것이 핵심이다.
이 책에서는 비즈니스 대시보드 프로젝트를 예시로 삼는다. 이 프로젝트에서는 다음과 같은 구조를 하나의 출발점으로 쓸 수 있다.
my-business-dashboard/
├── CLAUDE.md # AI가 작업을 시작할 때 참고하는 안내 파일
├── src/ # 실제 비즈니스 대시보드 앱이 자라는 곳
├── tests/ # 코드로 확인하는 검증이 놓이는 곳
├── context/ # AI가 판단할 때 다시 읽는 맥락과 기준
├── inputs/ # 판매, 문의, 콘텐츠 기록 같은 원본 자료
├── outputs/ # AI가 만들어낸 결과물이 쌓이는 곳
├── handoff.md # 다음 작업으로 이어지는 기록
└── .claude/ # Claude Code의 설정과 자동화가 놓이는 곳
이 구조는 모든 프로젝트에 적용되는 정답이 아니다. 비즈니스 대시보드 프로젝트에서 역할을 나눠보기 위한 예시다. 다른 프로젝트라면 폴더 이름도, 개수도, 나누는 기준도 달라질 수 있다.
예를 들어 글쓰기 프로젝트라면 src/ 대신 drafts/가 더 자연스러울 수 있다. 강의 제작 프로젝트라면 slides/, scripts/, references/가 필요할 수도 있다. 데이터 분석 프로젝트라면 raw-data/, processed-data/, notebooks/처럼 나누는 편이 더 맞을 수도 있다.
중요한 것은 이름이 아니라 역할이다.
하나 미리 말해두면, 이 폴더들을 지금 다 이해하거나 외울 필요는 없다. context/에 무엇을 담을지, tests/로 어떻게 검증할지, .claude/에 무엇을 둘지는 모두 이후에 소개될 버튼들에서 하나씩 자세히 다룬다. 지금 잡아둘 것은 "역할이 다른 것은 자리를 나눈다"는 감각 하나다.
그러니 아래 폴더 설명은 외울 목록이 아니라, 그 감각을 잡기 위한 참고로 읽으면 된다.
이 대시보드 예시에서는 각 폴더의 역할을 이렇게 나눈다.
src/는 실제 앱이 자라는 곳이다. 비즈니스 대시보드의 화면과 기능이 여기에 쌓인다.tests/는 코드로 확인하는 검증이 놓이는 곳이다. 매출이 기준대로 계산되는지, 환불이 제대로 빠졌는지 같은 확인이 여기에 들어간다.context/는 AI가 판단할 때 다시 읽어야 할 맥락과 기준을 두는 곳이다. 환불을 매출에서 어떻게 뺄지, 광고 제안을 문의 수에서 제외할지, 조회수를 어떤 의미로 해석할지 같은 약속이 여기에 있다.inputs/는 원본 자료를 두는 곳이다. 판매 기록, 문의 기록, 콘텐츠 기록처럼 손대지 말아야 할 사실이 여기에 있다.outputs/는 AI가 만들어낸 결과물을 두는 곳이다. 매주 현황 정리, 분석 결과, 다음 행동 제안처럼 작업을 거쳐 나온 산출물이 여기에 쌓인다.handoff.md는 다음 작업이 이어받을 기록을 두는 파일이다. 지금 작업을 어디까지 했고, 무엇이 남았고, 다음에는 무엇을 봐야 하는지 여기에 남긴다.
이렇게 폴더로 자리를 정해두면, inputs/의 파일은 원본 자료로, context/의 파일은 판단 기준으로 다루도록 약속할 수 있다. 작업을 거쳐 나온 결과는 outputs/에 새로 남기고, 작업이 끝나면 다음 작업을 위해 handoff.md에 이어받을 내용을 남긴다.
이렇게 구조를 잡아두면 AI는 어떤 데이터가 어디에 있고 어떤 역할을 하는지 명확히 알 수 있다. 짐작으로 채우던 자리가 사라지는 만큼, 모든 것이 한 폴더에 섞여 있을 때보다 훨씬 더 내 의도에 맞게 움직인다.
바꿔도 되는 이름과 바꾸면 안 되는 이름
여기서 한 가지를 더 구분해야 한다. 프로젝트 안에는 사용자가 자유롭게 정할 수 있는 이름과, Claude Code가 이미 약속해둔 이름이 함께 있다. 이 둘을 구분해야 나중에 무엇을 바꿔도 되고, 무엇은 그대로 두어야 하는지 헷갈리지 않는다.
사용자가 정하는 이름: src/ tests/ context/ inputs/ outputs/ handoff.md
Claude Code가 정한 이름: CLAUDE.md .claude/
src/, context/, inputs/, outputs/ 같은 폴더는 사용자가 프로젝트에 맞게 정하는 이름이다. inputs/를 data/로 바꾸거나 한국어로 자료/라고 불러도 되고, 새 폴더를 더해도 된다. 중요한 것은 이름 자체가 아니라 그 폴더가 맡은 역할이다.
반면 CLAUDE.md와 .claude/는 Claude Code가 미리 정해둔 이름이다. 이름 자체가 Claude Code와 맺은 약속이라, 함부로 바꾸면 같은 방식으로 읽히지 않거나 안에 둔 설정이 작동하지 않을 수 있다. CLAUDE.md는 AI가 작업을 시작할 때 가장 먼저 읽는 안내 파일이고, .claude/에는 반복 작업·규칙·에이전트 같은 설정과 자동화가 놓인다.
지금 이 두 가지의 안을 채울 필요는 없다. 무엇을 적을지는 뒤에서 버튼을 하나씩 누르며 채워간다.
직접 만드는 대신, 맡긴다
여기까지 읽으면 이런 생각이 들 수 있다.
"그럼 이 폴더들을 내가 하나하나 만들어야 하나?"
"폴더 이름도 정하고 파일도 옮기고, 이거 너무 개발자 일 아닌가?"
그렇지 않다.
이 책의 독자는 폴더 구조를 손으로 잘 만드는 사람이 아니라, 좋은 구조가 어떤 모습인지 알아보고 그 일을 AI에게 맡길 수 있는 사람이다. 구조 버튼에서 중요한 것도 폴더를 직접 만드는 능력이 아니라, 어떤 일이 어느 자리에 놓여야 하는지 구분하는 감각이다.
구조 버튼을 누르는 일은 두 단계면 충분하다. 내 프로젝트를 있는 그대로 설명하는 것, 그리고 역할을 나누는 일부터 AI에게 맡기는 것이다.
먼저 내 프로젝트가 어떤 일인지 설명할 준비를 한다. 거창한 분석이 아니라 아래 세 가지면 충분하다.
무엇을 만드는 프로젝트인가. (앱, 글, 데이터 분석, 강의 자료…)
어떤 작업을 반복하는가.
그 작업에 어떤 파일과 자료가 오가는가.
정답을 갖출 필요는 없다. 떠오르는 대로 적어두면, 그것이 곧 AI에게 알려줄 내 프로젝트의 상황이 된다.
다음은 위임이다. 이 프로젝트에 어떤 역할들이 있는지 구분하는 일부터 폴더 구조 제안까지, 방금 정리한 상황을 주고 통째로 맡긴다.
AI와 함께 작업하기 좋게 폴더 구조를 잡고 싶어.
내 프로젝트 상황은 이래.
- 만드는 것: (프로젝트 종류)
- 반복하는 작업: (매주 현황 정리, 원고 발행 등)
- 오가는 파일과 자료: (지금 갖고 있는 것들)
이 프로젝트에 역할이 다른 것들이 무엇무엇 있는지 먼저 구분해줘.
그 역할에 맞는 폴더 구조를 제안하고,
어떤 파일을 어디로 옮기면 좋을지 계획을 보여줘.
내가 확인하면 그때 정리해줘.
핵심은 폴더 이름을 정확히 받아쓰는 것이 아니라, 역할을 나누는 감각을 가지고 내 프로젝트에 맞는 구조를 AI와 함께 잡아가는 것이다. 처음부터 완벽할 필요도 없다. 구조는 한 번에 완성하는 것이 아니라, 쓰다가 불편한 곳이 보일 때마다 폴더를 더하고 나누면서 점점 자리를 잡아간다.
이렇게 구조를 한 번 잡아두면 AI가 읽을 목차가 생기고, 이후의 모든 작업이 그 위에서 이어진다.
다만 자리를 나눠두는 것만으로 모든 것이 전달되지는 않는다. 폴더는 무엇이 어디에 있는지까지만 알려줄 뿐, 그것을 어떤 규칙과 기준으로 다뤄야 하는지는 말해주지 못한다. 그래서 구조를 잡은 다음에는 이 규칙과 기준을 AI에게 알려주는 일이 남는다. 그것을 적어두는 파일이 CLAUDE.md다.
이 장에서 기억할 것
구조는 폴더를 보기 좋게 정리하는 일이 아니다.
AI가 읽을 프로젝트의 목차를 만드는 일이다.
파일 이름은 “무엇에 대한 파일인지”를 알려준다.
하지만 그 파일을 어떻게 다뤄야 하는지는 폴더가 알려준다.
구조를 만든다는 것은 AI가 매번 짐작하던 일을 줄이는 것이다.
무엇을 읽고 무엇을 남길지, 파일이 놓인 자리만 보고도 알 수 있게 해두는 일이다.
중요한 것은 폴더 이름을 외우는 것이 아니다.
내 프로젝트 안에서 역할이 다른 것들을 구분하는 감각이다.
이제 AI가 읽을 목차는 생겼다.
다음 장에서는 이 구조를 어떤 규칙과 기준으로 다뤄야 하는지 CLAUDE.md에 적어 넣는다.
