서론

📝

이전 글과의 관계: 직전의 기술서를 사지 않고 Claude Code를 1개월 만에 실용화한 학습법에서는 "공식 docs를 읽어라"라고 썼다. 본 기사는 그 다음에 이어지는 질문에 답한다: "그럼 공식 docs의 무엇을 읽어야 하는가", "Claude Code를 본격적으로 다루기 시작한 초보자가 손을 움직이기 전에 머릿속에 넣어두면 풍경이 바뀌는 .claude/의 각 디렉토리는 무엇을 위해 존재하는가"에 대한 이론편 = 설계의 지도를 제공한다.

이 글을 쓰는 이유: Claude Code를 1개월 사용하며 깨달은 가장 큰 배움은 "근본적인 제약은 단 하나"이며, "그로부터 모든 설계가 도출된다"는 것이었다. 이 경로를 초보자 눈높이에서 하나씩 다시 따라가 보면, Plan Mode / Skills / Subagents / Hooks가 제각각 떨어져 보이는 기능군이 아니라 하나의 제약으로부터 도출된 필연으로서 납득하게 된다.

독자에게 어떤 가치가 있는가:

• .claude/ 하위 디렉토리를 "일단 만들긴 했지만 무엇을 위한 것인지 모호하다"라고 느끼는 사람이, 기능의 전체상을 한 장의 지도로 파악할 수 있다.

• Plan Mode를 "사용해 봤지만 장점을 모르겠다"라고 느끼는 사람이, Context Window 제약이라는 근본적인 이유를 통해 납득하고 습관화할 수 있다.

• 이전 2편(개인 PDCA 자동화 기반 / 태스크 스케줄러 × 자신만의 신문)에서 "무엇을 만들었는가"를 읽은 사람이, **그 전 단계인 "왜 그렇게 설계했는가"**를 거슬러 올라가 이해할 수 있다.

본 기사의 범위: 공식 docs의 인용 + 나의 프로젝트 구현 스냅샷(2026-05-21 시점 · 11 skills / 15 hooks / 6 agents)을 지도로 사용한다. 개별 로직(이전 2편에서 다룬 자산 운용 / PDCA 등의 내용)에는 깊이 들어가지 않고, Claude Code의 이론 부분만을 추출한다.

이 글이 부정하지 않는 것: "Claude Code를 전부 이해해야만 사용할 수 있다"라고 주장하는 글이 아니다. 직접 손을 움직이며 익히는 것도 유효한 학습 방법이며, 본 기사는 어디까지나 "미리 머릿속에 지도를 가지고 있으면 풍경이 바뀐다"라는 체험담으로서 읽어주길 바란다.

독자의 Pain Point와 나의 출발점

독자가 지금 마주하고 있을 법한 방황: .claude/ 하위 디렉토리를 "일단 만들긴 했지만 무엇을 위한 것인지 모호함", Plan Mode를 "사용해 봤지만 장점을 모르겠다", "애초에 사용하지 않고 구현을 요청하고 있다" — Claude Code를 다루기 시작했을 무렵의 흔한 방황.

나의 출발점: 나 또한 처음에는 "디렉토리는 공식 docs의 샘플대로 만들었지만, 왜 그것으로 동작하는지 모르겠다", "Plan Mode도 사용하지 않고 구현을 요청해서, 올라온 코드를 몇 번이고 다시 쓰고 있었다"라는 상태로 1개월을 달렸다. 동작은 하지만 납득이 가지 않는, 그런 답답함이 계속 있었다.

배운 것: 공식 docs를 다시 읽으며 깨달은 것은 **"근본적인 제약은 단 하나이며, 거기서부터 모든 것이 역산되어 나온다"**라는 골격이었다. 이 골격을 한 장의 지도로 만든 것이 본 기사이다.

필자 프로필

결론 먼저 보기 — 한 장으로 보는 이론편의 전체상

결론 먼저 보기 — 한 장으로 보는 이론편의 전체상

🎯

내일부터의 한 수: 코드를 작성하게 하기 전에, 납득한 뒤에 Normal Mode로 구현한다. 자세한 내용은 section 5로. Shift+Tab으로 Plan Mode로 전환하여 먼저 계획을 출력하게 한다.

