반복되는 지침을 계층별로 관리하기

telebot 이라는 새 봇을 배포하면서, 해당 봇만의 CLAUDE.md 를 추가하는 작업을 진행했다. 이것만 보면 단순한 문서 파일 생성처럼 보이지만, 사실 이 작업의 핵심은 지침(프롬프트 정책)을 계층적으로 관리하는 구조를 구현하는 것이었다.

CLAUDE.md 와 토큰 비용의 관계

사내 각 봇(telebot, 기타 서비스들)은 실행될 때마다 자신의 CLAUDE.md 를 로드한다. 이 파일이 프롬프트 컨텍스트의 일부가 되기 때문에, 봇 호출할 때마다 토큰을 소비하는 것이다. 이를 감안하면, 공통 지침(예: 출력 형식, 금지사항)을 CLAUDE.md 에 계속 반복해서 적으면 낭비다.

더 나은 방식은 계층 구조 를 갖추는 것이다.

캐스케이드 구조 설계

다음과 같이 구성했다:

telebot CLAUDE.md 추가는 이 셋째 계층에 새 공간을 마련한 것이다. 이제 공통 규칙과 프로젝트 규칙을 반복하지 않고, telebot 에만 필요한 지침만 담을 수 있다.

코드 관점에서의 이점

코드를 건드리지 않았지만, 효과는 실질적이다:

• 프롬프트 중복 제거: 공통 지침을 따로 유지하면, 새 봇 추가 시 매번 복사-붙여넣기 할 필요가 없다
• 토큰 절감: 각 봇이 로드할 때 자신에게만 필요한 지침만 담아, 불필요한 컨텍스트를 줄인다
• 유지보수성 향상: 모든 봇의 공통 규칙을 바꿀 때, 중앙 파일 하나만 수정하면 된다 (물론 마치 Git 상속처럼 작동)
• 확장성: 다음 봇이 추가될 때 구조가 이미 정해져 있으므로, 온보딩 문서도 명확해진다

"서버검증"의 의미

커밋 메시지의 "(서버검증)"은 로컬 개발 환경에서만이 아니라 실제 서버 환경(hedvion ops)에서도 이 계층 구조가 정상 작동함을 확인했다는 뜻이다. symlink 와 캐스케이드 로직이 복잡할 수 있으니까, 실제 배포 전에 서버에서 한번 테스트하는 것이 중요했다.

팀장 관점에서의 회고

문서화와 정책 관리는 코딩처럼 보이지는 않지만, 팀이 커질수록 반복 제거와 중앙화된 규칙 관리가 얼마나 중요한지 느낀다. 새 팀원이 들어올 때마다 "어 근데 어느 CLAUDE.md 를 봐야 하나?" 라는 질문을 줄일 수 있고, 규칙을 바꾸려고 할 때 모든 봇/서비스를 하나하나 수정하지 않아도 된다.

side 작업이라는 시간 여유 속에서 이런 구조를 정비하는 것은, 급할 때 하는 임시방편이 나중에 기술부채가 되는 것을 미리 예방하는 일이다.

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

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

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