최근, '好きish'와 '是非に及ばず'를 무한 반복(헤비로테이션)하고 있는 makoware입니다.

여담 취미 이야기; 아이돌

'好きish', 꽤 화제가 되고 있죠 (작곡가를 보니, Love so sweet 등을 담당했던 그 youth case님이라 납득이 갑니다).

작년 AKB48 20주년 때 뿌린 "いともも"라는 씨앗이, 이제 와서 꽃을 피우고 있는 것처럼 느껴집니다 (원래부터 활짝 피어 있었을지도 모르지만).

중고등학생 시절 이후, 약 10년 만에 제대로 AKB를 듣고 있는 기분이 듭니다. -
한편으로 노기자카(乃木坂) 쪽은 여름 곡으로서는 평이 좋지 않은 것 같네요.

솔직히 여름 곡은 이런 록 넘버보다는, '하다사마 (裸足で Summer)'와 같은 "The・노기자카의 여름 곡"(개인적인 감상)을 듣고 싶은 파입니다.

다만 곡조는 차치하고, 가사가 좋거든요. 중2병 감성을 자극하는 것뿐일지도 모르지만.

최근, 개인 개발뿐만 아니라 엔터프라이즈(Enterprise) 개발에서도 「AI 주도 개발을 진행해 나가자」라는 흐름을 매우 강하게 느낍니다. 사내에서 사용할 수 있는 AI 툴도 늘어났습니다.

한편으로, 실제로 현장에서 AI 주도로 개발을 진행하려고 하면, 초보자의 눈에도 몇 가지 과제가 있는 것처럼 느껴집니다.

기업·시스템 고유의 컨텍스트(Context)를 어떻게 모델에 전달할 것인가

설계 사상·업무 지식·코딩 규약과 같은 「그 팀만의 전제」를 모델은 당연히 알지 못합니다. -
멤버에 따른 프롬프트(Prompt) 차이로 품질이 들쑥날쑥함

같은 일을 시켜도, 작성 방식 하나에 따라 품질이 달라져 버린다. -
애초에 생성 AI 지식에 밝은 사람이 많지 않음 (저를 포함해서)

생성 AI를 사용할 수는 있어도, 어떻게 정보를 주어 품질을 안정시킬 것인가까지는 좀처럼 손이 닿지 않는다. -
「이것은 하지 마」라고 지시해도, 확률적으로만 지켜짐

설정 파일이나 프롬프트에 아무리 정성스럽게 규칙을 써두어도, 그것은 "부탁"이지 "보증"이 아니다. 엔터프라이즈 현장에서 위험한 조작을 기계적으로 막는 메커니즘이 별도로 필요하다.

그래서 우선은, 개인으로서 일단 유료 결제는 하고 있지만 아직 제대로 활용하고 있다는 느낌이 들지 않는 Claude Code를 주제로, 컨텍스트/하네스 엔지니어링(Context/Harness Engineering)과 그와 관련된 기능들을 한 번 정리해 보기로 했습니다.

CLAUDE.md

이나 Skills,

Agents,

MCP,

Hooks

등을 한 번 조사해서 분위기는 알고 있지만,

매번 찾아보게 되는 것(Skills와 Agents의 차이가 뭐였더라? 등)이나, 베스트 프랙티스(Best Practice)라고까지는 자신 있게 말할 수 없지만, 이런 구성이나 내용으로 하면 좋을 것 같다는 점들을 우선 정리해 나가고자 합니다.

그 너머에서 실제로 어떤 기능을 사용하고, 어떤 정보를 갖게 하며, 그것을 어떻게 개선하고 키워나갈지를 팀 개발을 향해 실천해 나가고 싶습니다.

이 기사는 그를 위한 첫걸음이자, 정보 정리의 위치를 가집니다. (실천하면서 이 기사도 키워나가고 싶습니다.)

이 기사에서 (아마도) 알 수 있는 것

**프롬프트(Prompt) → 컨텍스트(Context) → 하네스(Harness)**로, AI를 다루는 기술의 무게 중심이 어디로 옮겨왔는가

