모두가 어떤 AI 모델이 가장 똑똑한지 논쟁하고 있습니다.

그동안 Claude Code 사용자의 상위 1%는 조용히 다른 무언가를 알아냈습니다:

모델이 병목 현상(bottleneck)이 아닙니다. 당신의 저장소(repo)가 병목입니다.

같은 모델. 같은 프롬프트(prompts). 한 개발자는 챗봇을 얻고, 다른 개발자는 자율 엔지니어(autonomous engineer)를 얻습니다.

그 차이는 폴더 구조에 있습니다.

나는 이것을 '최종 보스 설정(Final Boss Setup)'이라고 부릅니다.

━━━━━━━━━━━━━━━

1️⃣ 컨텍스트 사다리 (Context Ladder) (이것이 모든 것을 바꿉니다)

"CLAUDE.md에 무엇을 넣을까"라고 생각하는 것을 멈추세요.

"언제 무엇을 로드할까"라고 생각하기 시작하세요.

4단계가 있습니다:

• 모든 세션 → CLAUDE.md (매우 작으며, 항상 컨텍스트에 포함됨)
• 경로 제한(Path-gated) → rules/.md (Claude가 해당 파일들을 건드릴 때만 로드됨)
• 호출 시(On invoke) → skills/ (작업이 일치할 때 로드됨)
• 격리됨(Isolated) → 에이전트(agents) 및 워크플로우(workflows) (완전히 독자적인 컨텍스트를 가짐)

대부분의 사람들은 모든 것을 1단계에 쏟아붓습니다.

그러고는 프로젝트가 커짐에 따라 왜 Claude가 더 멍청해지는지 의아해합니다.

당신은 문서를 작성하는 것이 아닙니다. 메모리 계층 구조(memory hierarchy)를 설계하는 것입니다.

━━━━━━━━━━━━━━━

2️⃣ 요청됨(ASKED) vs 강제됨(FORCED) (아마추어와 프로를 가르는 경계선)

CLAUDE.md와 rules = 요청됨(ASKED).
Claude가 읽고 대개 따르는 지침(Instructions)

Hooks와 설정(settings) = 강제됨(FORCED).
permissions.deny는 Claude가 동의하든 아니든 rm -rf를 차단합니다.

테스트 방법은 다음과 같습니다:

"포매터(formatter)를 실행해 주세요" → 요청됨. 90%의 확률로 작동합니다.
모든 편집을 포맷하는 PostToolUse hook → 강제됨. 100%의 확률로 작동합니다.

90%로는 충분하지 않은 모든 것 — 비밀 정보(secrets), 마이그레이션(migrations), 운영 환경(prod) — 은 절대 마크다운(markdown) 파일에 있어서는 안 됩니다.

스타일을 위한 가이드는 요청(Guidance)으로, 생존을 위한 집행은 강제(Enforcement)로 하세요.

━━━━━━━━━━━━━━━

3️⃣ 라우팅 규칙 (Routing Rule) (어딘가에 문신으로 새겨두세요)

당신이 반복하는 모든 작업은 정확히 하나의 슬롯에 들어맞습니다:

• 리서치(Research) → 서브에이전트(subagent) (독자적인 컨텍스트, 깔끔하게 보고함)
• 절차(Procedure) → 스킬(skill) (플레이북, 필요할 때 로드됨)
• 보장(Guarantee) → hook (매번 발생하며, 재량권이 없음)

프롬프트에서 워크플로우를 반복하고 있나요? 그것은 당신이 아직 작성하지 않은 스킬(skill)입니다.
Claude에게 테스트를 실행하라고 계속 상기시키고 있나요? 그것은 당신이 아직 연결하지 않은 hook입니다.
탐색(exploration) 과정이 메인 컨텍스트를 오염하게 내버려 두고 있나요? 그것은 당신이 아직 생성하지 않은 서브에이전트(subagent)입니다.

━━━━━━━━━━━━━━━

4️⃣ 스스로 로드되는 규칙들 (Rules That Load Themselves)

저평가된 파일: 경로 게이팅 (path-gating) 기능이 포함된 .claude/rules/

frontend/react.md는 Claude가 프론트엔드 코드를 건드릴 때만 컨텍스트 (context)에 들어옵니다.
api-design.md는 API 작업 시에만 들어옵니다.

당신의 컨벤션 (conventions)은 마치 적절한 순간에 바로 옆에서 지켜보는 시니어 엔지니어처럼 코드베이스 (codebase)를 따라 Claude를 따라다닙니다.

해당되지 않는 규칙에 낭비되는 토큰 (tokens)은 제로입니다.

━━━━━━━━━━━━━━━

5️⃣ 자체 메모리를 가진 에이전트들 (Agents With Their Own Memory)

아직 아무도 사용하지 않고 있는 2026년형 업그레이드:

agent-memory/ — Claude가 배운 것을 작성하면, 당신이 커밋 (commit)합니다.

당신의 디버거 에이전트 (debugger agent)는 지난달의 까다로운 레이스 컨디션 (race condition)을 기억합니다.
다음 세션에서, 에이전트는 이전 세션이 끝났을 때보다 더 똑똑한 상태로 시작합니다.

Claude가 작성하고, 당신이 커밋합니다. 팀이 이를 상속받습니다.

당신의 AI 경험이 버전 관리되는 인프라 (infrastructure)가 됩니다.

━━━━━━━━━━━━━━━

6️⃣ 위험 구역에서의 CLAUDE.md (CLAUDE.md in the Danger Zones)

글로벌 컨텍스트 (Global context)는 당신의 인증 (auth) 모듈에 지뢰가 깔려 있다는 사실을 알 수 없습니다.

그러니 문제가 발생할 수 있는 곳에 로컬 파일 (local files)을 배치하세요:

src/api/CLAUDE.md
src/payments/CLAUDE.md

Claude는 해당 디렉토리 (directories)에 진입하는 바로 그 순간에 이 파일들을 읽습니다.

경고는 위험한 순간에 나타납니다. 무시되기 십상인 4,000 토큰 전이 아니라 말이죠.

━━━━━━━━━━━━━━━

7️⃣ 황금률 (실전 경험으로부터)

• CLAUDE.md는 200라인 미만으로 유지하세요. 내용이 늘어나면 rules/로 분리하세요. 비대해지면 (Bloat) 신호가 누락됩니다.
• 실제 명령어 (npm test, build, lint 등)를 나열하세요. 그래야 Claude가 자신의 작업 내용을 검증 (verify)할 수 있습니다.
• 비밀 정보 (Secrets)는 ${ENV_VAR} 참조 형태로 유지하세요. .mcp.json에는 절대 넣지 마세요. 말 그대로 절대 안 됩니다.
• .claude/를 커밋하고 *.local.*은 .gitignore에 추가하세요. 당신의 설정은 개인적 취향이 아니라 팀의 인프라 (infrastructure)입니다.

━━━━━━━━━━━━━━━

대부분의 사람들이 놓치는 변화는 이것입니다:

프롬프트 (Prompt)는 단 하나의 대화를 개선합니다.

구조 (Structure)는 모든 팀원을 위해, 모든 대화를, 영원히 개선합니다.

프롬프팅 (Prompting)은 지능을 빌려 쓰는 것이고,

구조 (Structure)는 지능을 소유하는 것입니다.

레포지토리 (repo)를 한 번 구축해 두면, Claude는 당신의 코드베이스를 방문하는 것을 멈추고 그 안에서 살기 시작할 것입니다.