여러 사이트의 공통 지침을 한곳에서 관리하다

Claude Code 로컬 설정인 CLAUDE.md는 꽤 특이한 파일이다. 모든 봇 호출마다 로드되기 때문에, 파일 크기와 내용이 토큰 비용에 직결된다. 한두 줄이라도 불필요한 중복이 있으면 매 호출마다 낭비가 누적된다.

당시 상황: 여러 프로젝트, 공통 규칙의 산재

우리는 ops 저장소를 중심으로 여러 사이트와 서버 프로젝트를 운영하고 있었다. 각 프로젝트마다 CLAUDE.md 파일이 있었고, 거기에 공통 규칙들이 들어가 있었다. 예를 들어:

• 출력 형식 규칙 (메타 문구 금지)
• 날짜 기준 (2026년)
• 토큰 비용 주의

이런 규칙들이 ops의 server-global-CLAUDE.md에는 원본이 있는데, 각 프로젝트 CLAUDE.md에도 동일한 내용이 중복으로 들어가 있었다. "나중에 한 곳에서만 관리하면 되겠지"라고 생각했지만, 시간이 지나면서 여러 파일의 동기화를 맞추는 것이 번거로워졌다.

캐스케이드 구조로의 계층화

이번 커밋의 핵심은 설정 파일의 상속 관계를 명시하는 것이었다. 구조를 다시 정리했다:

구체적으로는, 각 프로젝트의 CLAUDE.md가 최상위 server-global-CLAUDE.md를 상속받도록 문서화했다. 각 사이트는 자신의 특수 규칙만 추가하고, 공통 부분은 부모에서 로드되도록 캐스케이드하는 구조다.

ops/docs/server-global-CLAUDE.md (공통 규칙)
  ↓ 상속
/opt/<각-프로젝트>/CLAUDE.md (프로젝트별 규칙만)

왜 "diet" 라고 명명했나

"diet"이라는 단어는 단순히 파일을 가볍게 한다는 의미가 아니다. 우리 팀에서는 설정 관리의 철학을 담아서 쓰는 표현이다:

• 각 문서는 필요한 것만: 중복된 공통 규칙 제거
• 캐시 효율: 보트 호출 시 로드되는 토큰 양 감소
• 확장성: 새로운 프로젝트 추가 시 공통 부분 자동 상속

이런 구조면, 나중에 "모든 프로젝트에 새로운 공통 규칙을 추가해야 한다"는 요청이 와도 한 파일만 수정하면 된다. 각 프로젝트는 자동으로 그 규칙을 따르게 된다.

서버검증이 중요했던 이유

문서만 수정하는 것으로는 충분하지 않았다. 실제 서버 환경에서 Claude Code가 이 캐스케이드 구조를 제대로 인식하고 로드하는지 확인해야 했다.

예를 들어:
- 심볼릭 링크가 제대로 작동하는지
- 각 프로젝트에서 호출될 때 상속 관계가 제대로 유지되는지
- 로드 순서나 우선순위가 예상대로 동작하는지

서버에 직접 로그를 확인하고, 실제 봇 호출 몇 개를 테스트해봤다. 이 부분이 없었으면 배포 후 "어? 규칙이 안 먹는데?" 같은 버그 리포트가 들어왔을 수 있다.

팀 관점에서의 배운 점

이 작업은 단순한 문서 정리처럼 보이지만, 사실은 설정 관리 전략의 결정이었다. 팀이 성장하면서 프로젝트가 늘어날 때:

1. 공통 규칙을 반복 작성하는 것은 낭비
2. 한 곳에서 관리하면 일관성이 높아짐
3. 각 팀/사이트는 자신의 특수성에 집중 가능

특히 우리처럼 여러 사이트를 동시에 운영하고, AI 어시스턴트 설정이 토큰 비용에 영향을 미치는 환경에서는 이런 최적화가 쌓이면 꽤 유의미한 비용 감소로 이어진다. 매번 호출할 때마다 몇 줄 덜 로드되는 것이, 수천 개 호출이 되면 눈에 띄는 차이가 된다.

다음은 프로젝트별 규칙이 실제로 얼마나 달라질 수 있는지, 각 사이트가 독립적인 특수성을 가질 때의 이점을 더 체험해보려고 한다. 캐스케이드 구조가 자리잡으면, 새로운 사이트 추가도 이제 훨씬 수월할 것 같다.

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

• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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