사이트별 개발자 지침을 계층화해 중복 제거

모든 claude 호출마다 CLAUDE.md가 로드되는 구조에서, 여러 사이트가 공통 지침을 반복으로 담고 있었다. 이번에 계층화된 cascade 방식을 도입해 토큰 낭비를 줄이고 유지보수를 개선했다.

왜 계층화가 필요했나

우리는 여러 사이트와 환경을 운영하면서 각각이 고유한 CLAUDE.md를 가지고 있었다. 예를 들어:
- 전역 공통 룰 (모든 봇이 따라야 할 기본)
- button 사이트별 특수 지침 (특정 사이트에만 적용)
- 하위 프로젝트별 상세 설정

문제는 이 정보들이 각 파일에 분산되어 있으면서도 중복되었다는 점이다. 예를 들어 "출력은 요청된 형식만 낸다"는 규칙이 여러 CLAUDE.md에 써 있었다. 그러면 매 호출마다 더 많은 토큰을 소비할 뿐 아니라, 한 곳을 수정해도 다른 곳이 동기화되지 않아 불일치가 발생했다.

특히 모든 claude 호출이 이 파일들을 읽어야 하기 때문에, 불필요한 내용이 하나 있어도 전체 토큰 비용에 영향을 준다. 토큰 비용의 누적 효과는 생각보다 크다.

계층 구조 도입

이번 변경으로 다음과 같은 우선순위 체계를 만들었다:

더 구체적인 레벨이 상위 레벨을 override한다. 예를 들어 전역에서 "모든 출력은 마크다운"이라 했어도, 특정 프로젝트 CLAUDE.md에서 "이 프로젝트는 JSON 만 출력"이라 하면 그쪽을 따른다.

전역 CLAUDE.md (ops/docs/server-global-CLAUDE.md)
  └─ 사이트별 CLAUDE.md (/opt/button-site-1/.claude/CLAUDE.md)
       └─ 프로젝트 CLAUDE.md (/opt/button-site-1/myrepo/.claude/CLAUDE.md)

이 구조로 각 레벨은 자신에게만 필요한 것만 담고, 나머지는 위에 위임한다.

서버검증과 유지보수

이 변경을 서버에서 직접 검증했다. 실제로 여러 사이트의 봇 호출을 모니터링하면서:
- 각 사이트가 자신의 CLAUDE.md만 필요한 내용으로 줄어들었나
- 전역 변경이 제대로 cascade되었나
- 충돌이나 우선순위 역전은 없었나

이런 점들을 확인했다. 특히 중요한 건, 앞으로 공통 룰을 수정하면 한 군데만 손대도 모든 사이트에 반영된다는 것. 이전처럼 여러 곳을 일일이 찾아다닐 필요가 없다.

일반적인 교훈

이런 계층화 패턴은 문서나 설정 관리에서 자주 나타난다. CI/CD 파이프라인의 base config + env-specific config, terraform의 modules + tfvars, kubernetes의 CRDs + namespace overrides 등. 핵심은:

• 단일 진실(single source of truth): 공통 부분은 한 곳에만
• 명확한 우선순위: 어느 것이 어느 것을 덮을지 명시
• 검증: 계층이 복잡할수록 실제 동작을 확인하는 게 중요

우리의 경우 토큰 비용이 바로 "감지 가능한" 메트릭이었기 때문에, 이 정책이 실제로 얼마나 효율적인지도 측정할 수 있었다. 중복이 줄면 파일 크기가 줄고, 그만큼 토큰 사용량도 감소한다.

button 사이트들 외에 다른 프로젝트도 같은 패턴으로 정리하면 될 것 같다.

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

• 노트북 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

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