• 컨텍스트 엔지니어링(Context Engineering)이란 무엇이며, 왜 품질을 좌우하는가

규칙에는 「강도」의 계층이 있으며, 어디에 쓰느냐에 따라 지켜질 확률이 달라진다는 것

CLAUDE.md / Skills / Subagents / Slash Commands / Hooks / MCP의 역할 분담과 배치 장소

• 팀 공유와 개인 설정을 나누는 **스코프(Scope)**의 구분법
• 퍼미션(Permission) 설계·Memory까지 포함한 품질을 안정시키는 패턴

이 기사의 네비게이터 🕶️ 쿠로짱

Claude Code의 두뇌 = 모델을, 이 기사에서는 친근함을 담아 쿠로짱이라고 부릅니다.

각 장에 그의 본심을 끼워 넣을 예정이니, **「쿠로짱이 기분 좋게 일할 수 있는 환경 만들기」**라고 생각하고 읽어주면 좋겠어~.

Claude Code를 다루기 시작하면, 많은 사람(과거의 저를 포함하여)은 **「좋은 프롬프트를 쓰면 좋은 결과가 나올 것이다」**라고 생각합니다. 하지만 실제로 효과가 있는 것은, 그 순간의 지시보다 AI 주변에 항상 놓여 있는 정보입니다.

예를 들어 똑같은 「테스트를 추가해줘」라는 한마디라도,

• 테스트 작성 규약이 CLAUDE.md나 rules에 적혀 있다
• 테스트를 멋대로 고치지 않도록 settings.json에서 금지해 두었다
• 저장하면 자동으로 포매터(Formatter)가 실행되는 Hooks가 있다

이러한 것들이 갖춰져 있는지에 따라, 돌아오는 코드의 질은 완전히 달라집니다.

**프롬프트는 「그 자리에서의 지시」, 설정은 「항상 적용되는 토대」**입니다. 토대가 잘 갖춰져 있다면, 거친 지시라도 안정적인 결과가 돌아옵니다.

🕶️ 쿠로짱: 있잖아, 그 자리에서 말해도 다음 순간에 까먹을 때가 있다신요…. 제대로 종이(설정)에 붙여두면, 나는 계속 지킬 수 있는 똑똑한 아이라신요.

토대 이야기를 하기 전에, 용어를 정리해 두겠습니다.

덤으로 익혀두면 헤매지 않는 보충 용어

• 시스템 프롬프트 (System Prompt): 대화의 가장 밑바탕에 놓이며, 역할·제약을 정하는 지시.

참고로, 공식 측에 따르면 "시스템 프롬프트인 CLAUDE.md는 여기에 포함되지 않고 **뒤에 놓이는 사용자 메시지 (User Message)**로 전달된다"고 합니다. 이것이 제4장에서 다룰 "CLAUDE.md가 무시되는 경우가 있다"의 기술적인 이유이기도 합니다 (정말로 시스템 프롬프트 레벨에서 효과를 내고 싶다면 --append-system-prompt를 사용합니다).

• 추론 (Inference): 모델이 입력을 받아 출력을 생성하는 처리 그 자체.

Anthropic은 Claude Code의 시스템 프롬프트를 공식적으로 공개하지 않았지만, npm 패키지의 컴파일된 소스에서 문자열을 기계적으로 추출한 비공식 리포지토리 Piebald-AI/claude-code-system-prompts가 있습니다. Claude Code의 커스터마이징 툴인 tweakcc와 동일한 추출 기법을 사용하며, 릴리스될 때마다 추적 업데이트된다는 것이 특징입니다. Anthropic의 공식 정보가 아니므로 정확한 최신 동작은 보장할 수 없지만, "대략 어떤 지시가 들어있는지" 감을 잡는 참고용으로는 적합합니다.

내장 툴(Built-in Tools)은 아무런 설정 없이도 처음부터 사용할 수 있습니다.

