지침 파일 분산 관리를 캐스케이드로 통합

Claude 봇들이 작동할 때 로드되는 지침 파일 CLAUDE.md 를 여러 환경에 걸쳐 관리하면서 문제가 생겼다. Mac 로컬 환경과 서버 환경에서 지침이 따로 존재하다 보니, 공통 규칙을 변경할 때마다 양쪽을 동시에 업데이트해야 했고, 손으로 직접 편집하면서 불일치가 발생할 수 있었다. 이번에 이 문제를 단일진실(single source of truth) 원칙을 기반으로 한 캐스케이드 구조로 정리했다.

분산 관리의 복잡성

프로젝트 규모가 커지면서 Claude 봇 지침도 늘어났다. 단순히 각 환경마다 CLAUDE.md 를 따로 유지하는 것 같으면, 실제로는 꽤 골치 아픈 상황이 된다. 공통으로 적용해야 할 규칙(예: 날짜 기준, 출력 형식, 보안 정책)이 변경될 때마다 여러 파일을 수정해야 한다. 누군가는 하나는 빠뜨릴 수 있고, 또 다른 사람은 불필요하게 버전을 올렸을 수도 있다. 특히 서버 환경에서는 직접 편집하지 말자는 약속을 유지하기도 쉽지 않았다. 이렇게 되면 "정확한 지침이 뭐지?" 하는 혼동이 팀 내에서 반복된다.

더 큰 문제는 토큰 비용이다. 매 Claude 호출마다 이 지침 파일을 로드하는데, 중복된 내용이 여러 곳에 있으면 불필요한 토큰을 낭비한다. 팀 규모로 보면 매일 수백 번의 호출이 발생하는데, 공통 부분을 중복으로 로드하면 장기적으로 상당한 비용 오버헤드가 된다.

단일진실 원칙으로 구조화

해결책은 간단했다. 공통 지침은 한 곳(ops 리포지토리의 docs/server-global-CLAUDE.md)에만 두고, 개별 환경에서는 심볼릭 링크로 그곳을 가리키는 방식이다. 각 환경별 로컬 지침이 필요하면, 그 위에 계층화해서 추가한다.

이 구조에서 서버의 /home/hedvion/.claude/CLAUDE.md 는 실제로는 ops 의 공통 파일로의 심볼릭 링크가 되었다. 수정이 필요하면 Mac 에서 ops 에 커밋하고 푸시한 다음, 서버에서 git pull 하면 자동으로 반영된다.

왜 이 방식을 택했나

처음엔 파일 포함(file inclusion) 방식도 고려했다. 예를 들어 CLAUDE.md 에서 다른 파일을 읽고 병합하는 식이다. 하지만 그러려면 로드 로직을 별도로 구현해야 했고, 복잡도가 높아졌다. 심볼릭 링크는 OS 수준에서 제공하는 기능이라 추가 코드 없이 "파일이 같다"는 보장이 명확하다.

직접 편집 금지 정책도 중요했다. 서버에서 누가 실수로 파일을 편집하면 ops 와 불일치가 생긴다. 그래서 문서에 "직접편집 금지, ops 에서만 수정"이라고 명시하고, ops 의 변경이 source of truth 가 되도록 했다.

팀 관점에서의 이점

여러 봇이 실행되는 환경에서 일관된 지침을 유지하는 건 생각보다 중요하다. 한 봇은 공통 지침을 무시하고 다른 정책으로 실행되면, 다른 팀원은 왜 저 봇은 다르게 작동하는지 혼동한다. 캐스케이드 구조로 정리하면서, "이 지침이 언제 어디서 정의됐는지"를 쉽게 추적할 수 있게 됐다.

또한 토큰 비용 절감도 실질적이다. 공통 부분을 한 번만 로드하면, 매달 누적되는 비용이 눈에 띄게 줄어든다. 특히 ops 리포지토리는 대규모이지만, 공통 지침 부분은 간결하게 유지하도록 문서화했다.

배운 점

이 작업을 하면서 느낀 건, 초기에 "지침 파일도 결국 코드처럼 관리해야 한다"는 점이다. DRY(Don't Repeat Yourself) 원칙이 코드에만 적용되는 게 아니라, 설정이나 정책 문서에도 적용된다는 뜻이다. 변경 빈도가 높은 부분일수록 단일진실 원칙이 중요하다.

또한 "Mac 에서만 수정, 서버는 git pull" 이라는 워크플로우 제약도 팀원들이 일관된 방식으로 따르도록 강제하는 장치가 됐다. 문서화와 도구를 함께 써야 정책이 지켜진다는 걸 다시 한번 확인했다.

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

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

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