팀 CLAUDE.md를 git으로 통합·공유하는 방법 (Claude Code)

문제: local마다 다른 Claude

• 개발 제한이 사람마다 다르다. 누구 CLAUDE.md엔 “커밋하지 마”가 있고, 누구 건 없어서 Claude가 알아서 커밋한다.
• 규칙이 제각각이다. 네이밍, 주석 언어, 테스트 실행 여부가 파일마다 달라서 같은 프로젝트인데 결과물 스타일이 맞지 않는다.
• 오래돼서 틀린 내용이 남는다. 프로젝트 초기에 한 번 쓰고 아무도 건드리지 않아, 이미 사라진 폴더 구조나 옛 컨벤션이 그대로 있다.
• 찾은 지식이 퍼지지 않는다. 누군가 고생 끝에 찾은 우회법이 그 사람 local 파일에만 있어서, 옆 사람은 같은 고생을 처음부터 다시 한다.

마지막이 특히 아팠다. 원문에도 시니어 셋이 이미 아는 우회법을 주니어가 두 시간 동안 다시 헤맸다는 이야기가 나온다. 지식이 개인 파일에 갇혀 있던 딱 그 상황이었다.

전환점: 짧은 게 이긴다

처음엔 팀원들 CLAUDE.md를 전부 합치면 완벽한 파일이 나올 줄 알았다. 그렇게 하니 금방 몇천 줄이 됐고, 원문이 딱 그 지점을 짚었다.

둘 다 짧은데 더 잘 됐다. CLAUDE.md는 대화를 시작할 때마다 통째로 읽힌다. 파일이 크면 질문하기도 전에 토큰을 쓰고, 컨텍스트가 길어질수록 앞쪽 지시를 놓치는 현상(context rot)도 심해진다. 원문이 인용한 NoLiMa 벤치마크에서는 32k 토큰 구간에서 모델 12개 중 11개의 회상 정확도가 50% 아래로 떨어졌다.

그래서 방향을 합집합에서 교집합과 다이어트로 바꿨다.

When implementing authentication, always ensure you follow security best practices including input validation, proper error handling, secure token storage...

Auth: validate inputs, handle errors securely, follow auth/ patterns

같은 내용인데 토큰이 확 준다. 이 원칙으로 팀원 파일에서 겹치는 문장, 혹시 몰라 넣은 방어적 지시, 이미 안 쓰는 규칙을 걷어 냈다.

7가지 안티패턴에 내 경험 대 보기

원문의 일곱 가지를 그대로 나열하기보다, 합치면서 실제로 걸린 것 위주로 다시 묶었다.

이 중 통합과 가장 맞닿은 세 가지를 좀 더 풀어 본다.

혼자만의 설정: git 공유가 이 작업의 전부

원문이 인용한 Boris의 말이 이렇다. “Anthropic은 각 팀이 CLAUDE.md를 git에 두고 관리한다.” 내가 한 작업이 이 문장 하나로 요약된다. 구조는 이렇게 잡았다.

project-root/
├── CLAUDE.md         # 공유, git에 커밋 (팀 공통 규칙)
├── CLAUDE.local.md   # 개인 취향, .gitignore
└── .claude/
    └── commands/     # 팀 슬래시 커맨드

핵심은 팀 공통과 개인 취향을 파일로 나눈 것이다. 팀 규칙은 CLAUDE.md에 올려 모두가 같은 걸 쓰고, “난 이 로그 포맷이 좋아” 같은 개인 취향만 CLAUDE.local.md에 남겨 .gitignore에 넣었다. 새 팀원이 와도 clone 한 번으로 팀 컨텍스트를 그대로 받는다. 온보딩 때 말로 전하던 규칙이 확 줄었다.

정적 메모리: 계속 자라는 문서로

합쳐 놓고 또 방치하면 같은 문제가 반복된다. 그래서 규칙으로 정했다.

• PR 리뷰에서 나온 교훈은 그 자리에서 CLAUDE.md에 반영한다. 같은 지적이 여러 PR에서 반복되면 md에 들어갔어야 할 규칙이라는 신호다.
• 세션 중에 바로 추가할 땐 # 단축키를 쓴다. # 유틸은 named export만 쓴다처럼 치면 메모리에 바로 들어간다.
• 한 달에 한 번 점검한다. 오래된 건 지우고 빠진 건 채운다.

검증 루프: 팀 공통으로 넣기

원문에서 Boris가 가장 중요하다고 한 게 Claude에게 자기 작업을 검증할 방법을 주는 것이다. 검증만 붙여도 최종 품질이 2~3배 오른다고 한다. 사람마다 다르면 의미가 없어서 팀 공통 md에 넣었다.

## Verification
- 코드 변경 후 `npm test` 실행
- 완료 표시 전 `npm run typecheck`
- API 변경은 curl/Postman으로 확인
- UI 변경은 브라우저에서 눈으로 확인 후 커밋

프롬프트로 매번 시키지 않아도 프로젝트 컨텍스트에 있으니 Claude가 알아서 돌린다. 팀 전체에 걸리니 “검증했겠지” 하고 넘어가는 일이 사라졌다.

결과

굴린 지 얼마 안 돼서 대단한 성공담은 아니지만, 체감은 확실하다.

가장 좋은 건 복리 효과다. PR이 하나 올라올 때마다 CLAUDE.md가 조금씩 나아진다. 예전엔 고생한 결과가 개인 파일에 갇혀 사라졌는데, 지금은 팀 자산으로 쌓인다.

물론 만능은 아니다. 팀 전원이 기여하게 만드는 건 문화의 문제라 여전히 어렵고(적극적으로 기여하는 사람은 소수다), 분산 시스템처럼 복잡한 검증은 결국 사람이 판단해야 한다. 그래도 local마다 다른 Claude라는 근본 문제를 없앤 것만으로 충분히 남는 장사였다.

마무리

CLAUDE.md의 가치는 길이가 아니라, 팀이 같은 걸 보고 그게 계속 자라느냐에서 나온다. 어려운 기술은 하나도 없었다. 각자 알아서 하던 걸 팀이 같이 하도록 바꾼 것뿐인데, 그 차이가 생각보다 컸다.