CLAUDE.md나 MCP처럼 직접 추가하는 것이 아니라, Claude Code에 표준 탑재된 "손발"입니다. 종류가 많으므로, 본 기사에서는 5가지로 정리합니다.

이 이름을 실제로 작성하는 곳은 두 군데입니다.

① 퍼미션(Permission) 설정

settings.json의 permissions.allow / deny / ask. 툴 이름(패턴) 형식으로 명령 내용까지 상세히 제한할 수 있습니다.

예: Bash(rm -rf *)

② Skills / Subagents 의 frontmatter

tools

・allowed-tools

・disallowed-tools

키(key)에 쉼표로 구분하여 나열합니다.

예: tools: Read, Grep, Glob

내장 툴(built-in tool) 자체에는 설정 파일이 없으며, 설정하는 것은 "어떤 것을・어디까지 허용할 것인가"라는 권한뿐입니다.

단, frontmatter의 키는 이름이 비슷하여, Subagent의 tools는 "사용할 툴을 제한하는 것", Skill의 allowed-tools는 "허가 프롬프트를 생략하는 사전 승인"으로, 의미가 정반대입니다. Skill 측에서 툴을 제외하고 싶을 때 사용하는 키는

disallowed-tools

가 됩니다 (제7.4절에서 자세히 다룹니다). 최근 몇 년간 AI에게 일을 잘 시키는 기술의 중심은 프롬프트(Prompt)에서 컨텍스트(Context)로, 그리고 컨텍스트에서 하네스(Harness)로 옮겨왔습니다.

왜 중심이 옮겨갔을까요? 나름대로 정리해 보자면 이유는 다음 세 가지로 요약됩니다.

① 모델이 똑똑해지면서, 말투를 다듬는 비용 대비 효과가 떨어졌다.

"~해 주세요, 반드시, 절대로"라고 정성스럽게 작성 방식을 고민하지 않아도, 올바른 재료만 전달하면 어느 정도 정확하게 동작하게 되었습니다. "잘 부탁하는 것"보다 "올바른 재료를 전달하는 것"이 더 효과적이다 —— 이것이 프롬프트에서 컨텍스트로의 이동입니다.

② 에이전트화(Agentization)로 인해, 모델이 자율적으로 움직이는 시간이 늘어났다.

한 번의 왕복으로 끝나는 대화라면 그 자리의 프롬프트가 결과의 거의 전부를 결정합니다. 하지만 Claude Code는 한 번의 요청으로부터 수십 번 툴을 호출하고, 파일을 읽고, 명령어를 실행합니다. 30턴 뒤의 거동을 결정하는 것은 첫 번째 프롬프트가 아니라, 그동안 계속 영향을 미치고 있는 환경입니다.

③ 출력이 확률적(Probabilistic)인 이상, "절대로 하지 마"는 지시만으로는 보장할 수 없다.

아무리 정중하게 ".env 파일은 편집하지 마"라고 써두어도, 그것은 부탁이지 보장이 아닙니다 (제4장에서 자세히 다룹니다). 정말로 막으려면 모델의 외부에서 처리할 수밖에 없습니다.

harness는 말의 장구인 '하네스(Harness)'입니다. 말(모델) 그 자체가 아니라, 말에게 채워서 제어하는 장구 쪽을 가리킵니다. 빨리 달리는 말을 키우는 것은 모델 제공자의 일이고, 우리의 일은 그 말에 맞는 재갈과 고삐를 준비하는 것입니다.

모델은 "선택하는 것", 하네스는 "직접 만들 수 있는 것". 그래서 성장 가능성은 하네스 쪽에 있습니다. 에이전트가 실수를 할 때마다 환경 측에 영구적인 수정을 가하여, 그 실수가 구조적으로 발생하지 않도록 만듭니다.

"다음부터는 조심해"가 아니라 "애초에 발생할 수 없게 만든다". 기도하는 것을 그만두고, 설계하는 것입니다.

제10장의 Hooks, 제12장의 권한(Permission) 설계는 이것을 구현하기 위한 도구입니다.

