프로젝트별 AI 봇 설정을 계층 구조로 정리하기

여러 사이트에 걸쳐 흩어져 있던 CLAUDE.md 파일들을 캐스케이드 구조로 재정렬하고, 서버 환경에서 실제 작동을 검증했다.

뭐가 문제였나

우리 팀이 관리하는 여러 서비스와 프로젝트들이 점점 늘어나면서, 각각에 배치된 CLAUDE.md 들 사이의 관계가 복잡해졌다. 각 프로젝트마다 AI 봇 지침이 개별적으로 존재했는데, 처음엔 몰라도 시간이 지날수록 일관성 문제가 눈에 띄었다.

구체적으로 이런 일들이 반복됐다:
- 중복 작성: "출력은 요청된 형식만 낸다"는 글로벌 공통 룰을 매 프로젝트마다 다시 써야 했다.
- 수정 추적 곤란: 글로벌 룰을 수정했을 때 어느 프로젝트까지 영향을 주는지 불명확했다.
- 구조 혼동: 서버 환경에선 symlink로 단일 진실 공급원을 만들려고 했는데, 어느 파일을 수정하면 언제 반영되는지 모호했다.

특히 팀이 새 프로젝트를 추가할 때마다 "이건 공통 문서에 둘까, 프로젝트 문서에 둘까?" 하는 결정이 일관되지 않아서, 문서 구조 자체가 점점 엉망이 되고 있었다.

캐스케이드 구조로 재정렬

이번 작업은 명확한 계층 구조를 도입했다.

이렇게 정렬한 덕분에, 이제 각 파일이 뭘 하는지 명확하다. 예를 들어 새로운 팀원이 "이 서비스에만 적용되는 규칙"을 추가하고 싶으면, 글로벌 파일을 건드리지 않고 프로젝트별 CLAUDE.md 만 수정하면 된다. 반대로 "모든 봇이 지켜야 할 규칙"이 있으면 ops 중앙 문서를 수정한 뒤 서버에 git pull 하나로 모든 프로젝트에 반영된다.

문서 주석으로 경계를 명시

단순 파일 정렬만으로는 부족했다. 각 파일에 이 부분이 어느 계층인지를 주석으로 달았다.

# 전역 지침 — 모든 봇 호출에 로드 (심각한 토큰 비용)
- 출력은 요청된 형식만
- 날짜 기준은 2026년

# ⚠️ 프로젝트별 디테일은 여기가 아니라 /opt/<repo>/CLAUDE.md에
# 이 파일에는 "전 봇 공통 룰"만 둘 것

이렇게 하니 다음번에 누가 "어? 이 룰을 여기다 추가해야 하나?" 할 때 문서 자체가 가이드 역할을 했다.

서버 환경에서 실제 검증

로컬 환경에선 파일 구조가 완벽해 보였지만, 서버에 배포되면 symlink가 깨지거나 파일 경로가 꼬이는 사례가 자주 있었다. 이번엔 서버에 직접 접속해서 손으로 확인했다.

• symlink 타겟이 올바르게 가리키는가
• 캐스케이드 로드 순서가 기대대로인가 (공통 → 프로젝트별 → 오버라이드)
• 실제 봇 호출 시 어느 CLAUDE.md가 읽히는가

이 과정에서 몇 가지 예상 밖의 권한 문제와 경로 문제를 발견해 수정했다.

팀 관점에서의 의미

단순히 "파일 정리"로 보일 수 있지만, 이건 설정 관리 철학의 결정이다.

우리 팀 규모가 여러 사이트, 수십 개의 AI 호출 수준까지 성장하면서, 어디까지를 "중앙 통제"하고 어디부터를 "각자 자유"하게 할지가 중요해졌다. 중복이 많으면 변경 누락이 생기고, 자유도가 높으면 일관성이 깨진다.

우리가 채택한 답은 계층식 캐스케이드: 공통은 위에서 한 번, 프로젝트별 디테일은 아래에서만. 이러면 "공통 룰 한 줄 수정"이 모든 사이트에 파급되지만, 각 프로젝트는 필요한 부분만 오버라이드할 수 있다.

배운 점

문서 아키텍처 = 시스템 아키텍처다. 설정 문서가 헷갈린다는 것은 책임 경계가 흐릿하다는 신호다. CLAUDE.md 를 정리하면서 결국 "우리가 뭘 중앙화하고 뭘 분산화할 건가"라는 아키텍처 질문을 풀 수 있었다.

서버 검증은 선택 사항이 아니다. 로컬에선 완벽하던 것이 서버에선 symlink가 깨져 있고, 파일 경로가 꼬여 있을 수 있다. 특히 환경 의존적인 부분은 실제 환경에서 직접 테스트하는 게 유일한 방법이다.

팀이 커질수록 규칙은 "감"이 아니라 "문서"다. 처음엔 "나는 이렇게 하고 있었는데"라는 암묵적 합의가 작동한다. 하지만 팀이 5명을 넘어가면서부터 명시적인 문서가 필수가 된다. "CLAUDE.md 캐스케이드는 이렇게 작동한다"고 문서에 써두면 온보딩도 쉽고, 내가 빠져도 팀이 흔들리지 않는다.

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

• 모니터 쿠팡에서 보기 →
• 책상조명 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

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