멀티사이트 운영 문서 구조 정리하기

사이트별 개발 지침 파일(CLAUDE.md)을 계층적으로 정리했다. 전역 지침과 각 사이트별 지침을 분리해서, 봇이 호출될 때마다 필요한 규칙만 로드하도록 설계한 작업이다.

문서 구조 정리가 필요했던 이유

우리 팀은 여러 개의 사이트/서비스를 운영하고 있는데, 초기엔 모든 개발 지침을 하나의 전역 CLAUDE.md에 몰아 넣었다. 문제는 토큰 비용이었다. 봇이 호출될 때마다 전 지침을 로드하니 불필요한 토큰이 낭비되었고, 사이트별로 다른 요구사항이 생기면 조건문으로 처리해야 했다.

특히 팀이 성장하면서 각 사이트마다의 규칙이 달라지기 시작했다:
- 어떤 사이트는 특정 디렉토리 구조를 따르고
- 어떤 사이트는 다른 배포 방식을 쓰고
- 어떤 사이트는 보안 규정이 엄격하다

이런 상황에서 "모든 지침을 하나의 문서에"는 확장성이 떨어진다.

캐스케이드 패턴으로 해결

이번 커밋으로 문서 구조를 다음처럼 개선했다:

전역 지침에서는 "메타 룰" (출력 형식, 날짜 기준, 보안 관련)만 두고, 실제 프로젝트 디테일(디렉토리 구조, 배포 파이프라인 등)은 각 사이트 CLAUDE.md에 분산시켰다. 이렇게 하면:

• 토큰 절감: funeral 사이트 봇은 funeral 지침만 로드
• 유지보수 용이: 각 사이트 규칙이 변경되면 그 파일만 수정
• 일관성 유지: 전역 규칙은 한 곳에서 관리해서 모든 사이트가 동일하게 따름

서버 검증이 중요한 이유

커밋 메시지에 "(서버검증)"이라고 명시한 것은 단순 형식 맞춤이 아니다. 문서 구조 변경이 실제로 서버 환경에서 제대로 작동하는지 확인했다는 뜻이다.

symlink가 제대로 걸렸는지, 각 봇이 올바른 CLAUDE.md를 참조하는지, ops 저장소에서 pull했을 때 모든 사이트가 최신 지침을 받는지 — 이런 것들을 테스트해야 한다. 특히 캐스케이드 구조에서는 한 점의 실패(예: symlink 깨짐)가 여러 봇에 영향을 미칠 수 있으니까.

팀 차원에서의 학습

이 작업은 "단순 문서 정리"처럼 보이지만, 팀이 성장할 때의 중요한 패턴을 담고 있다:

1. 중앙화와 분산의 균형 — 전역 규칙은 한 곳에서 관리하되, 세부사항은 각 팀(또는 각 사이트)에 위임
2. 단일 진실 공급원(Single Source of Truth) — ops 저장소의 한 파일이 모든 서버에 반영되니 수작업 동기화 불필요
3. 비용 의식 — 토큰 절감 같은 작은 최적화가 모여서 개발 속도와 비용에 큰 영향

초기에는 "다 함께 한 문서"가 단순하고 편하다고 느껴질 수 있다. 하지만 팀이 2-3개 팀으로 나뉘거나 서비스가 증가하면, 명확한 계층 구조 없이는 문서가 비대해지고 중복이 생긴다. 이번 캐스케이드 구조가 지금은 작은 변화처럼 보이지만, 다음 사이트가 추가될 때 "아, 우리가 이미 이 패턴을 만들어뒀구나"라고 느끼게 될 거다.

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

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

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