사이트별 Claude 지침을 계층 구조로 관리하게

여러 사이트/팀에서 같은 money 프로젝트를 쓸 때 Claude Code 지침(CLAUDE.md)을 어떻게 관리할지가 고민이었다. 이번엔 사이트별로 지침을 계층적으로 구조화했다.

배경: 왜 계층화가 필요했나

처음엔 각 사이트마다 CLAUDE.md 파일을 완전히 별도로 두거나, 하나의 거대한 파일에 모든 예외 조건을 때려박는 방식을 썼다. 둘 다 문제가 있었다.

첫 번째 방식은 공통 규칙이 바뀔 때마다 모든 사이트 파일을 일일이 수정해야 한다. 두 번째 방식은 파일이 비대해지고 어느 지침이 어느 사이트에 적용되는지 추적하기 어렵다. 토큰 비용도 계속 올라간다 — 매번 Claude를 호출할 때마다 전체 CLAUDE.md를 로드하니까.

특히 우리처럼 여러 사이트(또는 여러 팀, 여러 환경)를 운영할 때는 공통 지침 과 사이트별 오버라이드 를 명확히 분리해야 한다. 개발자들도 "어떤 규칙이 내 환경에 적용되나"를 한눈에 파악해야 한다.

계층적 구조: 전역 → 프로젝트 → 사이트

이번 변경으로 CLAUDE.md를 다음처럼 계층화했다:

상위 계층의 규칙이 기본이 되고, 아래 계층에서 필요한 부분만 오버라이드한다. 예를 들어 전역 CLAUDE.md에서 "토큰 비용을 줄이려면 짧게 작성하라"고 했으면, money 프로젝트 CLAUDE.md에선 "하지만 money는 결제 정책이 복잡하니 상세히 설명하자" 같은 예외를 두면 된다.

구현과 검증

이 구조를 서버 환경에서 직접 검증했다. "(서버검증)"이라고 커밋에 남긴 이유도 그것이다 — 로컬에서 괜찮아 보여도 실제 서버에서 여러 사이트가 동시에 CLAUDE.md를 로드할 때 충돌이나 누락이 없는지 확인했다는 의미다.

실제로는:
- 전역 CLAUDE.md (심볼링크로 ops 레포와 동기화)
- money/CLAUDE.md (money 프로젝트 레포 루트)
- 선택적으로 각 사이트나 팀의 로컬 CLAUDE.md

이런 식으로 Claude 호출이 발생할 때 위 순서대로 로드되고, 나중에 로드된 것이 앞의 설정을 오버라이드한다.

이게 가져다 준 것들

1. 중복 제거 + 토큰 절감
공통 규칙을 여러 번 써야 했던 보일러플레이트가 사라졌다. 팀이 늘어나도 전역 규칙은 한 곳만 수정하면 된다.

2. 명확한 의도 전달
새로운 팀원이나 다른 팀이 money 프로젝트를 쓸 때, "어떤 규칙이 금융 도메인 특화이고 어떤 건 이 사이트만의 관례인가"를 문서 구조 자체로 볼 수 있다.

3. 안전한 온보딩
기존 팀의 규칙을 건드리지 않으면서 새 사이트가 합류할 수 있다. 사이트별 CLAUDE.md만 추가하고 나머지는 그대로 상속받으니까.

4. 유지보수 용이성
전역 정책이 바뀌는 상황(예: 새로운 모델 출시, 토큰 가격 정책 변경)을 한 곳에서 관리하고, 사이트별 커스텀은 각자 책임진다.

배운 점

이런 계층 구조는 설정 관리의 기본이지만, 문서라는 텍스트 파일에 적용할 때는 좀 다르다. 코드 설정이면 YAML이나 JSON으로 깔끔하게 병합할 수 있는데, Markdown 형식의 지침은 상속과 오버라이드를 구현하려면 관례와 주석에 의존 해야 한다.

그래서 우리는:
- 각 계층의 파일 시작 부분에 "이 파일의 범위"와 "상위 파일과의 관계"를 명시
- 오버라이드하는 항목은 명확하게 "이전 규칙을 무시하고 다음을 따른다"고 표기
- 사이트/프로젝트 CLAUDE.md 에 "전역 CLAUDE.md 도 읽어야 한다"는 주석

이렇게 문서 수준에서의 규약을 정하는 게 중요하다. 기술로는 자동화할 수 없는 부분이라 팀의 성숙도와 일관성에 달려 있다.

아무튼 이 변경 덕분에 money처럼 멀티사이트 프로젝트는 설정 관리가 훨씬 깔끔해졌다.

🛒 이 글과 어울리는 추천 상품

• 책상조명 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.