봇 지침 계층화로 프로젝트별 정책 충돌 없애기

이번 작업은 사실 "side task"로 분류했지만, 팀이 여러 프로젝트를 동시에 돌리면서 마주친 꽤 실질적인 기반 시설 문제였다. CLAUDE.md를 사이트별로 캐스케이드하는 구조를 다시 정리한 거다.

왜 이런 구조가 필요했나

초기에는 한두 프로젝트만 있어서 전역 지침 하나가 모든 봇 호출에 로드되면 충분했다. 근데 팀이 여러 도메인(formpack, ops, 다른 서버 프로젝트들)을 관리하게 되면서, 각 프로젝트마다 다른 규칙이 필요해졌다.

예를 들어:
- 전역 규칙: "출력은 요청 형식만" / "메타 문구 금지" (모든 봇이 따를 공통 표준)
- 프로젝트별 규칙: formpack은 "API 문서 생성 시 JSON Schema 필수", ops는 "변수명에 숫자 prefix 금지" 같은 식

각 프로젝트 디렉토리에 CLAUDE.md를 따로 두면, 봇이 그 디렉토리에서 실행될 때 자동으로 그 프로젝트의 지침을 로드한다. 하지만 "어디까지 전역이고 어디부터 프로젝트 로컬인가"를 명확히 하지 않으면, 팀원들이 중복으로 규칙을 쓰거나, 서로 충돌하는 지침을 넣을 수 있었다.

캐스케이드 구조의 설계

문제는 이렇게 정리했다:

사이트별 지침은 다음처럼 계층화했다:

/opt/ops/docs/server-global-CLAUDE.md (중앙 진실의 원천)
  ↓ 상속
/opt/<repo>/CLAUDE.md (각 프로젝트 커스텀)
  ↓ (재정의 가능)
프로젝트 특화 규칙 (override)

프로젝트 CLAUDE.md는 이제 명시적으로 "이 파일은 전역 지침을 기반으로 하며, 다음 규칙만 추가/변경한다"고 선언할 수 있다.

서버 검증이 왜 중요했나

"(서버검증)"이라고 단 이유는, 개발 환경에서는 로컬 파일이 잘 로드되지만, 실제 서버 배포에서는 경로가 다를 수 있기 때문이다. 봇이 /opt/repo/CLAUDE.md를 찾으러 갔을 때 파일이 없거나, 전역 지침이 누락되었거나, 상속 링크가 깨져 있을 수 있다.

그래서 배포 후 검증 단계를 넣었다:
- 각 프로젝트 CLAUDE.md가 제대로 로드되는가?
- 전역 지침이 실제로 포함되고 있는가?
- 순환 참조는 없는가?

이렇게 하면 "어라, 봇이 예전 규칙을 따르네?" 같은 버그를 배포 후가 아니라 배포 전에 잡을 수 있다.

회고

이 작업 자체는 코드 라인이 많지 않지만, 팀이 성장하면서 필요한 "조직화 작업"이었다. 처음에는 "문서만 정리하는데 왜 검증이 필요한가"라고 생각할 수 있지만, 실제로는:

1. 지침이 코드만큼 중요하다. 봇의 동작을 결정하는 규칙이니까, 이게 제대로 로드되지 않으면 팀 전체의 일방식이 깨진다.

2. 확장성 있게 설계해야 한다. 프로젝트가 2개일 때는 각자 관리해도 되지만, 5개, 10개가 되면 중앙화가 필수다.

3. 자동화와 검증은 사소한 작업에 더 필요하다. 코드는 테스트를 짜지만, 설정 문서는 수동 검토하기 쉽기 때문에 실제 버그는 문서 계층에서 자주 생긴다.

다음 팀이 규칙을 추가할 때는, 아마 "어느 CLAUDE.md에 써야 하나?" 하는 고민이 줄어들 것 같다.

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

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

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