1. Claude Code 프로젝트 구조 한눈에 보기

8장에서 Code 탭에 폴더 하나를 지정하고 일을 맡겼습니다. 그때 우리가 만진 것은 채팅창뿐이었지만, Claude Code는 사실 그 폴더 안에 놓인 파일들을 함께 읽으며 일합니다. 그래서 이 도구를 오래 쓰는 사람들은 일을 시키기 전에 폴더부터 갖춰 둡니다.

여기서는 그렇게 갖춰 둔 폴더가 어떤 모습인지 살펴봅니다. 파일 이름이 낯설게 느껴질 수 있는데, 지금 이걸 다 만들라는 뜻이 아닙니다. 대부분은 프로젝트가 커진 뒤에야 하나씩 생깁니다. 나중에 이런 폴더를 마주쳤을 때 "이건 뭐지" 하고 멈추지 않도록 지도만 익혀 두는 자리라고 생각해주세요.

1.1 왜 폴더에 파일을 두는가

Claude는 대화를 새로 열 때마다 기억이 비어 있는 상태로 시작합니다. 어제 알려준 회사 규칙도, 지난주에 고쳐준 말투도 새 대화에서는 남아 있지 않습니다. 그래서 매번 같은 설명을 다시 적게 됩니다.

7장에서 이 문제를 프로젝트 지침으로 해결했습니다. 지침을 한 번 적어 두면 그 프로젝트의 모든 대화가 그 내용을 읽고 시작했습니다. Claude Code가 하는 일도 똑같습니다. 다른 점은 그 지침을 설정 화면이 아니라 폴더 안의 파일로 둔다는 것뿐입니다.

새로 온 직원의 책상에 업무 매뉴얼을 올려 두는 상황을 떠올리면 쉽습니다. 매뉴얼이 책상에 있으니 매일 아침 같은 설명을 반복하지 않아도 되고, 다음 사람이 와도 그 자리에 그대로 있습니다. 파일이라서 생기는 이점도 여기서 나옵니다. 팀원에게 폴더째 건네면 지침도 함께 건너가고, 내용이 바뀌면 언제 누가 무엇을 고쳤는지 기록으로 남습니다.

1.2 폴더에 놓이는 파일들

갖춰 둔 폴더를 열면 대체로 이런 모습입니다.

하나씩 풀면 다음과 같습니다. 마지막 열은 Desktop에서 이미 써본 기능 중 같은 역할을 하는 것입니다.

여기서 AGENTS.md 하나는 미리 알아두면 좋습니다. 이 파일은 Claude Code가 직접 읽는 파일이 아닙니다. 여러 AI 도구가 공통으로 쓰자고 만들어진 이름이라, 이미 이 파일이 있는 프로젝트라면 CLAUDE.md 안에 @AGENTS.md 한 줄을 적어 불러오는 방식으로 씁니다. 같은 내용을 두 벌 적지 않기 위해서입니다.

이 밖에 .claude/workflows/나 .worktreeinclude 같은 파일이 더 보이기도 합니다. 여러 작업을 한꺼번에 돌릴 때 쓰는 것으로, 개발자가 큰 프로젝트를 다룰 때 만나는 파일입니다. 이런 것도 있구나 정도로 넘어가도 괜찮습니다.

1.3 언제 읽히는가

여기까지 보면 의문이 하나 남습니다. 파일이 이렇게 많으면 대화를 열 때마다 전부 읽어야 하는 것 아닌가 하는 의문입니다.

6.6에서 갖춰 둔 도구의 비용을 이야기했습니다. 프로젝트 지침도, 설치한 Skill도 대화가 시작될 때마다 함께 실리고, 그만큼 대화가 무거워지고 답이 둔해진다는 내용이었습니다. Claude Code도 사정이 같습니다. 그래서 모든 지침을 한 파일에 몰아넣는 대신, 읽히는 시점을 네 단계로 나눠 둡니다.

읽히는 시점은 단계마다 이렇게 다릅니다. 1단계는 대화를 열 때마다 항상 실립니다. 2단계는 관련된 파일을 다룰 때만, 3단계는 그 절차가 필요해질 때만 읽힙니다. 4단계는 아예 별도의 담당자가 자기 자리에서 읽기 때문에 우리 대화에는 결과만 돌아옵니다. 늘 필요한 것만 책상에 두고 나머지는 손 닿는 곳에 정리해 두는 셈입니다.

2단계가 조금 낯설 텐데, 규칙 파일 맨 위에 "이 규칙은 이런 파일을 다룰 때만 적용해줘"라고 대상을 적어 두는 방식입니다. 디자인 규칙은 디자인 파일을 열 때만, 데이터 규칙은 데이터 파일을 열 때만 읽히게 하는 것입니다.

1.4 부탁과 자물쇠

앞의 파일들은 성격이 두 갈래로 나뉘는데, 이 구분이 초보자가 가장 자주 헷갈리는 부분입니다.

