일기 slecs

계층화된 지침 구조로 문서 관리 효율성 높인 일

목차

admin 도구와 관련된 지침을 CLAUDE.md에 추가하면서, 동시에 문서의 계층화 구조를 정리했다. 서버에서 실제 동작을 검증하며 느낀 문서 설계의 중요성을 정리해본다.

문서 계층화가 필요했던 이유

팀이 성장하고 운영 서버, 개발 서버, 로컬 환경 등 여러 환경을 다루다 보니 지침 문서의 관리 복잡도가 증가했다. 처음엔 하나의 CLAUDE.md에 모든 규칙을 때려 박았는데, 이 방식엔 명백한 문제가 있었다.

  • 전역 규칙과 환경별 규칙이 섞임: 모든 팀원이 따라야 할 공통 규칙과 특정 서버/프로젝트에서만 필요한 규칙이 한 파일에 있으면, 어떤 규칙이 자신에게 해당하는지 판단하기 어렵다.
  • 중복 작성의 악순환: 비슷한 규칙을 여러 프로젝트 문서에 반복 작성하면, 나중에 규칙을 수정할 때 모든 곳을 찾아다니며 업데이트해야 한다. 실수로 놓친 곳이 생기고, 일관성이 깨진다.
  • 유지보수 비용 증가: 문서가 많아질수록, 문서 간 모순을 찾기 어렵고, 새로운 팀원이 어떤 규칙을 따를지 고민한다.

캐스케이드 구조: 상속과 오버라이드

이번 작업에서 도입한 "캐스케이드" 구조는 프로그래밍의 상속 개념을 문서에 적용한 것이다.

계층 역할 예시
전역(Global) 모든 환경의 기본 규칙 출력 형식, 보안 정책, 날짜 기준
서버/환경 특정 환경의 추가/오버라이드 규칙 서버 검증 방식, 배포 프로세스
프로젝트 특정 리포 내 규칙 코드 스타일, 테스트 요구사항

이 구조의 핵심은, 자식 문서가 명시적으로 재정의하지 않는 한 상위 계층의 규칙을 자동 상속한다는 점이다. 이렇게 하면:

  • 전역 규칙을 한 곳에서만 관리한다 (단일 진실 공급원).
  • 각 환경/프로젝트는 필요한 부분만 오버라이드한다.
  • 새로운 팀원도 "이 레벨에서 뭘 봐야 하나"가 명확해진다.

Admin 지침 추가: 실제 사례

이번 commit에서 admin 도구 관련 지침을 추가하면서, 위 캐스케이드 구조를 실제로 적용했다.

전역 CLAUDE.md 에는 "모든 봇이 따를 기본 규칙" (입출력 형식, 토큰 비용 고려 등)을 두고, admin 관련 세부 지침은 별도의 계층에 두었다. 예를 들어:

/opt/ops/docs/server-global-CLAUDE.md  (전역 기본 규칙)
  ↓ 상속
/opt/<특정-리포>/CLAUDE.md  (그 리포의 추가 규칙)
  ↓ 오버라이드
/.claude/CLAUDE.md  (로컬 프로젝트 오버라이드)

admin 지침은 "admin 도구를 다루는 봇이 로드할 때만 필요한 규칙"이므로, 전역에 넣지 않고 admin 전용 layer에 두게 된다. 그러면 다른 개발자는 시스템이 복잡하다고 느끼지 않으면서도, admin 도구를 다루는 팀은 명확한 가이드라인을 갖게 된다.

서버 검증: "이게 정말 먹히나"를 확인하다

commit 메시지에 "(서버검증)" 을 붙인 이유가 있다. 문서 구조를 잘 짜는 것도 중요하지만, 실제 서버 환경에서 그 구조가 정상 동작하는지 확인하지 않으면 의미가 없다.

파일 경로가 맞는지, symlink가 제대로 해석되는지, 실제 봇 호출 시 캐스케이드 로딩이 예상대로 되는지 모두 검증했다. 개발 환경에선 잘 되는데 서버에선 경로 해석이 다르거나, 퍼미션 문제로 읽지 못하는 경우가 왕왕 있기 때문이다. 특히 문서 시스템처럼 여러 봇이 동시에 로드하는 구조라면 경쟁 조건(race condition)도 생각해봐야 한다.

배운 점과 앞으로

이 작업을 하며 느낀 것:

  1. 문서도 코드처럼 구조를 생각해야 한다. 상속, 모듈화, 단일 진실 공급원 같은 소프트웨어 원칙이 문서에도 그대로 적용된다.

  2. 팀이 자라면서 계층화는 필수다. 팀 규모가 작을 땐 "한 문서에 다 때려 박기"도 괜찮지만, 5명 이상 협업하면 관리 비용이 급증한다.

  3. 문서 변경도 검증이 필요하다. 문서는 "확인하지 않고 배포"하기 쉬운데, 실제로 그 문서가 의도한 대로 로드되고 적용되는지 한두 번은 서버에서 확인해야 한다. 단순 "파일이 존재하는가"가 아니라 "실제 동작하는가"를 본다.

계층화된 문서 구조가 자리 잡으면, 새로운 환경이나 도구가 추가될 때도 더 깔끔하게 대응할 수 있다. 각 계층이 명확한 책임을 가지니까.

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

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

이어보기

댓글 0

첫 댓글 달아줘.