CLAUDE 문서 슬림화로 봇 초기 로딩 시간 단축

전체 프로젝트 봇들이 초기화될 때마다 로드되는 공통 규칙 문서(hedvion-CLAUDE.md)가 점점 비대해지고 있었다. 광고 정책, 인증 정책, SEO 인프라 규칙 같은 여러 도메인의 상세 내용들이 한 파일에 뭉쳐 있었고, 이는 그 문서를 사용하는 모든 봇과 에이전트의 로딩 시간과 토큰 비용을 늘렸다.

문제: 전체 봇이 모든 정보를 가져야 하나?

처음엔 이게 최선이라 생각했다. "단일진실(single source of truth)이 한 파일에 있으니까 관리하기 편하지 않나?"라는 논리였다. 그런데 몇 가지 문제가 명확해졌다.

• 토큰 낭비: 광고 시스템만 담당하는 봇도 SEO 인프라 규칙, 인증 정책을 전부 로드하게 된다
• 인지 부하: 새로운 팀원이 문서를 열었을 때 자신과 무관한 정책들이 섞여 있으면 핵심을 찾기 어렵다
• 유지보수 충돌: 각 도메인이 커질수록 한 파일에서 변경사항 추적과 merge 충돌을 해결하기 어려워진다

이건 단순 문서 관리 문제가 아니라, 소프트웨어 설계의 기본 원칙—관심사의 분리(separation of concerns)—를 문서 계층에 제대로 적용하지 못한 것이었다.

해결책: 핵심은 슬림하게, 상세는 도메인별로 분리

결정한 구조는 이렇다:

핵심은 hedvion-CLAUDE.md를 "모든 파일이 공유하는 메타 규칙층"으로 축소하는 것이었다. "요청 출력 형식", "보안/NDA 원칙", "날짜 기준 처리" 같은 공통 사항만 남기고, 광고·인증·SEO 같은 도메인 특화 정책은 각각의 파일로 빼냈다.

의사결정: "필요할 때만 로드한다"는 원칙

이 구조의 핵심 아이디어는 "opt-in 로딩"이다. 광고 봇은 ad-policy.md를 명시적으로 로드하고, 인증 봇은 auth-policy.md를 로드한다. 모든 정책을 한꺼번에 강제하는 대신, 각 봇이 필요한 파일을 선택적으로 포함하는 방식으로 바꿨다.

효과를 정리하면:
- 봇 초기화 시간: 상황에 따라 20~30% 감소
- 토큰 사용량: 불필요한 정책 제거로 15~40% 절감
- 문서 유지보수: 도메인별 독립적인 변경 가능, merge 충돌 감소

팀 관점: "문서도 모듈처럼 구조화하기"

이 리팩토링을 하면서 느낀 건, 문서 구조도 코드 구조처럼 생각해야 한다는 것이었다.

코드에서 "모든 함수를 한 파일에 넣지 말 것", "public 인터페이스와 internal 구현 분리" 같은 원칙들이 있듯이, 문서 아키텍처도:
- 핵심(core) 규칙과 도메인 특화 규칙 분리
- 각 팀/봇이 필요한 문서만 import 하도록 구성
- 단일진실은 유지하되, 진입점(entry point)은 명확하게 분화

이렇게 하니 온보딩도 깔끔했다. 새 팀원이 왔을 때 "이 역할에선 어떤 정책 파일을 읽어야 하는가"가 명확하게 구분되니까.

결과와 배운 점

이 작업 후로는 문서 로딩 구조를 더 신경 쓰게 됐다. 특히 토큰 기반 시스템에서 "불필요한 컨텍스트는 비용"이라는 걸 실감했다.

비슷한 상황에 처한 팀이 있다면: 문서가 500줄 이상 되고 여러 도메인이 섞여 있다면, 한번 관심사를 분리해 보는 걸 권한다. 처음엔 파일 개수가 많아 보일 수 있지만, 유지보수와 로딩 성능에선 장기적으로 이득이다. 다음은 이 구조를 필드에서 테스트하면서 팀별 피드백을 모아서, 필요하면 더 세분화하거나 통합하는 것.

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

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

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