팀별 지침을 계층 구조로 정리

여러 프로젝트와 팀이 각각 다른 Claude 지침을 가져야 할 때, 전역 규칙과 프로젝트별 규칙을 어떻게 관리할지가 문제였다. 이번 작업은 CLAUDE.md 파일들을 사이트별 캐스케이드 구조로 재정의해서 싱글 소스 오브 트루스를 확보하고, 동시에 토큰 비용도 최적화했다.

문제: 문서 중복과 유지보수 지옥

원래는 각 봇/프로젝트 디렉토리마다 완전히 독립된 CLAUDE.md 를 두고 있었다. 처음엔 괜찮았지만, 팀이 커지면서 다음 문제들이 터지기 시작했다.

공통 규칙의 반복
예를 들어 "출력은 요청된 형식만 낸다", "봇 인사말 금지" 같은 기본 원칙들이 모든 파일에 똑같이 박혀 있었다. 한 곳에서 기본값을 수정하면 다른 곳은 또 손을 봐야 한다.

토큰 낭비
Claude 호출할 때마다 CLAUDE.md 가 프롬프트에 로드된다. 중복된 전역 규칙이 들어가면, 매 호출마다 같은 텍스트를 처리하는 비용이 쌓인다. 토큰 버짓이 있는 환경에서는 치명적이다.

새 팀 온보딩 혼란
팀 리더들이 새로운 프로젝트를 시작할 때, 어떤 규칙을 어디까지 override 해야 하는지 명확하지 않았다. 모든 것을 복사-붙여넣기했다가 나중에 충돌 위험도 있었다.

솔루션: 계층 구조로 상속화

캐스케이드 구조를 설계했다. 로드 순서와 우선순위를 명확히 했다.

로드 순서가 중요하다. 나중에 로드된 규칙이 앞의 규칙을 override 한다. 그래서 프로젝트별 CLAUDE.md 에 같은 키가 있으면 그것만 적용된다.

구현 포인트

문서 내 명시적 참조
전역 CLAUDE.md 의 맨 위에 다음 같은 주석을 달았다:

> 단일진실 = `hedvionCorp/ops` 의 `docs/server-global-CLAUDE.md`.
> 서버 `/home/hedvion/.claude/CLAUDE.md` 는 이 파일로의 symlink.
> 수정 = mac 에서 ops 커밋+push → 서버 `cd /opt/ops && git pull`.

이렇게 하면 누가 봐도 "어디가 진실이고, 어디가 동기화되는 부분인지" 한눈에 드러난다.

프로젝트별 override 문법
각 프로젝트 CLAUDE.md 의 맨 위에 "이 파일이 전역을 override 하는 부분은 여기"라고 명시했다. 예를 들어:

# 프로젝트 X 개발자 지침

> 전역 지침: ~/.claude/CLAUDE.md 상속
> 프로젝트별 추가 규칙:

- [그 프로젝트만의 파일 구조, 도메인 용어, 특수 권한 등]

토큰 비용 의식
전역 CLAUDE.md 에는 "전 봇 공통 룰"만 남겼다. "프로젝트 A 는 NodeJS, B 는 Python" 같은 건 각 CLAUDE.md 에 넣도록 했다. 작은 차이지만, 매일 수백 번 호출될 때는 눈에 띈다.

회고: 문서 아키텍처의 중요성

이 작업을 하면서 느낀 건, 문서도 코드처럼 구조화와 DRY 원칙이 중요하다는 거였다. 팀 규모가 작을 때는 복사-붙여넣기가 빠르지만, 스케일이 커지면 유지보수 비용이 폭발한다.

비슷한 상황들:
- 데이터베이스 schema 상속 (테이블 간 공통 컬럼)
- 마이크로서비스 설정 (환경별 override)
- 팀 정책 문서 (조직 정책 + 팀별 규칙)

모두 같은 패턴이다: "공통 부분을 최상위에서 관리하고, 예외만 아래 단계에서 정의한다."

이번 refactoring 으로 새 프로젝트가 추가될 때도 신경 쓸 게 줄었다. 전역 파일을 복사하는 대신, "이건 symlink 다, 프로젝트별 부분만 추가해" 하고 하면 된다. 나중에 전역 규칙이 바뀌면 ops 리포에서 한 번만 고치면 모든 팀에 자동 반영된다.

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

• 기계식키보드 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

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