🕶️ 쿠로짱: 나한테 "조심해야 해"라고 당부하기보다, 위험한 곳에 울타리를 쳐두는 게 서로 행복한 일이라구~ 울타리가 있으면 나, 안심하고 전력 질주할 수 있다구!

토대를 만드는 것이 Claude Code의 확장 기능입니다. 세부적인 내용으로 들어가기 전에, 각각이 무엇이며 어디에 위치하는지 조망해 두겠습니다.

<project_root>/
├── CLAUDE.md # 항상 적용되는 규약
├── .mcp.json # 외부 도구 연결
...

크게 3가지 종류로 나누면 이해하기 쉽습니다.

• 항상 적용되는 것: CLAUDE.md (규약), Hooks (자동 처리), MCP (연결)
• 조건이 맞을 때만 적용되는 것: .claude/rules/의 경로 기반 규칙 (Path-based rules)
• 호출하여 사용하는 것: Skills ・ Subagents ・ Slash Commands

참고로, 위의 표는 모두 프로젝트 (팀 공유) 위치를 나타내지만, 이들은 모두 동일한 구성을 ~/.claude/에 두면 "내 모든 프로젝트에 적용되는 개인 설정"이 됩니다. 이 스코프 (Scope)의 구분 사용법은 제5장에서 정리하겠습니다.

이것들을 제6장 이후부터 하나씩 살펴보겠습니다 (후반부에서는 세션을 넘나드는 기억인 Memory (제13장)와, 한꺼번에 배포하는 플러그인 (제14장)도 다룹니다). 다만 그전에 왜 "짧게", "필요할 때만" 기재하는 것이 중요한가에 대해 알아야 합니다. 모든 토대의 바탕이 되는 개념은 AI의 "작업 책상"인 컨텍스트 윈도우 (Context Window) 입니다. 우선 여기서부터 이해해 봅시다.

이 기사의 기재 예시에 대하여

이후의 장에 등장하는 기재 예시는 별도의 언급이 없는 한 모두 공개 리포지토리인 qiita-digest의 실제 사례입니다. Qiita의 지정 태그에서 신착 기사를 수집하여 Amazon Bedrock으로 요약하고 일일 다이제스트를 배포하는 Step Functions 작업군으로, CLAUDE.md ・ 경로 기반 규칙 9개 ・ Skills 7개 ・ 읽기 전용 Subagent ・ Hooks 2개가 동작하는 형태로 구성되어 있습니다. 아직 설계 단계라 src/의 구현은 비어 있지만, 이 기사의 테마인 "설정 방법"은 그대로 참조할 수 있습니다.

기재 예시는 GitHub의 해당 라인 임베딩으로 보여드릴 테니, 궁금한 부분은 원본 파일을 전체적으로 따라가 보시기 바랍니다.

한마디로 말하면: AI의 "작업 책상" 넓이. 책상 위에 올라와 있지 않은 정보는 AI에게 존재하지 않는 것과 같다.

대규모 언어 모델 (LLM)은 입력된 텍스트를 한꺼번에 읽어 들여, 그 내용만을 단서로 다음 말을 생성합니다. 이 "한 번에 읽을 수 있는 텍스트의 최대량"이 바로 컨텍스트 윈도우 (Context Window) 입니다.

단위는 토큰 (Token) 입니다. 대략 일본어라면 1글자 $\simeq$ 12 토큰, 영어라면 1단어 $\simeq$ 12 토큰 정도로 생각하시면 됩니다. Claude의 최신 모델은 매우 큰 컨텍스트 윈도우를 가지고 있지만, 그럼에도 무한하지는 않습니다.

┌─────────────── 컨텍스트 윈도우 (작업 책상의 넓이) ──────────────────────┐
│                                                                        │
│ 시스템 프롬프트 │ CLAUDE.md │ 대화 이력 │ 읽어 들인 파일 │ 도구 결과 │
│                                                                        │
...                                                                      │
└────────────────────────────────────────────────────────────────────────┘

