CLAUDE.md를 prompt 파일로만 보면 역할이 작아진다. 더 정확히는 팀의 operating manual이다. 새 engineer, designer, PM, agent가 codebase에 들어왔을 때 “우리 팀에서는 이렇게 한다”를 알려주는 첫 번째 interface다.
예전에는 이런 지식이 senior engineer의 머릿속에 있었다. 어떤 framework를 써야 하는지, 어떤 architecture pattern을 피해야 하는지, review에서 무엇을 중시하는지, 어디까지 자동화되어 있는지. 하지만 agent가 codebase를 탐색하고 non-engineer도 code contribution을 시도하는 환경에서는 이 암묵지가 병목이 된다.
좋은 CLAUDE.md는 agent를 똑똑하게 만드는 것이 아니라 팀의 규칙을 명시적으로 만든다. 그래서 reviewer가 나중에 거절할 일을 agent가 처음부터 피한다. AI 시대 onboarding의 핵심은 더 긴 설명이 아니라 더 실행 가능한 repository instruction이다.
연결된 생각
- 20260716-claude-md-as-contributor-onboarding-infrastructure — CLAUDE.md를 contributor onboarding layer로 보는 개념.
- 20260716-domain-knowledge-as-agent-infrastructure — 암묵지를 인프라로 바꾸는 상위 개념.
- 20260704-code-explainer-docs-as-understanding-harness — 이해를 돕는 문서형 하네스.