• CLAUDE.md와 rules/는 부탁입니다: Claude가 읽고 대체로 따르지만, 상황에 따라 다르게 판단할 수 있습니다. 사람에게 건네는 업무 지침과 성격이 같습니다.
• settings.json과 hooks는 자물쇠입니다: Claude의 판단과 관계없이 프로그램이 막습니다. "이 명령은 실행 금지"라고 적어 두면 Claude가 아무리 필요하다고 여겨도 실행되지 않습니다.

7.4에서 편집 수락 버튼으로 권한 단계를 조절해봤습니다. 그때는 버튼을 눌러 그때그때 정했다면, settings.json은 같은 결정을 파일에 미리 적어 두는 것입니다. 정말 일어나면 안 되는 일이 있다면 지침에 적어 부탁하지 말고 이쪽에 적어 막아야 합니다.

hooks는 여기서 한 걸음 더 나갑니다. "파일을 고칠 때마다 자동으로 서식을 정리해줘"처럼 정해진 시점에 반드시 실행되는 절차를 걸어 두는 장치입니다. 앞서 본 .claude/hooks/ 폴더에 들어 있는 것이 그때 실행되는 스크립트들입니다.

1.5 Claude가 스스로 적어 두는 메모

지금까지는 우리가 적는 파일이었는데, 반대로 Claude가 스스로 적는 쪽도 있습니다. 자동 메모리라고 부릅니다. 우리가 고쳐준 것, 자주 쓰는 명령, 이 프로젝트에서 알게 된 특징 같은 것을 알아서 기록해 두고 다음 대화에서 다시 읽습니다. 같은 지적을 두 번 하지 않아도 되게 만드는 장치입니다.

기록은 프로젝트 폴더가 아니라 내 컴퓨터의 개인 영역에 남습니다. 그래서 팀원에게 폴더를 건네도 내 메모까지 따라가지는 않습니다. 무엇이 저장됐는지 궁금하면 /memory 명령으로 목록을 열어 직접 읽고 고치거나 지울 수 있습니다.

1.6 처음 만들 때 지킬 것

실제로 파일을 만들기 시작하면 이 다섯 가지에서 갈립니다.

1. CLAUDE.md는 200줄 안쪽으로 유지합니다: 이 파일은 대화마다 통째로 실리기 때문에 길수록 비용이 늘고, 역설적으로 지시를 덜 지키게 됩니다. 길어지면 주제별로 잘라 rules/로 옮깁니다.
2. 결과를 확인하는 방법을 적어 둡니다: 만든 것을 어떻게 실행해보고 어떻게 점검하는지 적어 두면, Claude가 결과를 우리에게 넘기기 전에 스스로 확인합니다. 8장에서 본 '실행해보고 고치는' 반복이 여기서 나옵니다.
3. 비밀번호와 열쇠는 파일에 직접 적지 않습니다: .mcp.json 같은 파일은 팀과 함께 공유되기 때문에, 비밀 값은 파일 밖에 두고 이름으로만 불러옵니다.
4. .claude/ 폴더는 팀과 공유하고, 개인용 파일만 제외합니다: 이름에 local이 들어간 파일이 개인용입니다.
5. 목적에 맞는 도구를 고릅니다: 찾아보고 정리하는 일은 서브 에이전트에게, 반복되는 절차는 Skill로, 반드시 지켜져야 하는 것은 hooks로 맡깁니다.

1.7 Desktop에서 하던 일이 파일이 된다

지금까지 본 것을 돌아보면 새로운 개념은 사실 거의 없습니다. 지침을 적어 두는 일도, 절차를 Skill로 굳히는 일도, 외부 도구를 MCP로 잇는 일도, 무엇을 허용할지 정하는 일도 모두 이 책에서 이미 해본 것들입니다. Claude Code는 그 설정들을 화면의 메뉴가 아니라 폴더 안의 파일로 적을 뿐입니다.

6장에서 잘 대화하는 사람은 묻기 전에 환경부터 갖추는 사람이라고 했습니다. 폴더 구조가 복잡해 보이는 이유도 결국 하나입니다. 환경을 갖추는 방법이 그만큼 여러 갈래로 준비되어 있다는 뜻입니다.

당장 해볼 만한 것은 하나입니다. Code 탭에서 쓰는 폴더를 열고 이렇게 부탁해보세요.

이 폴더를 살펴보고 CLAUDE.md를 만들어줘. 어떤 자료가 들어 있는 폴더인지, 결과물은 어디에 저장해야 하는지, 내가 매번 알려주던 규칙은 무엇인지 정리해서 적어줘.

입력창에 /를 입력했을 때 목록에 /init이 보인다면 그 명령으로 같은 일을 시킬 수도 있습니다. 만들어진 파일을 열어보면 폴더 구조의 맨 위에 있던 CLAUDE.md가 무엇인지 손에 잡힐 겁니다. 나머지 파일들은 필요해질 때 하나씩 만나면 됩니다.