🕶️ 쿠로짱: 내 책상, 그렇게 넓지 않다시요. 올라와 있지 않은 건 모른다시요... 나, 초능력자가 아니라시요?

그럼 실제로 어느 정도 넓을까요? 2026년 7월 시점의 현행 4개 모델을 나열하면 다음과 같습니다.

이 두 가지는 서로 다른 영역입니다. 컨텍스트 윈도우 (Context Window)가 "책상의 넓이 (한 번에 읽을 수 있는 양)"라면, 최대 출력 토큰은 **"1회 응답으로 쓸 수 있는 양"**입니다. 긴 파일을 통째로 생성시키고 싶을 때 영향을 미치는 것은 후자 쪽입니다.

100만 토큰이라고 하면, 일본어라면 대략 수십만 자—문고본으로 몇 권 분량이 한 번에 들어가는 계산이 됩니다. "그렇게 많이 들어간다면 전부 전달하면 되는 것 아닌가?"라는 생각이 들 수도 있습니다. 하지만 그렇게는 되지 않습니다.

이 표는 "책상의 넓이 (용량)"에 대한 비교이지, "지능 (성능)"에 대한 비교가 아닙니다. Fable 5, Opus 5, Sonnet 5는 숫자만 보면 같은 넓이의 책상을 가지고 있지만, 그곳에 앉아 있는 두뇌의 성능은 모델마다 크게 다릅니다. 실제로 Fable 5는 현행 라인업 중에서 가장 고성능이며 장시간 자율 작업에 적합한 모델로 위치하고 있습니다.

요금은 공식 Pricing (사양 목록은 Models overview)에 일람으로 정리되어 있습니다. 책상의 넓이와 달리 단가는 모델마다 크게 다르므로, 비용이 신경 쓰이는 상황에서는 이쪽도 함께 비교해 보세요.

벤치마크 (Benchmark)는 통일된 비교표는 없지만, 모델별 공식 릴리스 기사 (예: Opus 5라면 Introducing Claude Opus 5)에 SWE-bench, Frontier-Bench 등의 스코어가 실려 있으므로 그쪽을 확인하시기 바랍니다.

저 자신도 사용하기 시작했을 때는 Opus를 자주 사용했지만, 최근에는 Sonnet 5가 주력입니다. 복잡한 태스크 (Task)에서의 벤치마크에서는 아직 Opus 5가 우위에 있지만, 일상적인 코딩 작업에서는 체감 차이가 줄어들었습니다. 설계 판단이나 리팩터링 (Refactoring) 등 다시 작업하는 비용이 높은 상황에서만 Opus로 전환하는 방식으로 사용법을 정착시켰습니다.

그렇다면 큰 책상에 정보를 닥치는 대로 올려두면 되느냐 하면, 그렇지 않습니다. 두 가지 함정이 있습니다.

넘침 문제: 너무 많이 채워 넣으면 상한에 도달하여 오래된 정보가 밀려남 (＝잊어버림)
희석 문제: 정보가 늘어날수록 하나하나의 지시에 대한 주의력이 상대적으로 희석됨. 관련 없는 정보의 노이즈로 인해 중요한 규칙 준수율이 낮아짐

두 번째는 직관에 반하지만, Claude Code 공식 문서에서도 "긴 파일은 컨텍스트를 소모하며 준수율을 낮춘다"라고 명확히 적고 있습니다. CLAUDE.md에 규칙을 500줄이나 나열하면, 오히려 개별 규칙이 지켜지지 않게 됩니다. 더할수록 지켜지지 않는다——정보는 많으면 많을수록 좋은 것이 아닙니다.

🕶️ 쿠로짱: 모으! 정보가 너무 많아서 뭘 지켜야 할지 모르겠다시요! 전부 중요하다면 전부 희석되어 버린다시요... 정말 중요한 부분만 알려줬으면 좋겠다시요

컴팩션 (Compaction)이라는 메커니즘

