아키텍트 Brij Kishore Pandey가 제시한 표준은 현재 Agent의 컨텍스트(context) 팽창을 막는 가장 우아한 엔지니어링 해결책입니다.

대부분의 사람들은 CLAUDE.md 파일을 단순한 프롬프트 파일로 취급합니다. 그러니 여러분의 AI가 왜 항상 코드를 마구 수정하는 바보 인턴처럼 행동하는지 이해할 수 있습니다: 코드 규약, API 형식, 비즈니스 로직을 모두 루트 디렉토리에 무작정 채워 넣습니다. 모델이 작업에 착수하기도 전에, 주의력이 몇 천 줄의 쓸모없는 설명으로 희석되어 버립니다.

Claude Code가 여러분의 코드베이스에 상주하는 숙련된 아키텍트가 되게 하려면, 더 긴 프롬프트를 작성할 필요가 없습니다. 필요한 것은 컨텍스트를 물리적으로 분해하는 이 프로젝트 해부학입니다:

1️⃣ 루트 디렉토리에는 최소한의 골격만 배치합니다 (4차원 계약): 시스템이 무엇을 하는지 목표, 파일 위치 지도, 허용/금지 규칙(Dead Rules), 그리고 작업을 완료하는 워크플로우만을 작성하고, 구체적인 코드는 절대 쌓아두지 않습니다;

2️⃣ 비즈니스 컨텍스트는 서브 디렉토리로 하향 배치합니다: 많은 사람이 Claude가 서브 디렉토리의 독립적인 메모리를 자동으로 읽는다는 것을 모릅니다. src/api와 영속화(persistence) 디렉토리에 각각 로컬 CLAUDE.md를 만들면, 모델이 어느 모듈에 들어갈지 그 매뉴얼만 읽게 됩니다;

3️⃣ 워크플로우는 .claude/skills로 캡슐화합니다: 코드 검토, 리팩토링, 배포 프로세스를 매번 말로 설명할 필요 없이, 모두 재사용 가능한 스킬로 고정하고 사용 후 제거합니다;

4️⃣ 경직된 가드레일은 .claude/hooks에 맡깁니다: 중요한 변경 전에 자동화된 검사를 강제 실행하여, 규격에 맞지 않으면 코드 레벨에서 즉시 되돌립니다. 모델의 자발성에 의존하지 않습니다.

프롬프트는 줄이고(Subtraction), 엔지니어링 구조를 늘려서(Addition), 컨텍스트의 최소성과 정확성을 유지해야만 모델이 여러분의 코드베이스 안에서 제 역할을 할 수 있습니다.

현재 여러분의 프로젝트 루트 디렉토리에 몇 천 자짜리 잡동사니 프롬프트가 채워져 있지는 않습니까?