설정 캐스케이드 구조 명시화

여러 팀이 각각 다른 Claude 설정을 쓰게 되면서, 공통 규칙과 팀별 규칙 사이의 우선순위가 애매해지는 문제에 직면했다. 누가 global CLAUDE.md를 수정하면 모든 팀에 영향이 갈 텐데, 각 팀은 자기 사이트/프로젝트만의 규칙도 필요했다. 결국 "어느 설정이 우선인가" 하는 질문이 반복됐고, 새 팀원들은 어느 파일을 봐야 하는지 헷갈렸다.

이번 작업에서는 CLAUDE.md 파일들의 계층구조를 명시적으로 문서화했다. global → site → project 순서로 상속되고, 아래 단계의 설정이 위 단계를 오버라이드한다는 규칙을 콘크리트하게 박아놨다. 서버 환경에서도 실제로 이 구조가 먹히는지 검증했고, 팀원들이 참고할 수 있도록 정리했다.

암묵적 우선순위의 비용

처음엔 "설정은 그냥 파일에 있는 거지, 뭘 복잡하게" 싶을 수 있다. 하지만 조직이 10명 규모를 넘어가면서 변화가 생긴다. 예를 들어 내가 global CLAUDE.md에서 "모든 출력에서 인사말 금지"라고 수정했는데, 어떤 팀의 프로젝트 CLAUDE.md에는 "팀 내부용이니까 인사말 포함하기"라고 이미 쓰여 있었다. 그럼 둘 중 뭐가 진짜 규칙인가?

이런 상황에서 팀 간 마찰이 생긴다. 한쪽은 "global이 바뀌었으니까 우리도 맞춰야지"라고 하고, 다른 쪽은 "우리 프로젝트는 자체 규칙이 있었는데?"라고 한다. 개인별로 물어도 답이 다르다. 이건 단순 문서 문제가 아니라 의사결정 구조의 부재였다.

계층을 설계할 때는 문서가 룰

결국 그냥 파일을 만드는 게 아니라, "왜 이 순서인가"를 적어야 한다는 깨달음이 왔다.

global CLAUDE.md: 모든 봇이 따를 수 없는 하한선(floor). "출력 형식은 요청한 포맷만", "인사말 금지" 같은 건 어디서나 지켜야 함.

site/도메인 CLAUDE.md: 우리 조직 내 특정 사이트(예: legal 처리 사이트)에만 적용. "이 도메인은 보안 감사 기록을 남긴다" 같은 걸 한 곳에 정의.

project/repo CLAUDE.md: 특정 프로젝트의 코드 스타일, 네이밍, 온보딩만의 특수성. "이 repo는 TypeScript strict mode 쓴다" 같은.

아래로 갈수록 구체적이고, 위로 올라갈수록 일반적이다. 충돌 나면 아래(구체적)가 이긴다. 이렇게 문서에 박아놓으니, 팀원들이 "어느 파일을 봐야 하나?"라고 물을 일이 없어졌다. 자신의 프로젝트 CLAUDE.md를 보고, 없으면 site, 그 다음 global 순서로 찾으면 된다.

서버 환경과 symlink의 현실성

처음 계획할 땐 이론이 깔끔했다. 그런데 실제 서버 환경에서는 symlink, 파일 권한, 자동 업데이트 같은 게 개입한다. ops 저장소의 master를 건드리면, 모든 서버의 symlink를 통해 바로 반영되어야 한다. 반대로 한 프로젝트의 CLAUDE.md를 손대는 건 그 프로젝트만 영향을 줄 수 있어야 한다.

이번에 "서버 검증"을 거친 건, symlink가 정말 깨지지 않는지, 캐스케이드 로딩이 실제로 작동하는지를 확인한 것. 이론만 예쁜 구조보다는, 실제 운영 환경에서 안정적인 게 중요했다.

다음 번엔 처음부터 계층을 생각한다

이 작업을 하면서 배운 가장 큰 교훈은, 설정 시스템을 만들 때부터 우선순위를 설계하는 게 낫다는 것이다. 나중에 "어? 이게 왜 안 되지?"라고 물어본 후 문서를 쓰는 건 너무 비효율적이다. 처음부터 "공통은 여기, 팀별은 여기, 프로젝트별은 여기"를 정하고, 그걸 명시적으로 코드나 문서에 박아놔야 한다. 팀이 작을 땐 암묵적 합의가 통하지만, 10명을 넘으면 "우리가 이렇게 했던 거 같은데?"는 분쟁의 시작이다.

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

• 모니터 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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