1. 근본 제약 — Context Window (대화 바구니)는 유한하다

Claude에게는 "한 번의 대화에서 기억할 수 있는 양"에 상한이 있다. 이를 Context Window (= 대화 바구니)라고 부른다. 대화 이력, 읽은 파일, 커맨드 결과, 도구 정의 — 이 모든 것이 이 바구니에 들어간다.

공식 문서의 한 구절:

Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills.

(베스트 프랙티스의 대부분은 "대화 바구니가 금방 차고, 차오를수록 성능이 저하된다"라는 하나의 제약에서 도출된다)

즉, "바구니를 어떻게 절약할 것인가" = "Claude Code를 어떻게 설계할 것인가"와 거의 같은 의미가 된다. 이 하나의 제약으로부터, 후술할 스펙 주도 방식, 3계층 사양, .claude/ 하위의 역할 분담까지 모든 것이 역산되어 도출된다 (하나의 이유로부터 모든 것이 나온다는 관계).

1.1 「갑작스러운 코드 작성」이 대화 바구니를 파괴하는 메커니즘

공식은 명확하게 기술하고 있다:

Letting Claude jump straight to coding can produce code that solves the wrong problem.

(Claude가 곧바로 코딩에 뛰어들게 하면, 잘못된 문제를 해결하는 코드가 생성될 수 있다)

무슨 일이 일어나는지 도식화하면:

요건을 계획 단계에서 제대로 고정하면, 구현은 스펙을 보며 일직선으로 달릴 수 있다. 수정 루프가 발생하지 않으므로 바구니가 오염되지 않는다. 스펙 주도 방식은 이 순환 고리의 "입구"를 막는다.

1.2 나의 시행착오 — Plan Mode와 CLAUDE.md로 두 번 고생한 이야기

Claude Code를 본격적으로 다루기 시작한 초기에, 나 자신도 이 "근본 제약"에 정면으로 충돌하는 시행착오를 두 차례 겪었다. 원리로부터 역산하여 깨닫는 것은 어려웠고, 둘 다 직접 고생해 본 뒤에야 "공식에서 context window 제약이라고 말하는 것이 바로 이런 것이었구나"라고 납득할 수 있었던 경험이었다. 같은 함정에 빠지는 사람이 한 명이라도 줄기를 바라는 마음으로 기록해 둔다.

시행착오 1: Plan Mode를 사용하지 않고 구현 직행 → 2주간의 수정 루프

현상: 처음 몇 주 동안, "설계는 머릿속에서 고정하고 나머지는 Claude에게 코드를 쓰게 한다"라는 직구 방식의 사용법을 택했다. 당연하게도 올라오는 코드는 요건과 조금씩 어긋나 있었고, "여기는 틀렸다", "이쪽도 어긋났다"를 반복하는 사이 대화 바구니가 수정 이력으로 가득 찼다. Claude가 바로 직전의 수정 지시를 잊어버리거나, 같은 수정을 두 번 요청해야 하는 사고도 발생했다. 그야말로 위의 "악순환의 도식" 속에서 2주 동안 뱅뱅 돌고 있었다.

원인: 머릿속에서 설계가 고정되면 구현만 맡겨서 시간을 단축할 수 있다고 과신했다. 실제로는 머릿속의 설계는 요건의 세부 사항이 언어화되지 않은 "임시 지도"였으며, 코드를 착수하고 나서야 비로소 어긋남이 발견되는 구조였다.

대처: Shift+Tab

Shift+Tab을 2번 눌러 Plan Mode를 기본값으로 설정하는 규칙으로 전환했다. 구현을 요청하기 전에 반드시 계획 문서(Plan Document)를 생성하게 하고, 사람이 읽었을 때 위화감이 있다면 계획 단계에서 수정한다. 코드에 발을 들이기 전에 수정 루프의 입구를 막는 것만으로도, 동일한 기능이 완성될 때까지 걸리는 대화의 왕복 횟수가 체감상 절반 이하로 줄어들었다.

