팀 CLAUDE.md

문제

전역 CLAUDE.md에 있는 규칙과 프로젝트 CLAUDE.md에 있어야 할 규칙이 무엇이 다른지 매번 애매합니다. 다 프로젝트 쪽에 몰아넣거나, 반대로 개인 습관을 팀 레포에 그대로 커밋합니다.

이유

경계를 가르는 기준은 “이 문장이 프로젝트를 바꿔도 여전히 참인가”입니다. 참이면 개인 CLAUDE.md, 아니면 프로젝트 CLAUDE.md입니다.

도구 사용 습관(“worktree 작업 결과는 커밋까지만 하고 원격에는 손대지 않는다”, “브라우저 자동화는 기본 도구를 먼저 쓰고, 특정 조건에서만 다른 도구로 바꾼다”)은 그 사람이 일하는 방식이지, 이 프로젝트가 요구하는 사실이 아닙니다. 프로젝트를 바꿔도 그 사람은 똑같이 일합니다.
반대로 “이 레포의 모노레포 빌드는 영향 범위만 골라 돈다”, “이 API는 폐기 예정이니 쓰지 않는다” 같은 문장은 그 레포를 벗어나면 의미가 없어집니다. 이런 것만 프로젝트 CLAUDE.md에 남깁니다.

개인 습관을 프로젝트 CLAUDE.md에 넣으면 한 사람의 도구 선호를 팀원 전체에 강요하게 됩니다. 반대로 이 레포만의 사실을 개인 CLAUDE.md에 넣으면 그 사람이 없는 세션에서는 아무도 그 규칙을 보지 못합니다.

CLAUDE.md에 쓴다고 습관이 되는 것은 아닙니다. 산문으로 적은 규칙은 조건을 아무리 구체적으로 적어도 지켜지지 않는 경우가 많습니다. 종료 코드로 강제하는 훅은 지켜지는 경우가 많습니다. 자기가 쓴 문서조차 매번 다시 읽지는 않습니다. 팀 CLAUDE.md는 자기가 쓰지 않은 문서를 여러 사람이 지켜야 하므로 산문의 구속력은 이보다 더 약하다고 보는 것이 안전합니다. 반드시 지켜야 하는 규칙이면 처음부터 훅이나 스킬 게이트로 옮깁니다.

실무적으로는 이렇게 나뉩니다.

	개인 글로벌 CLAUDE.md	프로젝트 CLAUDE.md
도구를 언제 쓰는가	O	레포마다 강제해야 하면 훅으로
세션을 어떻게 정리하는가	O	—
이 레포의 빌드·배포 순서, 금지된 API	—	O
“이렇게 하지 마라”를 반드시 지켜야 함	훅/스킬로	훅/스킬로

문체·구조 같은 CLAUDE.md 자체의 작성 규칙은 이 페이지가 다루지 않습니다. CLAUDE.md 실전 가이드를 봅니다.

예시

프로젝트 CLAUDE.md에 넣지 않는 것입니다. 개인 선호이므로 개인 전역 쪽에 남깁니다.

# ~/.claude/CLAUDE.md (개인, 전역)

## Worktree 정책
worktree에서 작업한 결과는 원격에 push하거나 PR을 생성하지 않는다.
커밋까지만 하고 종료한다.

## 브라우저 도구 선택
기본은 <도구 A>. 영상 녹화·trace·디바이스 에뮬레이션이 필요할 때만 <도구 B>.

프로젝트 CLAUDE.md에 넣는 것입니다. 이 레포에서만 참이고, 지키지 않으면 다른 사람이 사고를 냅니다.

# .claude/CLAUDE.md (프로젝트, 커밋됨)

## 이 레포의 사실
- 모노레포 pre-commit이 nx affected를 돈다. 원격 캐시가 죽으면
  NX_SKIP_NX_CACHE=true를 앞에 붙인다.
- .claude/worktrees/ 는 .gitignore·테스트 러너 exclude
  양쪽 모두에 등록돼 있어야 한다.

하지 말 것

개인 도구 선호를 프로젝트 CLAUDE.md에 커밋하기. 팀원 각자 다른 브라우저 자동화 도구나 에디터 워크플로를 쓸 수 있는데, 한 사람의 라우팅 규칙을 레포 전체 기본값으로 만듭니다.

꼭 지켜야 하는 규칙을 산문으로만 적고 끝내기. CLAUDE.md 산문은 읽히더라도 습관이 되지 않는 경우가 많습니다. 반드시 지켜야 하면 훅으로 막거나 스킬 안에 절차로 넣습니다.

같은 사실을 CLAUDE.md·스킬·위키 세 곳에 똑같은 형태로 중복하기. 형태를 다르게 가져가야 드리프트가 났을 때 어느 쪽이 최신인지 판단할 수 있습니다.

팀 CLAUDE.md

문제

추천

이유

예시

하지 말 것