봇 지침 계층화로 전사 중복 제거

최근 여러 팀과 사이트가 사용하는 AI 봇들의 지침 파일(CLAUDE.md) 관리 구조를 개선했다. 개별 봇이나 사이트마다 전사 공통 규칙을 반복해서 작성하는 비효율을 없애기 위해 캐스케이드 방식의 계층화를 도입한 작업이다.

배경: CLAUDE.md 파일의 역할과 문제

CLAUDE.md는 AI 봇이 해당 디렉토리에서 실행될 때 자동으로 로드되는 지침 문서다. 봇의 동작, 출력 형식, 권한 관리, 환경 변수 같은 프로젝트별/팀별 맞춤 규칙을 담는다.

초기엔 모든 규칙을 각 봇이나 사이트 디렉토리마다 별도로 관리했다. 문제는 몇 가지였다:
- 전사 공통 규칙이 중복 — "날짜 기준은 2026년", "출력은 요청된 형식만" 같은 글로벌 정책을 매번 반복 작성
- 유지보수 비용 — 전사 정책이 바뀔 때마다 모든 CLAUDE.md를 수정해야 함
- 일관성 부족 — 어떤 사이트는 최신 규칙, 어떤 사이트는 구 규칙을 따르게 됨
- 토큰 낭비 — 봇 호출마다 로드되는 파일이므로, 중복된 텍스트는 곧 비용 증가

해결: 캐스케이드 계층 구조 설계

전사 글로벌 지침 파일을 최상단에 두고, 각 사이트/프로젝트는 공통 규칙을 상속받는 구조로 변경했다.

이 구조에서:
1. 전사 글로벌 파일은 단일 진실 공급원(Single Source of Truth)이 됨
2. 서버/.claude/CLAUDE.md는 심볼릭 링크로 전사 파일을 참조
3. 각 사이트 CLAUDE.md는 "추가" 규칙만 작성 — "이 프로젝트 고유 룰"을 넣고, 공통 규칙은 상속 받는다고 명시
4. 변경 프로세스: mac에서 전사 ops 커밋 → 서버 git pull → 모든 사이트가 자동 반영

# projectX/CLAUDE.md 예시
> 단일진실 = `/opt/ops/docs/server-global-CLAUDE.md`.
> 변경 = ops 커밋+push → 서버 `git pull`.
> ⚠️ "전 봇 공통 룰"은 전사 파일에. 프로젝트 디테일만 여기 작성.

- [전사 공통 지침 상속받음]
- [이 프로젝트만의 추가 규칙...]

토큰 비용과 유지보수의 관점

매일 수십 개의 봇 호출이 이루어지는 환경에서 CLAUDE.md는 매번 로드되는 비용이다. 전사 공통 규칙을 중복 작성했다면:
- 파일마다 500자씩 중복 × 10개 사이트 = 5000자 × 호출 수
- 문서 수정할 때마다 10곳을 일일이 수정해야 함

계층화하면:
- 글로벌 파일만 유지 → 각 사이트 CLAUDE.md 크기 감소 → 로드 토큰 절감
- 정책 변경 시 한 파일만 수정 → 휴먼 에러 감소

팀 리딩 관점에서의 결정

이 변경을 설계하면서 염두에 둔 트레이드오프:

✓ 장점:
- 신규 사이트 추가 시 보일러플레이트 줄어듦
- 전사 정책의 무결성(integrity) 보장
- 각 팀장이 "이게 글로벌 규칙인지, 우리 것인지" 빠르게 판단 가능

△ 고려한 부분:
- symlink 기반 참조 → 서버 환경 의존성 증가 (따라서 서버 검증 필수)
- 명시적 설명 필요 → 새 팀원이 구조를 이해해야 함

회고

이 작업을 통해 느낀 점:

1. "공통 규칙을 놓치지 말자" — 초기에 "각 프로젝트가 독립적이면 되지 않을까"로 시작했다면, 3개월 뒤 유지보수가 악몽이 됐을 것
2. 계층화 설계는 조직 성장과 함께 — 팀이 작을 땐 중복이 눈에 띄지 않지만, 5개→10개→20개 사이트가 되면 DRY 원칙이 살아난다
3. "사이트별 추가 규칙만"이라는 명시 — 문서에 "이곳엔 프로젝트 디테일만 둔다"고 명시하는 것만으로도 팀들의 혼동이 줄어듦

앞으로도 새로운 봇이나 사이트가 추가될 때마다, 이 구조가 스케일링의 부담을 덜어줄 것 같다.

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

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

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