교훈: 머릿속의 설계는 계획 문서로 써 내려가기 전까지는 "가설"이다. 쓰기 전에 구현에 착수하면, 그 차이(diff)가 대화 버킷(Conversation Bucket)에 수정 이력으로서 흘러 들어간다.

동일한 기능 완성까지 필요한 대화 왕복 횟수 (체감치):

Plan Mode 미사용 [████████████████████████] 100% (기준)
Plan Mode 기본값 설정 후 [████████████ ] 50% ✅

※ 정확한 왕복 횟수를 기록하지는 않았으나, "동일한 기능을 만드는 데 절반의 대화만으로 충분하다"는 체감을 시각화한 것이다.

멀리 돌아간 사례 2: CLAUDE.md에 너무 많이 채워 넣어 매 세션이 무거워짐

현상: "프로젝트 전체에 적용되는 규칙은 CLAUDE.md에 적는다"라는 원칙을 너무 성실하게 지킨 결과, 규약·절차·지식·경위·아이디어까지 전부 CLAUDE.md에 쌓여갔다. 정신을 차려보니 CLAUDE.md는 수천 자급이 되어 있었다. 세션 시작 시점에 이미 대화 버킷의 적지 않은 비율을 소비하고 있는 상태가 되었고, 본론에 들어가기도 전에 초반 지시 사항이 희석되기 쉬운 체질이 만들어졌다.

원인: "CLAUDE.md = 프로젝트 공통 규칙 저장소"라는 공식 설명을 직역하여, 규칙처럼 보이는 것은 전부 CLAUDE.md에 두는 운용 방식을 택했다. SKILL.md의 존재는 알고 있었지만, "매 세션마다 자동으로 읽힌다는 안심감"을 우선시하여 CLAUDE.md로 계속 몰아넣은 것이 치명적인 실수였다.

