프로젝트별 Claude 지침을 계층화하다

CLAUDE.md 파일의 사이트별 캐스케이드 구조를 추가했다. 단순해 보이지만 문서 관리의 복잡성을 한 차원 낮춘 작업이다.

문제: 전역 지침의 한계

기존에는 서버 전역으로 단 하나의 CLAUDE.md 만 관리했다. 이 파일은 ops 저장소의 central 문서로 symlink 연결되어 있었는데, 모든 프로젝트와 사이트가 이 하나의 문서를 공유하다 보니 여러 제약이 생겼다.

우리 팀은 여러 사이트와 프로젝트를 동시에 운영하고 있다. 각 프로젝트마다 Claude 호출 방식, 토큰 비용 정책, 보안 규칙이 전혀 다르다. 예를 들어 일부 사이트는 prompt caching을 적극 활용하고, 다른 프로젝트는 특정 파일 형식만 처리하거나, 또 다른 서비스는 외부 API 호출을 엄격히 제한한다.

이 모든 조건을 하나의 문서에 섞으면:
- 문서 비대화: 자신과 무관한 규칙이 잔뜩 섞여 있어서 관심사 분리가 어렵다
- 수정 위험성: 한 프로젝트의 규칙을 바꿀 때 다른 곳에 미칠 영향을 매번 신경 써야 한다
- 온보딩 어려움: 새 팀원이 "내 프로젝트에 어떤 규칙이 적용되나" 를 찾기 힘들다
- 변경 추적 혼란: git 히스토리가 무관한 프로젝트들의 변경으로 지저분해진다

해결: 계층적 캐스케이드 구조

이번 작업으로 CLAUDE.md 를 다단계로 구성했다:

Claude 호출 시 문서 로더는 이제 다음 순서로 작동한다:

1. 글로벌 규칙 로드 (기본값)
   → ~/.claude/CLAUDE.md (global)

2. 현재 작업 디렉토리 확인
   → /opt/<site>/CLAUDE.md 가 있다면 로드

3. 충돌 시 site-specific 규칙이 우선 (override)

실제 예시로 보면:
- Global에서: "출력은 메타 문구 없이" → 모든 사이트가 따름
- Site A에서: "추가로 prompt caching 사용" → A 사이트만 적용
- Site B에서: "외부 API 호출 금지" → B 사이트만 적용
- 우선순위: Site C에서 Global의 규칙을 다르게 정의했다면, C의 설정으로 실행됨

중복을 피하면서도 각 프로젝트의 특수성을 명확히 표현할 수 있다.

서버 검증과 배운 점

이 구조가 이론적으로만 좋은 게 아니라 실제 서버 환경에서 제대로 동작함을 확인했다. Symlink 체계, 파일 로드 순서, 우선순위 해결 로직이 의도대로 작동하는지 테스트했고, 기존 호출들도 여전히 정상이다.

이 작업으로 깨달은 게, 문서 구조도 소프트웨어 설계의 원칙을 따른다는 것이다. 상속, override, 우선순위 같은 개념들이 코드뿐 아니라 규칙 문서에도 중요하다. 특히 여러 팀이 관여하는 환경에서는 "누가 언제 어디서 뭐를 수정할 수 있는가" 를 명확히 하는 것이 실수와 갈등을 줄인다.

이제 각 프로젝트는 필요할 때 자신의 CLAUDE.md 를 만들어 글로벌 규칙을 상속받으면서 독립적으로 확장할 수 있다. ops 저장소의 변경 부담도 줄어들고, 각 팀은 자기 사이트의 규칙에만 집중할 수 있게 됐다. 또한 새로 합류하는 팀원도 "내 작업 디렉토리의 CLAUDE.md 를 보면 된다" 는 단순한 규칙으로 온보딩이 쉬워진다.

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

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

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