대부분의 사람들은 CLAUDE.md를 프롬프트 파일처럼 취급합니다.
그것이 실수입니다.
Claude Code가 저장소에 사는 시니어 엔지니어처럼 느껴지길 원한다면 — 파일 접근이 있는 챗봇이 아니라 — 프로젝트에 구조가 필요합니다. Claude는 항상 4가지가 필요합니다: 왜(시스템이 무엇을 하는지), 지도(어디에 무엇이 있는지), 규칙(무엇이 허용되는지), 그리고 워크플로(작업이 어떻게 이루어지는지).
이것을 가능하게 하는 5개의 계층입니다.
1. CLAUDE.md — 저장소 메모리 (짧게 유지)
이것이 북극성 파일입니다. Claude가 프로젝트에 진입할 때 처음 읽는 것이며, 이후 모든 것의 톤을 설정합니다.
하지만 대부분의 팀이 여기서 잘못 갑니다: CLAUDE.md를 지식 덤프로 만듭니다. 아키텍처 문서, 코딩 표준, API 참조, 배포 절차 — 모두 한 파일에 cram.
결과? 노이즈가 너무 많아 모델이 중요한 컨텍스트를 놓치기 시작합니다.
CLAUDE.md를 세 가지에 집중시키세요:
- 목적 — 이 시스템은 왜 존재하는가?
- 저장소 지도 — 무엇이 어디에 사는가?
- 규칙과 명령 — 무엇이 허용되고, 무엇이 아닌지, 그리고 작업은 어떻게 이루어지는가?
그게 전부입니다. 나머지는 아래 계층 중 하나에 속합니다.
2. Skills — 재사용 가능한 전문가 모드
매 세션마다 지침을 다시 작성하는 것을 멈추세요.
Claude Code skills(.claude/skills/ 또는 ~/.agents/skills/)는 일반 워크플로를 재사용 가능한 모듈로 패키징하여 Claude가 온디맨드로 로드하게 합니다. 전문가 모드로 생각하세요:
- 코드 리뷰 체크리스트
- 리팩터 플레이북
- 릴리스 절차
- 디버깅 흐름
결과는 세션과 팀원 간의 일관성입니다. 스킬이 잘 구조화되어 있으면, Claude는 단순히 코드를 생성하는 것이 아니라 — 팀의 실제 프로세스를 따릅니다.
OpenClaw 또는 유사한 에이전트 프레임워크를 사용 중이라면, 스킬은 더욱 강력해집니다. 스크립트, 참조 문서, 자산을 어떤 에이전트든 가져갈 수 있는 휴대 가능한 패키지로 번들링할 수 있습니다.
스킬 생성 도구가 어떻게 진화하는지에 대해 더 알고 싶다면, Anthropic의 스킬 크리에이터와 Google의 Workspace CLI에 대한 최근 글을 보세요.
3. Hooks - 잊지 않는 가드레일
모델은 잊습니다. 훅은 그렇지 않습니다.
Claude Code hooks는 Claude가 특정 작업을 수행하기 전이나 후에 자동으로 발생하는 결정적 액션입니다. 반드시 매번 일어나야 하는 것들을 위해 사용하세요:
- 파일 편집 후 포매터 실행
- 핵심 모듈 변경 시 테스트 실행
- 안전하지 않은 디렉터리 차단(auth, billing, migrations)
구분이 중요합니다: 프롬프트는 제안입니다. 훅은 보장입니다. 프롬프트에서 “src/auth/ 편집 후 항상 테스트 실행"이라고 Claude에게 말하면, 세 번째 편집 즈음에는 잊을 수 있습니다. 훅으로 연결하면 자동입니다.
4. Docs - 점진적 컨텍스트
Claude가 필요할 수 있는 모든 것으로 프롬프트를 부풀리지 마세요. 대신, 진실이 어디에 있는지 Claude에게 지도를 주세요:
- 아키텍처 개요 — 시스템 설계, 데이터 흐름, 인프라
- ADRs(Architecture Decision Records) — 왜 그 선택을 했는지
- 운영 런북 — 배포, 디버그, 복구 방법
Claude는 온디맨드로 파일을 읽는 데 능숙합니다. 모든 세부 사항을 미리 알 필요가 없습니다 — 어디를 봐야 하는지 알 필요가 있습니다. 잘 조직된 docs/ 디렉터리는 Claude가 정확히 관련 있을 때 컨텍스트를 끌어올 수 있게 합니다.
5. 위험한 모듈을 위한 로컬 CLAUDE.md
이것이 대부분의 팀이 완전히 놓치는 계층입니다.
코드베이스의 날카로운 모서리 근처에 작고 집중된 CLAUDE.md 파일을 두세요:
src/auth/CLAUDE.md
src/persistence/CLAUDE.md
infra/CLAUDE.md
이 파일들은 모듈별 함정, 제약, 경고를 포함합니다. Claude가 src/auth/에서 작업할 때, 인증 특정 가이드 — 토큰 회전 특성, 세션 처리 엣지 케이스, “이 함수를 수정할 때 마이그레이션도 업데이트” 경고 — 를 자동으로 봅니다.
이것이 루트 CLAUDE.md를 부풀리지 않고 외과적 정밀도를 얻는 방법입니다.
프롬프팅 너머의 구조
프롬프팅은 일시적입니다. 구조는 영구적입니다.
저장소가 이렇게 조직되면, Claude는 챗봇처럼 행동하는 것을 멈추고 프로젝트에 네이티브한 엔지니어처럼 행동하기 시작합니다. 컨텍스트를 알고, 프로세스를 따르며, 가드레일을 존중하고, 올바른 문서를 찾습니다 — 프로젝트 자체가 어떻게 작업할지 가르치기 때문입니다.
AI 코딩 CLI 환경은 빠르게 움직이고 있습니다. Claude Code, Codex CLI, Gemini CLI — 모두 에이전트 역량을 출시하고 있습니다. 하지만 진정한 가치를 얻는 팀은 최고의 프롬프트를 가진 팀이 아닙니다. 가장 잘 구조화된 저장소를 가진 팀입니다.
Kevin Kaminski는 Microsoft MVP이자 Big Hat Group의 Principal로, 엔터프라이즈 팀이 AI 에이전트, Windows 365, 현대 관리 솔루션을 배포하도록 돕습니다. AI 코딩 워크플로를 구조화하는 데 도움이 필요하시면, 연락하세요.