AI 프롬프트 규칙을 계층화 구조로 관리하기

ssulbox 환경에서 여러 사이트를 동시에 관리하면서 마주한 문제가 있었다. 각 사이트마다 특수한 AI 봇 지침(CLAUDE.md)이 필요한데, 모든 사이트가 지켜야 할 '공통 기본 규칙'도 있었다는 것. 이 둘을 어떻게 효율적으로 관리할지 고민하다가 CLAUDE.md 를 계층화 구조(캐스케이드)로 정리했다.

문제: 규모 커질수록 지침 관리가 복잡해진다

처음엔 각 사이트마다 전체 규칙을 다 박아두는 방식으로 운영했다. 단순하긴 했지만 몇 가지 문제가 생겼다:

• 중복 관리의 악순환: 공통 규칙(보안, 포맷, 금지사항 등) 하나를 수정할 때마다 모든 사이트의 파일을 찾아서 일일이 수정해야 함. 휴먼 에러 가능성이 높다.
• 토큰 낭비: 특정 사이트에서 실행되는 봇이 자기한테 필요 없는 다른 사이트의 규칙까지 로드하게 됨. 프롬프트 토큰이 계속 늘어난다.
• 읽기 어려움: 공통 규칙과 사이트별 특수 규칙이 뒤섞여 있으니 뭐가 필수이고 뭐가 선택인지 불명확.

팀 규모가 작을 땐 이 정도도 참을 수 있지만, 서비스가 확장되고 새로운 사이트가 계속 생기는 상황에선 구조적 해결이 필요했다.

해결: 글로벌과 사이트별 지침 분리

기본 원칙을 이렇게 정했다:

봇이 실행될 때 로드 순서는:
1. 글로벌 지침 로드 (기본값, 모든 사이트 적용)
2. 현재 사이트/프로젝트 지침 로드 (override/확장)
3. 더 specific한 지침이 general한 지침을 덮음

예를 들어:

# 글로벌 (ops/server-global-CLAUDE.md)
- 절대 실고객명/IP/비번을 출력하지 말 것
- 출력은 요청된 형식만
- 토큰 비용에 주의

# ssulbox 사이트A (/opt/ssulbox-a/CLAUDE.md)
- 기본 규칙은 상속받음
- 추가: "이 사이트는 결제 플랫폼이므로 금융 규칙 엄격하게"
- 추가: "내부 정책 관련 질문엔 '정책 문서 참조' 이상 말하지 말 것"

이번 커밋은 ssulbox 환경 아래의 여러 사이트들을 이 계층 구조에 맞춰서 정리한 작업이다. 서버에서 실제로 구동해서 "(서버검증)"했으니, 이 구조가 실제로 작동함을 확인한 상태라는 뜻.

이런 계층화의 효과

규칙을 분리한 후 몇 가지 효과가 있었다:

• 수정 효율: 공통 규칙을 한 곳에서만 관리하니 버그 수정이나 보안 정책 변경이 간단해짐
• 토큰 절감: 각 봇은 필요한 규칙만 로드하므로 불필요한 컨텍스트가 줄어듦
• 확장성: 새로운 사이트를 추가할 때 글로벌 기본을 그냥 상속받고 특수 규칙만 추가하면 됨
• 명확성: 파일을 읽을 때 "어디까지가 필수이고 어디가 선택인가"가 명확해짐

팀이 커지면서 느낀 점

코드 아키텍처나 마이크로서비스 철학과 비슷하게, 문서도 규모를 고려해서 설계해야 한다. DRY, Locality, Maintainability 같은 원칙들이 설정/지침 관리에도 똑같이 적용된다.

특히 AI 봇 지침처럼 "모든 호출마다 로드되는 컨텍스트"는 더더욱 신경 써야 한다. 한 줄이라도 불필요하면 누적되면 상당한 비용이 된다. 그래서 "이게 모든 사이트에 필수인가?" 질문을 자주 던지게 되고, 자연스럽게 계층화 구조가 나온다.

이번 작업으로 얻은 배운 점은: 초반에 "전체 동일"이 편해 보일 때도, 언젠가는 계층화가 필요해진다는 것. 아예 처음부터 성장 여지를 두고 설계하는 게 나중의 리팩토링 비용을 줄일 수 있다.

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

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

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