프로젝트 문서 캐스케이드로 싱크 비용 줄이기

최근 job 사이트별로 흩어져 있던 CLAUDE.md 파일들이 상위 공통 설정 문서로부터 캐스케이드되도록 개선했다. 단순해 보이지만 꽤 실질적인 변경인데, 이 작업의 맥락과 배운 점을 정리해본다.

왜 이런 구조가 필요했는가

팀이 성장하면서 각 프로젝트, 각 서버, 각 job 스크립트마다 "로컬" 설정 문서가 생겨났다. 처음에는 각자 독립적으로 관리하는 게 맞았다. 하지만 시간이 지나면서 공통 규칙들이 생겼다:
- "출력은 요청 형식만 낸다"
- "날짜·연도 기준은 2026년"
- "메타 문구 금지"

이런 규칙들은 모든 봇에 적용되어야 하지만, 각 CLAUDE.md에 따로 따로 적혀 있으니 한곳을 수정할 때마다 다른 곳들도 다 찾아 손 봐야 했다. 특히 서버 환경에서는 symlink로 중앙 설정을 가리키고 있었는데, 로컬 프로젝트들은 여전히 복사본을 쓰고 있어서 싱크가 깨졌다.

캐스케이드 구조 도입

해결책은 간단했다: 각 프로젝트의 CLAUDE.md가 "상위 공통 설정"을 명시적으로 참조하고, 프로젝트별 세부사항만 추가하도록 구조화했다.

# 구조 개선 전
ops/CLAUDE.md (중앙 규칙)
job-a/CLAUDE.md (규칙 + 프로젝트 세부)  ← 복사본
job-b/CLAUDE.md (규칙 + 프로젝트 세부)  ← 복사본

# 개선 후
ops/CLAUDE.md (중앙 규칙)
job-a/CLAUDE.md (→ "ops의 설정을 상속받음" + 프로젝트 세부)
job-b/CLAUDE.md (→ "ops의 설정을 상속받음" + 프로젝트 세부)

실제 구현은 마크다운의 "include" 패턴이나 상세한 참조 주석으로, 각 프로젝트의 CLAUDE.md에 "이 파일은 상위 공통 규칙에 종속됨"이라는 명시를 추가했다. 로더(봇이 파일을 읽는 로직)는 이미 계층 구조를 이해하고 있었으므로, 문서 구조만 명확하게 하면 충분했다.

운영 관점의 효과

이게 중요한 이유는 "관리 비용"의 관점이다. 문서가 중복되어 있으면 한 곳 실수가 전체에 파급된다. 예를 들어 올해 연도를 2027년으로 바꿔야 한다면, 예전 방식대로라면 모든 CLAUDE.md를 순회해야 했다. 지금은 중앙 파일 한 곳만 고치면 다음 봇 호출부터 자동 반영된다.

배운 점: 언제 이런 구조가 필요한가

이 패턴은 문서뿐 아니라 설정 파일, 환경 변수, 테스트 fixture 같은 곳에서도 마주친다. 내 판단 기준은:

• 변경 빈도: 공통 규칙이 자주 바뀐다면 캐스케이드는 투자 가치가 있다.
• 프로젝트 수: 3개 이상 같은 규칙을 갖고 있다면 상속 구조 고려.
• 온보딩 비용: 새 팀원이 "뭘 복사해야 하지?" 묻는 순간이 신호.

side 작업처럼 보이지만, 이런 개선이 쌓이면 팀의 "운영 마찰"이 확실히 줄어든다. 다음번엔 더 빨리 움직일 수 있다.

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

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

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