조직 전체 AI 도구 지침, 계층적으로 통일

여러 프로젝트와 사이트에 걸쳐 개발자 도구 설정 문서(CLAUDE.md)를 계층적으로 관리하는 구조를 추가했다. 전역 지침에서 시작해서 각 사이트별, 프로젝트별로 오버라이드되는 캐스케이드 방식인데, 이제 서버 환경에서도 이 구조가 제대로 로드되는지 검증했다.

조직이 커지면서 마주친 설정 분산 문제

처음엔 간단했다. 개발자 도구 지침 한 개를 홈 디렉토리에 둬도 됐다. 하지만 조직이 성장하면서 상황이 복잡해졌다. ops 팀의 정책이 있고, 다양한 사이트들(예: 결제, 이커머스, 운영 플랫폼)이 생겼으며, 각 사이트 내에서도 여러 마이크로서비스가 동작하기 시작한 것.

그때부터 문제가 터졌다:
- 전역 규칙을 모든 사이트가 따라야 하는데, 특정 사이트나 팀은 추가 규칙이 필요했다
- 같은 내용을 여러 곳에 복붙하게 되니까 수정할 때마다 일관성이 깨졌다
- 새로운 팀원이 어느 규칙을 우선적으로 따라야 할지 헷갈렸다
- 문서와 실제 서버 동작이 안 맞는 상황도 생겼다

이런 문제는 사실 모든 조직에서 공통적으로 겪는다. 설정 관리를 한곳에만 두면 확장이 어렵고, 분산해서 두면 일관성이 떨어진다. 우리는 "계층적 상속"으로 이 둘을 균형 맞추기로 했다.

계층 구조: 전역 → 사이트 → 프로젝트

지침 문서가 이렇게 로드되도록 설계했다:

1. 전역 지침 (홈 디렉토리)
   ~/.claude/CLAUDE.md
   └─ ops 저장소의 중앙 정의 (symlink)

2. 사이트별 지침 (새로 추가)
   /opt/<site>/CLAUDE.md
   └─ 예: /opt/payment/CLAUDE.md, /opt/ecommerce/CLAUDE.md

3. 프로젝트별 지침 (기존)
   /opt/<site>/<project>/CLAUDE.md
   └─ 예: /opt/payment/order-svc/CLAUDE.md

뒤에 오는 규칙이 앞의 규칙을 오버라이드한다. 덕분에:
- 결제 사이트의 모든 프로젝트는 결제팀 규칙을 자동으로 적용한다
- 특정 프로젝트는 추가로 자신만의 규칙을 가질 수 있다
- 전역 룰을 바꾸면 모든 곳에 한 번에 반영된다

이는 DRY(Don't Repeat Yourself) 원칙을 지키면서도 각 팀의 자율성을 존중하는 방식이다.

서버검증을 통해 실제 동작 확인

문서만 작성해서는 부족했다. 개발자 머신(맥)에서는 잘 작동하지만, 서버에서도 같은 방식으로 로드되는지 확인해야 했다. CI 환경, 서버 권한, 파일 경로 등이 로컬과 다를 수 있기 때문이다.

서버검증 과정에서:
- 심볼릭 링크가 제대로 따라가지는지 확인했다
- 경로별 로드 순서를 추적해서 실제 캐스케이드가 일어나는지 검증했다
- 권한 문제로 인한 로드 실패 시나리오를 테스트했다

이렇게 "실제 환경에서 작동한다"는 확신이 생겨야 팀에 신뢰할 수 있는 지침이 된다.

팀에 미친 영향과 배운 점

이 구조 덕분에 몇 가지가 좋아졌다:

"프로젝트별 지침까지만 있으면 되지 않을까"라고 생각했을 때도 있다. 하지만 팀 규모가 커지고 사이트별 특수성이 생기니, 중간 단계의 사이트 지침이 정말 필요했다. 팀 리딩 관점에서 보면, 전체를 통일하되 각 팀의 자율성을 보장하는 구조가 문화적으로도 중요하다는 걸 깨달았다.

이 작업은 결국 "문서화"가 아니라 "조직 구조 정리"였다. 기술 도구 설정이 비즈니스 조직 구조를 따라가야 한다는 원칙을 실행에 옮긴 것이다. 다음번에 유사한 설정 관리 문제가 생기면, 이 패턴을 먼저 떠올릴 것 같다.

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

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

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