일기 slecs

설정 파일 중복을 계층 구조로 정리하기

목차

여러 사이트를 운영하면서 AI 봇 설정 파일이 자꾸 중복되는 문제가 있었다. 이번에 CLAUDE.md를 사이트별로 계층적으로 관리할 수 있게 개선했다.

다중 서비스 환경에서의 지침 관리 과제

혼자 하던 프로젝트와 달리, 여러 사이트가 떠있으면 "이 규칙은 어디까지 적용해야 하나?"라는 질문이 자꾸 생긴다. 전역 지침도 필요하고, 특정 서비스만의 규칙도 있고, 팀이 달라지면 또 다르다. CLAUDE.md 파일이 여기저기 흩어지거나 중복되다 보면:

  • 중앙에서 규칙을 바꿀 때마다 모든 사이트를 일일이 수정해야 함
  • 어느 버전이 정본인지 헷갈림
  • 토큰 낭비 (매 호출마다 설정을 로드하는데, 불필요한 내용도 함께 로드됨)
  • 새로운 사이트 추가할 때 어떤 파일을 어디에 둬야 할지 불명확

이런 상황에서는 설정 파일도 "단일 진실 공급원(Single Source of Truth)" 원칙을 적용해야 한다.

계층 캐스케이드 구조의 필요성

사실 이런 문제는 CI/CD 설정(.yaml), 환경 변수(.env), 패키지 관리(monorepo) 등 여러 곳에서 마주친다. 보통의 해결책은 상위 → 하위로 내려오면서 필요한 부분만 오버라이드하는 방식이다.

예를 들어:
- 글로벌 레벨: 회사 전체의 기본 규칙 (보안, 아웃풋 포맷, 토큰 비용 주의사항)
- 서버 레벨: 이 서버에서 실행되는 모든 봇이 따를 공통 사항
- 프로젝트/사이트 레벨: 특정 서비스의 고유한 규칙 (DB 구조, API 스타일, 팀 컨벤션)

캐스케이드(waterfall)라고 부르는 이유는, 상위의 설정이 아래로 "흐르면서" 더 구체적인 규칙으로 좁혀진다는 뜻이다. 봇이 어떤 사이트에서 호출될 때는:

1. 글로벌 설정 파일 로드
2. 현재 서버의 설정 파일 로드 (글로벌과 중복되면 덮어씀)
3. 현재 프로젝트의 설정 파일 로드 (위의 것들을 덮어씀)
→ 최종 효과적인 설정이 결정됨

설계: 토큰 비용과 우선순위

이 구조를 실제로 도입할 때는 두 가지를 균형잡아야 한다.

첫째, 토큰 낭비를 피하기. CLAUDE.md는 매 봇 호출마다 로드되므로, 글자수가 많으면 누적 비용이 빠르게 는다. 그래서 글로벌 설정은 "정말 필요한 것"만 담고, 프로젝트별 상세한 규칙은 각각의 CLAUDE.md에만 둔다. 동시에 글로벌에선 "이 아래는 각 사이트의 CLAUDE.md에서 오버라이드하세요"라고 명시해놔야 혼동을 줄인다.

둘째, 명확한 우선순위 문서화. 어떤 설정이 충돌했을 때 어느 것이 이기는지 모르면, 디버깅이 지옥이 된다. 따라서 캐스케이드 순서를 명시적으로 쓰고, "이 파일에 없으면 저 파일을 본다"는 폴백 규칙도 정의한다. 이걸 docs나 설정 파일 주석에 명확하게 둔다.

셋째, 대칭성 유지. 모든 사이트가 같은 구조로 설정되어야 나중에 새로운 인력이 들어왔을 때 빨리 따라잡는다. "이 사이트는 CLAUDE.md가 3단계, 저 사이트는 2단계"라고 하면 혼란스럽다.

서버 환경에서의 검증

실제 서버에 배포하기 전에 검증 단계는 중요하다. 특히 지침 파일처럼 "눈에 띄게 깨지지 않지만, 봇의 행동을 은근히 바꾸는" 것들은 더 그렇다.

이번 커밋에서 "(서버검증)"이라고 표기한 것은 서버 환경에서 실제로 캐스케이드가 제대로 동작하는지 확인했다는 뜻이다. 예컨대:
- 각 경로의 파일이 정확히 로드되는가
- 충돌할 때 우선순위가 맞게 적용되는가
- 파일이 없는 사이트도 정상적으로 폴백되는가

서버에서 직접 테스트하는 이유는, 로컬 개발 환경과 서버의 디렉토리 구조, symlink 처리, 권한 설정이 다를 수 있기 때문이다.

회고: 계층화의 가치와 비용

이런 작업을 하다 보니 느낀 점이 몇 가지 있다.

첫 번째, 중앙화와 자율성의 균형. 팀장 입장에서는 모든 팀이 공통 규칙을 따르길 원하지만, 각 팀은 자신들의 사정에 맞게 커스터마이징하고 싶어한다. 계층 구조는 이 두 욕구를 동시에 충족시켜준다. "꼭 따라야 할 것"은 글로벌에, "자유롭게 확장할 부분"은 로컬에 두는 식으로.

두 번째, 문서화의 중요성. 코드는 자명하지만(예: 폴더 구조, 파일명), 사람의 합의는 그렇지 않다. "이 CLAUDE.md는 어디에 둬야 하나?", "이 규칙은 글로벌인가 로컬인가?"라는 질문이 계속 나온다. 따라서 설계 초기에 README나 주석으로 명확하게 기록해두는 게 투자다.

세 번째, 점진적 확장의 여유. 처음부터 완벽할 필요는 없다. 글로벌 + 프로젝트 2단계로 시작해서, 필요하면 중간 계층(팀별, 환경별)을 추가할 수 있다. 구조가 유연하면 나중에 확장하기가 쉽다.

결국 설정 파일이 code만큼 중요하다는 걸 배웠다. 특히 분산 환경에서는 더욱.

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

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

이어보기

댓글 0

첫 댓글 달아줘.