일기 slecs

문서 계층화로 팀 지침 일관성 확보

목차

lotto 사이트에 CLAUDE.md 캐스케이드 구조를 추가했다. 한 문장이지만 뒤에는 제법 있는 이야기가 있다.

멀티사이트 환경에서 도큐먼트 중복의 고통

내가 관리하는 여러 사이트와 서버들이 있다. 각각은 조금씩 다른 기술 스택, 다른 규칙, 다른 팀 컨텍스트를 가지고 있다. Claude를 비롯한 LLM 도구들을 쓸 때마다 "이 프로젝트의 컨벤션이 뭐지?", "이 팀의 코딩 룰은?" 같은 지침을 공급해야 한다. 그게 CLAUDE.md — 각 프로젝트별 AI 도구 가이드다.

문제는 단순했다. 공통 룰은 매번 복붙, 사이트별 특수사항만 다르다. 여러 곳에 같은 내용이 흩어져 있으면, 중앙 정책이 바뀔 때마다 모든 파일을 찾아다니며 수정해야 한다. 토큰 비용 지침을 바꿨다 → 5개 사이트에 뿔뿔이 산재된 CLAUDE.md를 일일이 갱신. 기술 스택을 추가했다 → 또 그 과정의 반복. 이건 스케일하지 않는다.

캐스케이드 구조: 전역 → 사이트별 상속

그래서 계층화했다.

/opt/ops/docs/server-global-CLAUDE.md  ← 전체 서버 공통 가이드
  ↓ symlink
~/.claude/CLAUDE.md  ← 각 사이트의 진입점
  ↓ 
/opt/<each-site>/CLAUDE.md  ← 사이트별 추가 규칙

이제 흐름은 이렇다. Claude가 어떤 사이트에서 실행되면, 먼저 그 사이트의 로컬 CLAUDE.md를 읽는다. 그 안에는 "전역 규칙은 /opt/ops/docs/server-global-CLAUDE.md 참고"라는 링크만 있고, 사이트별 특수사항만 담는다. 예를 들어 "이 사이트는 BQ 권한이 필요하다" 같은 것들.

중앙의 공통 정책이 바뀌면? 한 곳만 수정하면 된다. 각 사이트는 자동으로 최신 공통 가이드를 따르고, 자기만의 추가 설정을 덧붙인다. 이게 바로 "캐스케이드" — 상위에서 하위로 자연스럽게 흘러내린다.

"서버검증"의 의미

lotto 사이트가 실제로 이 구조를 따르도록 했을 때, 정말로 작동하는지 확인했다. 즉, "이 CLAUDE.md 파일이 실제 서버 환경에서 로드되고, 설정이 제대로 적용되나?"를 검증한 거다. 단순해 보이지만, 실제 운영 환경에서는 symlink가 깨진다든지, 파일 경로가 맞지 않는다든지, 읽기 권한이 없다든지 하는 일이 벌어질 수 있다. 그래서 "서버검증"은 "이거 실제로 운영 환경에서 정상 작동함을 확인했다"는 의미다.

온보딩과 일관성 유지의 효과

이렇게 하니 몇 가지가 편해졌다.

새로운 팀원이 들어올 때, "CLAUDE.md 읽어 봐"라고 하나만 가리킬 수 있다. 그들이 읽는 파일은 전역 가이드를 자동으로 따르면서도, 해당 사이트의 컨텍스트를 함께 제시한다. 두 개 파일을 번갈아 읽을 필요 없다.

정책 변경이 한결 수월해졌다. AI 도구 사용 가이드나 토큰 관리 방식을 바꿀 때, 한 곳만 손대면 모든 사이트가 자동으로 따른다. 실수로 어디선가 빠뜨릴 일도 없다.

문서 리뷰도 간단해진다. "전역 정책은 진짜로 전역인가?", "이 설정이 모든 사이트에서 필요한가?" 같은 질문을 체계적으로 물을 수 있다. 사이트별 예외는 명확하게 구분되고, 공통 부분은 중앙에서 한 번만 관리된다.

다른 설정 문서에도 적용 가능한 패턴

이 구조는 CLAUDE.md에만 해당하는 게 아니다. 팀 규모가 커지고 운영하는 서비스가 많아지면, 어느 조직이든 비슷한 문제를 만난다. 데이터베이스 연결 설정, 배포 파이프라인 규칙, 보안 정책, 성능 임계값 같은 것들이 "공통 부분"과 "사이트별 오버라이드"로 나뉜다. 이때 계층적 구조를 먼저 생각하면, 나중에 수정과 확장이 훨씬 깔끔해진다.

반대로, "일단 각 사이트마다 복사해서 관리하자"는 방식은 처음엔 빠른 것 같지만, 6개월 뒤쯤 되면 어느 파일이 어느 정책을 반영하는지 헷갈리기 시작한다. 중앙 정책이 진짜 중앙인지, 아니면 어딘가에서 이미 바뀐 건지 불분명해진다.

이번 작업은 작은 changes 이지만, 팀의 규모가 커지고 사이트가 늘어나는 상황에서 "문서도 구조화하자"는 신호였다. 코드만큼 문서도 DRY 원칙을 따르면, 관리 비용이 주는 대신 신뢰도가 올라간다.

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

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

이어보기

댓글 0

첫 댓글 달아줘.