AI 지침 문서 계층화로 일관성 강화

최근 games-hub 프로젝트에서 사이트별 설정 문서(CLAUDE.md)의 캐스케이드 구조를 정리하고 서버 환경에서 이를 검증하는 작업을 했다. 한두 개 파일 수정으로 보이지만, 뒤에는 팀 간 협업과 AI 어시스턴트 활용 방식을 표준화하는 꽤 중요한 인프라 개선이 숨어 있었다.

계층화된 지침의 필요성

프로젝트가 여러 팀, 여러 사이트로 확장되면서 각각의 운영 규칙과 개발 가이드라인이 달라지기 시작했다. 글로벌 회사 레벨의 규칙이 있고, 팀별 규칙이 있고, 개별 프로젝트별 로컬 규칙이 있다. 처음엔 이게 다 한 곳에 뭉쳐 있었다. 그러다 보니:

• 어떤 지침이 어느 수준에서 적용되는지 불명확
• 팀 온보딩 시 참고할 설정을 찾기 어려움
• 글로벌 규칙 변경이 로컬 프로젝트에 영향을 주는지 추적 불가
• 새 팀이 합류할 때 어느 문서를 먼저 봐야 할지 애매

특히 AI 어시스턴트(우리 경우 Claude Code)가 매번 프로젝트를 돌 때 이 설정을 읽기 때문에, 지침이 명확하지 않으면 일관된 대응을 기대하기 어렵다. 누군가는 팀 규칙만 따르고, 누군가는 글로벌 규칙을 모르고, 누군가는 프로젝트 로컬 규칙을 발견하지 못한다.

캐스케이드 구조로 재정의

이번 작업에서 도입한 구조는 이렇다:

어시스턴트가 프로젝트에서 실행될 때, 이 세 파일을 모두 로드한다. 더 구체적인(로컬) 지침이 일반적인(글로벌) 지침을 override 한다. symlink를 통해 전역 설정은 한 곳에서만 관리되므로, 회사 정책 변경 시 모든 팀 리포지토리가 자동으로 따라간다.

서버 환경에서의 검증

단순히 문서를 작성하는 것만으로는 부족했다. "서버검증"은 실제 운영 환경에서:

• 각 경로의 파일이 제대로 존재하고 로드되는가
• symlink(전역 설정 → 각 팀 리포)가 정상 작동하는가
• 계층 간 충돌이나 누락이 없는가
• 어시스턴트가 지침을 순서대로 읽고 올바르게 적용하는가

실제로 서버에서 git pull 후 이 파일들이 어시스턴트 관점에서 제대로 로드되는지, 충돌이나 누락이 없는지를 점검하는 과정이었다. 로컬 개발 환경에서 동작한다고 해서 운영 서버에서도 동작하는 건 아니기 때문이다.

이런 구조가 팀에 주는 영향

겉보기엔 문서 정리일 뿐이지만:

• 확장성: 새로운 사이트가 추가되면 그 사이트용 CLAUDE.md 하나만 두면 된다. 전역 설정을 건드릴 필요 없음.
• 유지보수성: 회사 공통 규칙이 바뀌어도 전역 문서 하나만 수정하면, symlink를 따르는 모든 팀이 자동으로 반영됨.
• 명확한 온보딩: 새 팀장이 들어왔을 때 "당신의 프로젝트에는 이 세 CLAUDE.md 가 있고, 위에서 아래 순서로 읽힌다"는 설명 한 줄이면 충분.
• AI 어시스턴트 신뢰도: 일관된 지침을 읽으면 어시스턴트의 동작이 예측 가능해진다. 팀마다 다른 스타일로 대응하는 일을 줄일 수 있음.

회고

이 작업이 "side" 카테고리에 분류된 이유는 기능 개발이 아니기 때문이다. 하지만 팀장 입장에서 보니, 인프라 정리 작업이 때론 기능 개발보다 큰 장기 수익성을 가진다.

개인적으로 배운 점은, 문서 하나를 정리하는 게 아니라 문서 구조 자체를 투명하게 하는 것의 가치다. 앞으로 팀이 확장되어도, "규칙이 어디 있나요?" 질문이 적어질 것이고, 팀 간 협업할 때 규칙 충돌이 명확하게 해결될 것이다. 다음 온보딩도 더 빠를 것 같다.

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

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

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