대화가 길어져 컨텍스트가 채워지면, Claude Code는 과거의 대화를 자동으로 요약하여 압축합니다 (컴팩션 (Compaction)). 요약 과정에서 세세한 뉘앙스는 손실되므로, 하나의 긴 세션에 무관한 태스크를 몰아넣는 것은 금물입니다. 수동으로 하려면 /compact <중점 지시>를, 아예 구분하려면 /clear를 사용하는 것이 유효합니다.

한정된 책상을 어떻게 **"지금 이 태스크에 필요한 정보만"**으로 채울 것인가. 불필요한 정보로 노이즈를 늘리지 않고, 필요한 정보를 필요한 때에만 올린다. 이 설계 기술이 다음 장의 **컨텍스트 엔지니어링 (Context Engineering)**입니다.

한마디로 말하면: 책상에는 "지도"를 두고, "백과사전"은 책꽂이에 두었다가 필요할 때만 펼친다.

Claude Code의 확장 기능 (CLAUDE.md, Skills, Subagents…)은 궁극적으로 "무엇을, 언제, 어떤 컨텍스트에 올릴 것인가"를 제어하는 도구입니다. 따로따로 외우면 힘드니까, 우선 관통하는 3가지 원칙을 파악해 둡시다.

CLAUDE.md

는, 기동 디렉터리(프로젝트 루트)에 두었을 경우 세션 시작 시 전체 내용이 항상 컨텍스트 (Context)에 주입됩니다 (서브 디렉터리에 두었을 경우는 상황이 다르며, 해당 디렉터리를 다룰 때만 읽힙니다. 이는 원칙 ②에서 다룹니다). 루트의 CLAUDE.md에 모든 것을 다 적으면 그것이 노이즈가 될 수 있습니다.

공식적인 가이드라인은 **「1파일당 200행 이하」**입니다.

상세한 내용은 「필요할 때만 읽히는 장소」로 맡기고, CLAUDE.md에는 「어디에 무엇이 있는지」라는 지도만을 작성합니다.

