온라인의 대부분의 CLAUDE.md 예시는 한 사람이 하나의 사이드 프로젝트를 위해 작성되었습니다. 팀 파일은 다른 역할을 합니다. 모든 개발자의 Claude Code 세션이 동일한 파일을 읽기 때문에, 이 파일은 한 개인이 어떻게 일하는지보다 팀이 어떻게 작동하는지를 인코딩해야 합니다.
아래는 공유 레포지토리의 루트에 복사할 수 있는 템플릿입니다. <꺾쇠괄호> 안의 모든 내용을 교체하고, 적용되지 않는 내용은 삭제하며, 간결하게 유지하세요. 각 섹션별 참고 사항은 다음과 같습니다.
템플릿
# <프로젝트 이름>
<이 레포지토리가 무엇이며 누가 사용하는지에 대한 한 문장입니다.>
...
이것이 전체 파일입니다. 만약 여러분의 파일이 훨씬 길다면, 계속 읽어보세요.
각 섹션별 용도
Commands (명령어)
가장 빠르게 효과를 볼 수 있는 섹션입니다. 이것이 없으면 Claude Code는 명령어를 추측하고, 그럴듯한 추측(pnpm 모노레포에서 npm test, 적절한 플래그 없이 pytest)은 모든 작업에 시간을 낭비하게 만듭니다.
"Never run" (실행하지 말 것) 라인이 보이는 것보다 더 중요합니다. 데이터베이스 초기화나 배포 스크립트처럼 입력하기 쉬운 파괴적인 명령어 하나를 명시적으로 언급하는 것이 가치가 있습니다.
Layout and the reference implementation (레이아웃 및 참조 구현)
전체 폴더 트리를 설명하지 마세요. 에이전트는 그것을 읽을 수 있습니다. 목적이 분명하지 않은 폴더 이름에 이름을 붙이고, 일을 하는 올바른 방식을 보여주는 기존 파일 하나를 가리키세요.
"새로운 엔드포인트는 api/orders/의 구조를 따릅니다"라는 문구가 아키텍처를 설명하는 페이지보다 더 나은 결과를 가져옵니다. 모델들은 설명을 따르는 것보다 예시를 훨씬 더 신뢰성 있게 복사합니다.
Ownership (소유권)
팀 레포지토리에서 가장 비용이 많이 드는 에이전트 실수는 팀 경계를 넘나드는 변경입니다. 즉, 하나의 PR에서 세 팀의 코드를 건드리는 리팩토링입니다. 소유권 표를 사용하면 에이전트가 경계를 감지하고 작업을 분할하거나 먼저 질문하도록 할 수 있습니다.
Rules (규칙)
짧은 명령문 형태로 규칙을 작성하세요. "스키마 변경 사항을 직접 적용하지 말 것"은 지켜집니다. "우리는 일반적으로 스키마 변경 사항이 검토를 거치기를 선호합니다"는 그렇지 않습니다.
실제로 위반될 수 있는 규칙으로 목록을 유지하세요. 아무도 어기지 않을 규칙은 중요한 내용을 희석시키는 노이즈입니다.
Standards (표준)
형용사보다 숫자가 강력하다. '깔끔하고 잘 테스트된 코드'는 아무것도 바꾸지 못한다. 하지만 '새로운 코드에 대한 80% 커버리지'와 'any 타입 없음'은 에이전트와 리뷰어 모두가 확인할 수 있다.
용어집 (Glossary)
이 섹션은 대부분의 팀이 건너뛰지만, 가장 필요한 부분이다. 에이전트가 도메인 개념에 대해 자체적인 명칭을 만들 때(예: 한 파일에서는 '고객'을 '계정 보유자'로, 다른 파일에서는 '클라이언트'로 부르는 경우), 코드베이스는 점차 일관성 없는 어휘로 채워진다. 이러한 혼란을 막기 위해, 원하지 않는 동의어까지 포함하는 짧은 용어집이 필요하다.
완료 정의 (Definition of done)
에이전트가 작업을 마쳤다고 말하기 전에 무엇을 확인해야 하는지 알려주라. 이는 '완료'라는 주장을 에이전트가 검증하는 것으로 바꾼다: 테스트 실행 여부, 린터 통과 여부, 변경 사항이 참조와 일치하는지 등.
제외할 내용 (What to leave out)
- 코드가 이미 말해주는 것들. 에이전트는
package.json과 폴더 구조를 읽을 수 있다.
- 개인적인 선호도. 톤, 상세함의 정도, 에디터 습관 등: 이러한 것은 공유 파일이 아니라 각 개발자 자신의
~/.claude/CLAUDE.md에 속한다.
- 특정 폴더에 대한 규칙. 이는 해당 폴더 안에 있는
CLAUDE.md에 넣으라. Claude Code는 그 안에서 작업할 때 이를 가져가고, 루트 파일은 읽기 쉽게 유지된다.
- 긴 산문. 섹션에 단락이 필요하다면, 그것은 문서(documentation)이다. 붙여넣기 하는 대신 링크를 사용하라.
일관성을 유지하는 방법 (Keeping it true)
팀 CLAUDE.md가 실패할 때는 조용히 실패한다: 한 가지 규칙을 말하고, 코드베이스는 이미 다음 단계로 나아가 버렸으며, 에이전트는 자신 있게 오래된 규칙을 따른다. 이러한 상황을 방지하는 두 가지 습관이 있다:
- 코드처럼 검토하라. 변경 사항은 PR(Pull Request)을 통해 진행되며, 컨벤션을 변경하는 모든 PR은 같은 PR에서 해당 파일을 업데이트해야 한다.
- 나쁜 에이전트 제안을 파일에 대한 버그 리포트로 취급하라. 만약 규칙이 없거나 오래되어서 에이전트가 잘못된 것을 얻었다면, 코드만 고치는 것이 아니라 파일을 수정해야 한다.
팀 문서에서 시작하기 (Starting from your team's docs instead)
이 템플릿에 들어갈 대부분의 내용은 이미 팀 문서 어딘가에 존재한다: 온보딩 가이드, 엔지니어링 핸드북, 누가 무엇을 소유하는지에 대한 페이지 등. 이러한 산문을 짧은 규칙으로 바꾸는 것이 시간이 많이 걸리는 부분이다.
이것이 바로 우리가 AI Workspace Builder를 만든 이유입니다. 팀이 이미 가지고 있는 문서를 업로드하면, 15초에서 30초 만에 CLAUDE.md 파일, 각 역할별 프로필, 그리고 팀 레벨 파일을 생성합니다. 무료 체험 워크스페이스가 있으며 카드 등록은 필요하지 않습니다.
어떤 경우든 작게 시작하세요: 명령어, 하나의 참고 구현체, 그리고 팀이 가장 자주 위반하는 세 가지 규칙만으로도 충분합니다. 이것만으로도 Claude Code가 여러분의 리포지토리에서 작동하는 방식이 달라집니다.