CLAUDE.md는 새로 합류한 팀원이 필요로 할 만한 맥락을 Claude에게 제공하며, 여기에는 컨벤션, 명령어, 아키텍처, 그리고 팀에서 가장 자주 발견되는 실수들이 포함됩니다. 과거에는 사람들의 머릿속이나 위키에 머물러 있던 지식이 이제는 에이전트가 매 세션 시작 시 읽는 파일이 되며, 팀 전체가 유지 관리하고 실수가 발생할 때마다 개선해 나갑니다.
시작하기
- 전제 조건: 없음.
- 인프라: 저장소, 설치된 Claude Code, 그리고 코드베이스를 잘 아는 엔지니어 한 명.
실행 방법
- 저장소에서
/init을 실행합니다. Claude가 발견한 내용을 바탕으로 초기CLAUDE.md를 생성합니다. - 생성된 파일을 새로 합류한 팀원이 첫날에 필요로 할 내용으로 줄입니다. 빌드, 테스트, 린트 명령어, 중요한 컨벤션, 그리고 Claude가 계속 틀리는 부분을 유지하세요.
CLAUDE.md를 저장소 루트에 Git으로 커밋하여 팀 전체가 하나의 버전을 공유하고 변경 사항이 코드처럼 리뷰되도록 합니다.- 여기서는 하나의 작업 규칙이 도움이 됩니다. Claude가 같은 실수를 두 번 하면, 그 수정 내용을
CLAUDE.md에 반영합니다. - 한 페이지 이내로 유지하세요. Claude는 세션 시작 시 전체 내용을 읽으므로, 오래되어 쓸모없는 내용은 아무런 이점 없이 컨텍스트를 차지할 뿐입니다.
실제 예시
이 CLAUDE.md는 한 보험사의 고객 포털 저장소에 속해 있습니다. 청구 정보를 보관하는 오래된 내부 시스템은 claims-core이며, intent/는 각 변경 사항에 대한 계획 파일을 보관합니다.
CLAUDE.md:
markdown
# Claims portal
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
- Run: make run (portal on :3000, claims-api on :8000)
## Conventions
- claims-api is Python 3.12 and FastAPI. portal is TypeScript and React.
- Every endpoint needs a test in claims-api/tests.
- Dates cross the API as ISO 8601, never as formatted text.
## Architecture
- portal/ is the customer site, claims-api/ is its backend, and
intent/ holds the intent.md, spec.md and plan.md for each change.
- Only claims-api talks to claims-core. The portal never calls it.
- claims-core allows 50 requests a second. Cache reads; never poll it.
## Things Claude gets wrong
- Do not log request or response bodies in claims-api; they can hold PII.
- Do not bump dependency versions; the platform team owns them.거버넌스 고려 사항
CLAUDE.md는 버전 관리되므로, 에이전트가 따르는 지침을 검토하고 감사할 수 있습니다. 팀 컨벤션은 이 파일을 통해 적용되며, 파일에 대한 변경 사항은 Git 기록에 남고, 코드 소유자가 PR 리뷰에서 해당 변경 사항을 승인합니다.
측정 방법
- 선행 지표:
CLAUDE.md가 잡아냈어야 할 실수를 Claude가 얼마나 자주 반복하는지.CLAUDE.md에 대한 수정이나 변경 사항은 Git 기록 내에서 추적되어야 합니다. - 후행 지표: PR 기록을 기준으로, 팀에 새로 합류한 구성원이 첫 PR을 병합하기까지 걸리는 시간.