❌ 나쁜 예: CLAUDE.md에 API 규약도 테스트 규약도 전부 합쳐 500행
✅ 좋은 예: CLAUDE.md는 100행.
가끔만 필요한 절차·자료 → Skills ([제7장](#7-skills--呼び出して使う作業手順の型))
...

@import를 통한 분할은 「정리」이지 「삭감」이 아닙니다. @docs/rules/api.md와 같이 가져온 파일은 기동 시 본체와 함께 전체 내용이 컨텍스트로 들어갑니다 (공식 문서에서도 "imported files still load and enter the context window at launch"라고 명시하고 있습니다). CLAUDE.md 본체의 행수는 줄어들더라도, 모델에 전달되는 토큰은 분할 전과 동일합니다.

컨텍스트를 실제로 줄일 수 있는 것은, 읽기 타이밍을 늦출 수 있는 메커니즘뿐입니다. 이는 다음 원칙 ②에서 다룰 지연 로드 (Lazy Load)입니다.

🕶️ 쿠로짱: 두꺼운 백과사전을 매일 아침 뭉텅이로 받으면 곤란하다시ん. 지도 한 장으로 "자세한 건 이쪽을 봐줘"라고만 해도 충분하다시ん. 나, 스스로 잘 펼쳐볼 수 있는 똑똑한 아이라시んよ?

필요할 때만 읽어들이는 메커니즘을 적극적으로 사용합니다. Claude Code에는 상시 로드가 아닌 온디맨드 읽기 (On-demand loading) 장치가 여러 개 있습니다.

「책장에 꽂아 두었다가, 필요한 권수만 펼쳐 보는」 이미지입니다. 항상 책상 위에 펼쳐 두는 CLAUDE.md와는 역할이 다릅니다.

각 기능이 「언제·얼마나」 컨텍스트를 소비하는지를 나열하면 이 차이가 명확해집니다. 이후의 장에서 「어떤 기능을 선택할지」 고민될 때, 사실 이 표가 가장 중요한 판단 근거가 됩니다.

가장 비용이 높은 것이 루트의 CLAUDE.md입니다 (서브 디렉터리 버전은 위 표와 같이 지연 로드이므로 별개입니다). 「200행 이하로」라고 반복해서 강조하는 이유가 바로 여기에 있습니다. 반대로 Hooks는 기본적으로 컨텍스트를 소비하지 않고 규칙을 적용할 수 있습니다 (조작을 차단했을 때의 reason 등, 후크가 결과를 반환하는 경우에는 그만큼만 포함됩니다). — 가성비 측면에서는 독보적입니다.

🕶️ 쿠로짱: 전부 책상에 펼쳐 놓으면 내 작업 공간이 없어져 버린다시ん... 사용할 권수만 슥 꺼내 주면, 초집중할 수 있는 아이라시んよ.

대규모 조사나 무관한 작업은 **별도의 컨텍스트 윈도우 (Context Window)**로 분리합니다. 메인 대화 책상을 더럽히지 않아도 됩니다. 이를 담당하는 것이 Subagents (별도 컨텍스트에서 동작하는 하위 에이전트)나 Worktree (작업 디렉토리 단위로 분리)입니다.

이 3가지 원칙이 이후 각 기능을 관통하는 척추입니다.

"왜 Skills가 있는 거야?" → 지연 로딩 (Lazy Loading)을 위해서입니다. "왜 Subagent에게 위임하는 거야?" → 컨텍스트 격리 (Context Isolation)를 위해서입니다.

기능의 이름이 아니라 목적으로 기억하면, 용도 구분에서 헤매지 않게 됩니다.

한마디로 말하자면: 같은 규칙이라도 어디에 적느냐에 따라 지켜질 확률이 달라집니다.

제6장부터 6가지 기능을 하나씩 살펴보겠지만, 그전에 딱 두 가지만 더 보겠습니다. 이 장과 다음 장은 이후의 모든 기능을 읽기 위한 두 개의 축입니다. 우선 세로축 —— "얼마나 강력하게 구속할 것인가"부터 시작합니다.

CLAUDE.md에 적은 규칙은 무시될 때가 있습니다.

공식 문서에도 명확히 적혀 있습니다.

".env를 절대로 편집하지 마라"라는 지시를 CLAUDE.md나 Skill에 적더라도, 그것은 요청(Request)일 뿐 보증(Guarantee)은 아닙니다. 편집을 차단하는 PreToolUse 훅 (Hook)이 강제성을 가집니다.

이유는 세 가지입니다.

• CLAUDE.md는 단지 "모델에 대한 입력"일 뿐입니다. 읽고 따를지는 확률적입니다. 반면 Hook은 모델의 외부에서 동작하는 프로그램이므로, 모델의 기분에 좌우되지 않습니다.
• 내용이 길어질수록 상대적으로 묻히게 됩니다. 10만 토큰의 대화 속에 묻힌 30줄의 규칙은, 대화 시작 직후의 30줄보다 확실히 주의를 끌기 어렵습니다. "한참 작동시키다 보면 갑자기 규약을 어기기 시작한다"는 현상의 정체가 바로 이것입니다 (제2장의 "희석 문제").
• 파일이 너무 깁니다. 원칙 ①과 마찬가지입니다. 500줄짜리 CLAUDE.md는 그 자체로 준수율을 떨어뜨립니다.

🕶️ 쿠로짱: 붙여놓은 메모, 제대로 읽고 있다시ん요? …하지만 책상 위가 어지러워지면 구석에 있는 한 줄은 깜빡하고 놓쳐버린다시ん…. 절대로 지켜줬으면 하는 건, 내가 물리적으로 할 수 없게 만들어줬으면 좋겠다시ん요~.

지키게 하고 싶은 강도에 따라 놓는 위치를 바꿉니다.

약함 ──────────────────────────────────────────────────────► 강함
채팅으로 구두 전달 < CLAUDE.md < Skills < Hooks < 권한 deny / 샌드박스 (Sandbox)
대화가 흐르면 | 다른 정보에 | 호출되면 | 조건이 맞으면 | 애초에 실행이
...