Claude 지침을 사이트별로 계층화

insurance 사이트별 CLAUDE.md를 캐스케이드 구조로 추가했다. 여러 사이트를 운영하면서 전역 지침과 사이트별 지침을 동시에 관리해야 했는데, 단순히 파일을 나누는 것만으로는 충분하지 않았다.

캐스케이드 구조가 필요했던 이유

초반에는 서버 전역 CLAUDE.md 하나에 모든 지침을 몰아둔 상태였다. 각 사이트마다 봇이 실행될 때마다 이 파일 전체가 컨텍스트에 로드되곤 했는데, 문제는 두 가지였다.

첫째, 토큰 비용. 매 봇 호출마다 전역 지침이 통째로 들어가니 중복과 낭비가 심했다. 특정 사이트는 그 사이트에만 필요한 규칙을 받아야 하는데, 다른 모든 사이트의 지침까지 읽게 되는 셈이다. 둘째, 보안 격리. 어떤 사이트의 내부 정책이나 운영 규칙이 다른 사이트의 봇에 노출되면 안 되는 경우가 있다. insurance 사이트는 특별히 더 그런 부분이 컸다.

결과적으로 전역에서 "이건 모든 봇 공통", "이건 insurance만의 룰"을 매번 섬세하게 구분하려던 초기 방식은 유지보수가 힘들었다.

계층적 로드 구조로 전환

이번에 도입한 구조는 이렇다:

전역 파일은 정말 "모든 봇의 모든 호출에 적용되는 최소 규칙"만 담고, insurance 같은 특정 사이트의 세부 지침은 그 프로젝트 아래 별도 CLAUDE.md에 뒀다. 봇이 시작될 때 어느 디렉토리에서 실행되는지에 따라 자동으로 그 사이트의 지침을 먼저 읽게 되고, 전역 지침은 뒤에서 fallback처럼 작동한다.

실제로는 symlink도 활용했다. 서버의 /home/hedvion/.claude/CLAUDE.md 는 ops 저장소의 server-global 파일로의 심볼릭 링크로 유지하되, insurance 같은 사이트별 디렉토리에는 로컬 CLAUDE.md를 두는 방식이다. 이렇게 하면 ops에서 전역 지침을 한 번만 수정해도 모든 봇이 그걸 따르면서도, 사이트별로는 독립적인 오버라이드가 가능하다.

서버 검증이 중요했던 이유

단순히 파일을 나열했다고 끝이 아니었다. 실제로 봇이 올바른 파일을 로드하는지, symlink가 올바르게 풀리는지, 경로 구조가 일관되는지를 서버에서 직접 확인해야 했다.

예컨대 심볼릭 링크가 깨져 있으면 봇은 그걸 알아채지 못하고 오래된 캐시된 지침을 쓸 수도 있다. 또한 여러 사이트의 봇이 동시에 돌아가는 환경에서 CLAUDE.md 로드 순서가 보장되지 않으면 일관성이 깨질 수 있다. CI/CD나 배포 프로세스를 통해 "이 커밋 이후로 정말 새로운 지침이 적용되고 있는가"를 검증하는 단계가 필수였다.

배운 점과 앞으로

이 구조를 다루면서 깨달은 것은, 프로그래밍 코드만 계층적으로 관리할 게 아니라 AI 어시스턴트의 지침도 같은 방식으로 관리할 수 있다는 것이었다. 토큰 비용 절감, 보안 격리, 유지보수성—이 모든 게 단순한 파일 구조 개선으로 해결된다.

다만 조심할 점도 있다. 캐스케이드의 계층이 깊어지면 어느 지침이 최종적으로 적용되는지 추적이 어려워진다. 그래서 문서화를 명확히 하고, 특히 서버 검증 같은 자동화 단계를 빠뜨리면 안 된다. 또 사이트별 지침을 추가할 때마다 보안·격리 정책을 다시 한번 체크하는 습관도 필요하다.

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

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

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