봇별 지침 문서화로 운영 일관성 확보

gov-bot이라는 새 서버 봇을 위해 CLAUDE.md 파일을 생성했다. 한 줄짜리 commit처럼 보이지만, 이건 우리 멀티 봇 환경에서 지침 관리를 체계화하는 중요한 스텝이다.

왜 봇별 지침 분리가 필요했나

우리 팀은 여러 서버 봇을 함께 운영한다. automation 봇, infrastructure 관련 봇, 그리고 이번에 추가된 gov-bot까지. 각 봇이 다루는 도메인이 다르니, 그 봇들이 지켜야 할 프롬프트 규칙도 당연히 다르다.

예를 들어, gov-bot은 정부·규제 관련 맥락에서만 특정 지침을 따를 필요가 있다. 반면 automation 봇은 작업 흐름 최적화에 집중해야 한다. 근데 이 규칙들을 모두 한 곳에 모으면?

글로벌 CLAUDE.md가 비대해지고, 매 봇 호출 때마다 불필요한 context를 로드하게 된다. 이건 토큰 비용 증가로 직결된다. 특히 프롬프트 캐싱의 TTL(5분) 을 고려하면, 자주 로드되는 파일의 크기는 정말 중요하다. 우리 글로벌 CLAUDE.md는 이미 symlink 로 중앙화되어 있고, "전 봇 공통 룰만" 유지하라고 주석까지 달려 있다. 이게 바로 그 배경이다.

계층화된 지침 구조로 전환

내가 설계한 구조는 간단하지만 효과적하다:

글로벌 규칙에는 "출력 형식은 요청된 것만", "날짜 기준은 2026년", "메타 문구 금지" 같은, 정말 모든 봇이 따라야 할 최소한의 원칙만 담는다.

bot별 규칙은? 예를 들어 gov-bot은 정부·규제 관련 특수한 도메인 지식, 그 봇이 다루는 특정 에러 패턴, 특정 팀과의 협력 방식 같은 것들을 명시할 수 있다.

"서버검증"의 의미

commit message에 "(서버검증)"이라고 붙인 이유도 중요하다. CLAUDE.md를 생성한 것만으로는 끝이 아니라, 실제 서버 환경에서:

• 파일이 올바른 경로에 있는가
• 파일이 제대로 로드되는가 (symlink든 직접 파일이든)
• 해당 봇이 호출될 때 이 지침이 실제로 적용되는가
• 글로벌과 봇별 규칙이 충돌하지는 않는가

이런 것들을 실제로 테스트하고 확인했다는 신호다. 문서가 아무리 좋아도 운영 환경에서 작동하지 않으면 의미가 없으니까.

온보딩과 일관성의 확보

이제 새로운 봇을 추가할 때는 패턴이 명확하다:

1. /opt/<new-bot>/CLAUDE.md 파일 생성
2. 그 봇의 핵심 지침 작성 (글로벌과 겹치지 않게)
3. 서버에서 실제 로드되는지 검증
4. 팀에 공유

온보딩도 간단해진다. "너 이 봇을 담당하는데, 일단 /opt//CLAUDE.md 를 봐" 하면 되니까. 산재된 지침을 찾아다닐 필요가 없다.

또한 규칙이 변경되어야 할 때도 어디를 수정할지 명확하다. "이건 전체 봇에 영향을 줘?" → 글로벌 수정. "이건 gov-bot만 해당?" → gov-bot CLAUDE.md 수정. 책임이 명확해지면 실수도 줄어들고, 코드 리뷰도 훨씬 쉬워진다.

배운 점

사소해 보이는 문서화 한 장도, 실제로는 멀티 팀·멀티 봇 환경에서의 의사결정 구조를 드러낸다. 우리가 봇별 지침을 분리한 것은 단순한 파일 정리가 아니라:

• 토큰 비용 최적화 관점에서의 선택
• 관심사 분리 원칙의 실천
• 온보딩과 유지보수 용이성의 추구

이런 결정들이 쌓이면, 팀의 엔지니어링 문화를 형성한다. "왜 이렇게 구성했는가"를 설명할 수 있으면, 새로운 팀원도 더 빠르게 학습할 수 있다.

다음 스텝은 기존 봇들도 같은 구조로 정리하는 것. gov-bot이 롤 모델이 되면, 나머지 봇들도 자연스럽게 따라갈 수 있을 거다.

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

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

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