Claude Code를 잘 쓰려면 “모든 지시를 CLAUDE.md에 넣기”보다 지시 전달 채널을 나눠야 한다. Anthropic은 Claude Code 제어 방법을 CLAUDE.md, Rules, Skills, Subagents, Hooks, Output styles, system prompt append로 구분한다.
어떤 지시를 어디에 둘까
| 방법 | 적합한 용도 | 주의점 |
|---|---|---|
루트 CLAUDE.md | 빌드 명령, 저장소 구조, 팀 공통 규칙 | 항상 컨텍스트를 차지하므로 길어지면 비용 증가 |
하위 CLAUDE.md | 특정 디렉터리 규칙 | 해당 경로를 읽을 때만 필요 |
| Rules | 파일 패턴별 제약, 팀 정책 | 상시 규칙은 꼭 필요한 것만 둔다 |
| Skills | 반복 절차, 도메인별 플레이북 | 설명(description)이 정확해야 잘 발동한다 |
| Subagents | 병렬 조사, 격리된 분석, 긴 로그 점검 | 최종 요약만 메인 세션에 돌아온다 |
| Hooks | 린트, 백업, 승인 차단 같은 결정론적 자동화 | 모델 지시가 아니라 실행 이벤트로 동작한다 |
| Output styles | 역할·응답 스타일 전환 | 시스템 프롬프트 수준이므로 무겁다 |
실무 패턴
- 저장소 공통 규칙은 짧은
CLAUDE.md에 둔다. - 긴 체크리스트와 절차는 Skills로 분리한다.
- 보안상 반드시 지켜야 하는 실행 제약은 Hooks나 외부 검증으로 옮긴다.
- 큰 조사 작업은 Subagents로 격리해 메인 컨텍스트를 보존한다.
- 개인 취향과 팀 정책을 섞지 않는다. 팀 정책은 repo, 개인 취향은 user-level 설정에 둔다.
관련 문서
- claude-code — Claude Code 개요
- agent-skills — 스킬 시스템의 구조와 작성법
- claude-code-tips-project-structure — 프로젝트 구조 지침으로 AI 코딩 품질 높이기
참고 자료
- Steering Claude Code: skills, hooks, subagents and more — Claude Blog (2026-06-22)