대처: CLAUDE.md를 "절대로 잊으면 안 되는 규칙에 대한 포인터 집합"으로 다시 압축하고, 상세 내용은 SKILL.md나 docs/*.md로 오프로드(Offload)했다. CLAUDE.md는 인덱스(Index) 역할을 하고, 본문은 필요할 때만 로드(On-demand)하는 역할 분담을 구현했다. 이는 이후 Section 3 "사양의 3계층 모델"의 출발점이기도 하다.

교훈: "규칙 같은 것" ≠ "매번 읽어야 하는 것". 읽기 빈도와 내용을 분리하여 설계하라.

2가지 사례의 공통점 — "갑자기 달리는 것"이 가장 비용이 많이 든다

두 사례 모두 본질은 같다. 바로 **"머릿속에 지도를 먼저 그리지 않고, 곧바로 달리기 시작했다"**는 점이다. Plan Mode를 건너뛰고 코드로 돌진하는 것도, CLAUDE.md에 모든 것을 채워 넣고 개별 최적화로 달리는 것도, 결국은 대화 버킷을 미리 결제하는 것을 게을리한 대가를 나중에 치르는 구조다. "먼저 지도, 나중에 발" — 이 글의 골격은 바로 이 교훈 그 자체이기도 하다.

2. 스펙 주도(Spec-driven)의 4단계 — Explore → Plan → Implement → Commit

공식에서 권장하는 진행 방식은 **"읽기 전용 모드에서 사양을 확정한 후, 쓰기 모드로 승격한다"**는 2상 구조로 되어 있다. 전반부 2단계(Explore → Plan)는 Shift+Tab을 2번 눌러 실행하는 Plan Mode에서 수행되며, 파일을 읽고 관련 부분을 파악하여 계획을 문장화하는 단계에서 멈춘다. Claude는 Write / Edit도 rm / mv도 사용할 수 없으므로, 이 단계에서 아무리 다시 써도 코드는 단 한 줄도 생성되지 않는다. 사용자가 계획에 납득하고 나서야 다시 한번 Shift+Tab을 눌러 Normal Mode로 전환하여 후반부 2단계(Implement → Commit)로 진입한다.

이 방식이 효과적인 이유는 수정 비용이 가장 저렴한 단계에서 요구사항의 어긋남을 제거할 수 있기 때문이다. 코드를 작성한 뒤에 "이게 아니다"라는 말을 들으면, 작성한 코드와 그 수정 이력이 대화 버킷에 쌓여간다. 반면 문장 단계에서 "이게 아니다"라는 말을 들었을 때는 계획 문서를 다시 쓰는 것만으로 충분하다.

2.1 Plan Mode의 정체

• Shift+Tab을 통해 4가지 권한 모드를 순차적으로 전환할 수 있다: Normal(일반) → Auto-accept(승인 다이얼로그를 자동으로 OK 하는 모드) → Plan(읽기 전용) → 다시 Normal로 복귀
• Plan Mode에서는 Write / Edit를 사용할 수 없으며, Bash 또한 읽기 계열만 가능하다 (cat / ls는 가능, rm / mv는 불가능)
• Claude가 AskUserQuestion(선택지를 제시하며 사용자에게 질문하는 내장 도구)을 사용하여 적극적으로 요구사항을 묻게 된다

2.2 '완료 판정 기준'을 사양에 작성하기 — 가장 강력한 지렛대

공식 문서에서

이 3계층 운영에서 효과를 발휘하는 것은 **「아래에서 위로의 승격」**이다. 태스크 중에 작성한 C 중 재사용할 수 있는 것을 B로 격상시키고, B의 규약 중 모든 프로젝트에 적용되는 것을 A로 격상시킨다. 처음부터 A를 만들려 하지 말고, C에서 몇 번 실행해 본 경험을 통해 키워나가는 것이 읽기 비용(Reading Cost)과 지식량의 균형을 맞추는 요령이다.

CLAUDE.md

(영속 · 항상 읽힘)

3.1 계층 A:

• 역할: 프로젝트 전체에 적용되는 「넓고 얕은 규칙」
• 읽히는 방식: 세션이 시작될 때마다 자동으로 읽힘
• 작성해야 할 것: 코딩 규약 (Coding Convention) / build & test 명령어 / 설계 판단 / 절대 변경해서는 안 되는 규칙
• 작성하지 말아야 할 것: 태스크 고유의 세부 절차 / 거대한 레퍼런스 / 희망 사항이나 목표

공식 경고:

If Claude already does something correctly without the instruction, delete it.

(지시를 쓰지 않아도 Claude가 올바르게 수행할 수 있다면, 그 지시는 삭제하라)

즉, "Claude가 가만히 둬도 올바르게 수행하는 것을 CLAUDE.md에 적는 것은 그저 버킷(Bucket)의 낭비일 뿐이다". 앞서 언급한 우회로 2 (section 1.2)에서 썼듯이, 나의 CLAUDE.md는 절대 잊으면 안 되는 규칙에 대한 포인터 집합으로 압축하고, 상세 내용은 각각 별도의 파일로 오프로드(Offload)하고 있다. 이것이 상세 정보의 on-demand 로드를 실현하는 설계이다.

SKILL.md

(필요할 때만 읽힘)

3.2 계층 B:

• 역할: 특정 태스크에 필요한 「좁고 깊은 절차서」
• 읽히는 방식: description (= 스킬의 자기소개 문구)만 항상 컨텍스트 (Context)에 있으며, 본체는 호출되었을 때만 읽힘
• 작성해야 할 것: 단계별 절차 / 해당 태스크 고유의 지식 / 출처 · 소스

이것이 Progressive Disclosure (단계적 공개 = 필요해지기 전까지는 보여주지 않음)라는 메커니즘이다.

SKILL.md 파일 도입부의 메타 정보 (frontmatter)는 사양의 제어층으로서 작동한다:

이 부분은 오해하기 쉽다: SKILL.md는 "문서"가 아니라 **읽히는 순간 그에 따라 움직이는 실행 가능한 사양 (Executable Specification)**이다.

3.3 계층 C: Plan Mode의 출력 (그때만 사용)

• 역할: 해당 태스크 1회 한정의 구현 계획
• 읽히는 방식: 대화 컨텍스트 (Context)에 그대로 남음 (길어지면 요약될 수도 있음)
• 영속화: "이것은 나중에 또 쓰겠다"고 판단되면, 종료 후에 SKILL.md나 CLAUDE.md로 격상시킨다

.claude/ 하위 기능 체계 — 7개 디렉토리 지도

4. .claude/ 하위는 공식 기능과 1 대 1로 대응한다. 나의 프로젝트 2026-05-21 시점의 스냅샷을 지도로 사용한다.

📝
숫자는 시기에 따라 변동된다: 상기 건수 (11 skills / 6 agents / 15 hooks)는 2026-05-21 시점 기준이다. Claude Code의 기능 추가나 프로젝트의 성장으로 변하기 때문에, 본 아티클에서는 설계 사상만을 가져가길 바란다.

skills/

— 절차서의 본체

4.1 공식 정의:

Skills는 Claude의 능력을 확장하는 지침(instructions), 스크립트(scripts), 리소스(resources)의 묶음입니다.

(Skill은 Claude의 능력을 확장하는 「지침·스크립트·리소스의 묶음」)

점진적 공개 (Progressive Disclosure)의 실례: description만 항상 컨텍스트 (context)에 배치하고, 본체는 호출될 때만 로드합니다. 하나의 「허브(중심)」가 되는 스킬(예: 매일 아침 정해진 시간에 실행되며, 그날의 상황에 따라 다른 스킬들을 순차적으로 호출하는 종합 스킬)을 만들어, 거기서부터 다른 스킬들을 순차적으로 호출하는 구조로 만들면, 각 스킬의 description만 컨텍스트에 상주하고 본체는 필요할 때만 로드됩니다 (버킷 효율이 좋습니다).

agents/

— 별도의 버킷에서 작업하는 「분신」

4.2 공식 정의:

다시 참조하지 않을 검색 결과, 로그, 또는 파일 내용으로 인해 메인 대화가 넘쳐날 것 같은 부수적인 작업에는 서브에이전트 (subagent)를 사용하십시오. 서브에이전트는 자신의 컨텍스트에서 해당 작업을 수행하고 요약본만 반환합니다.

(다시 보지 않을 검색 결과·로그·파일 내용으로 메인 대화가 채워질 것 같을 때는 subagent를 사용하라. subagent는 자신의 버킷에서 작업하고 요약만 반환한다)

용도는 크게 2가지 (공식 분류가 아닌, 본인의 운영상 구분):

• 감사용 (auditor): 부모 Claude가 낸 결과를 독립된 컨텍스트에서 재검토. 판정을 「다른 머리」로 검증함으로써 판단의 편차를 줄임
• 위임용 (producer): 대량의 WebFetch / 검색 / 파일 읽기 등 「끝나면 요약만 남으면 되는 작업」을 자식에게 통째로 맡김. 부모 버킷의 오염을 방지

주의사항 (공식 유래):

• subagent는 subagent를 호출할 수 없음 (중첩 불가)
• 부모와 자식 간에 빈번한 상호작용이 필요한 태스크는 subagent화에 적합하지 않음
• description이 자동 위임 (auto-delegation = 부모 Claude가 「이것은 subagent에게 맡긴다」라고 자동으로 판단하는 메커니즘)의 트리거 판정에 사용됨 → 모호한 기술은 오작동을 유발함

hooks/

— 결정론적인 가드와 자동화

4.3 공식 정의:

Hooks를 사용하면 특정 라이프사이클 이벤트 (lifecycle events)에서 스크립트를 실행하여 Claude Code를 커스텀할 수 있습니다. Hooks는 결정론적 (deterministic)입니다 — Claude는 CLAUDE.md 지침을 무시할 수 있지만, hooks는 항상 실행됩니다.

(Hook은 라이프사이클 이벤트에서 스크립트를 구동하는 메커니즘. Hook은 결정론적 — Claude는 CLAUDE.md를 무시할 수 있지만, hook은 반드시 동작한다)

이것이 hook의 최대 가치: 「Claude의 판단에 의존하지 않는 강제력」.

📝

다음의 철칙은, 일단 hook을 작성하여 운영에 포함시킨 후 다시 읽어볼 때 가장 효과적인 대목입니다. 처음 읽는 단계에서는 「hook = 자동 감시자이며, Claude의 변덕에 좌우되지 않는다」는 것만 기억해도 충분합니다.

Hook 설계의 철칙:

• Hook은 「보고만」 하는 데 집중할 것: 수정 로직을 hook에 담으면 디버깅 (debug)이 어려워짐 → 탐지·통지만 수행하고, 수정은 부모 Claude에게 맡기는 것이 옳음
• PreToolUse는 exit 2로 차단(block)하고, 그 외에는 관측: hook 스크립트가 exit 2로 종료되면 해당 도구 실행은 중단됩니다 (= block). 강제성을 갖게 하는 것은 「Claude가 사고를 치기 전」의 이벤트 (PreToolUse)로만 한정하고, 그 외의 이벤트는 관측·기록에 집중할 것
• matcher를 좁게 유지할 것: hook 설정의 matcher 필드는 「어떤 도구 / 어떤 subagent에 반응할지」를 지정하는 부분 (정규 표현식으로도 작성 가능). 익숙해지기 전까지는 구체적인 이름을 직접 작성할 것 (예: investment-auditor)

와 같이 agent 명을 그대로 사용하는 것이 안전하다. .*-auditor와 같은 넓은 정규 표현식 (Regular Expression)을 사용하면, 새로운 agent를 추가하는 순간 의도하지 않은 트리거가 발생할 수 있다.

로그는: .claude/logs/에 집약
output/은 사람이 여는 리포트 전용, 로그는 hook 전용 공간

output-styles/ — 출력의 "형태"를 분리

4.4 Claude의 응답 포맷을 테마별로 전환하는 기능. SKILL.md는 "무엇을 할 것인가", output-styles는 "결과를 어떻게 쓸 것인가"를 분리하고 있다. 이는 "처리"와 "표현"의 관심사 분리 (Separation of Concerns) — 두 가지를 섞으면 skill이 비대해진다.

🪧

만드는 타이밍: 동일한 skill 결과물을 서로 다른 대상(사내 보고 / Zenn 기사 / 터미널 표시 등)에게 나누어 보여주고 싶어졌을 때 처음 만들면 된다. 초기 몇 개의 skill 단계에서는 불필요한 경우가 많다.

rules/ — 공통된 작은 조각들

4.5 여러 SKILL에서 참조되는 짧은 정형 문구(면책 문구 등)를 분리하여 보관. SKILL.md에 복사해서 붙여넣으면 수정 누락의 온상이 되기 때문에, rules/로 분리하는 것이 정답이다.

🪧

만드는 타이밍: 동일한 면책 문구·정형 템플릿이 2개 이상일 때가 분리 신호다. 단 한 곳에서만 사용하는 조각은 당분간 SKILL.md에 복사해서 붙여넣어도 좋으며, SKILL.md 내에 남겨두어도 괜찮다.

logs/ — hook의 출력 대상

4.6 Hook이 출력하는 로그를 집약하는 장소. output/는 사람이 읽는 리포트, logs/는 hook이 쌓아두는 운용 로그라는 역할 분담.

🪧

무엇을 둘 것인가: 사람은 평소에 직접 열어보지 않지만, 운용 추적에 필요한 파일(hook의 탐지 이력·실패 로그 등)은 이곳에 둔다. 반대로 "독자에게 보여줄 리포트"는 output/에 둔다.

settings.json / settings.local.json — 권한과 환경

4.7 공식 계층 (위에서부터 우선순위가 높음):

5. 내일부터의 행동 — 단 하나

내일부터의 한 수는 시간축이 다른 3가지를 연쇄시키는 형태로 구성되어 있다. 오늘 5분 → 1주일 30~90분 → 월 단위의 지속적 관찰과 같이, 점진적으로 투입하는 시간과 사정거리를 넓혀가는 구조다. 중요한 것은 3가지가 독립된 제안이 아니라, 이전의 습관이 다음 단계의 소재를 만들어낸다는 점이다:

• 오늘 (🌱 씨뿌리기): Plan Mode를 기본값으로 설정함으로써, 매 태스크마다 "계획 문서"라는 결과물이 생겨나기 시작한다.
• 1주일 (🌿 정리): 기존의 SKILL.md