봇 설정을 효율적으로 관리하다

팀의 프로젝트와 사이트가 늘어나면서 봇 설정 문서(CLAUDE.md)도 함께 증가했다. 처음엔 각 사이트가 독립적이라 괜찮았지만, 시간이 지나니 문제가 보였다. 공통으로 적용할 규칙들이 여러 파일에 중복되고, 한곳을 수정하면 다른 곳도 일일이 찾아 고쳐야 했다. 특히 팀이 커지면서 "이 설정이 어디까지 반영됐지?", "누가 서버에서 git pull 했나?" 같은 의문이 자주 생겼다.

단일 진실 공급원의 필요성

설정을 관리하는 방식은 크기가 작을 땐 문제가 안 보인다. 하지만 조직과 프로젝트가 성장하면서 네 가지 문제가 동시에 터진다:

• 일관성: 공통 규칙이 사이트마다 조금씩 다르게 기록됨
• 유지보수: 전사 공통 정책이 바뀌면 모든 파일을 찾아 수정해야 함
• 검증: 설정이 실제로 반영됐는지 확인하기 어려움
• 토큰 낭비: 각 봇 호출마다 중복 내용을 로드하게 됨

내 팀의 글로벌 설정을 보면, 이미 "단일 진실 = hedvionCorp/ops 의 docs/server-global-CLAUDE.md"라고 명시해뒀다. 즉, 최상위 설정 파일이 있고, 서버나 각 사이트가 이를 symlink 또는 참조하는 구조를 목표로 한 것이다. 하지만 모든 사이트가 이 패턴을 따르진 않았고, lifecard 사이트는 특히 그랬다.

캐스케이드 구조 도입

이번 작업은 lifecard 사이트에 대해 이 캐스케이드 구조를 명확히 문서화한 것이다. 구조는 이렇게 설계했다:

1. 최상위: 전사 공통 CLAUDE.md (ops 저장소)
2. 중간: lifecard 사이트별 CLAUDE.md (공통 설정을 명시적으로 상속)
3. 하위: 각 프로젝트 또는 봇 호출 시점에서 적절한 레벨의 설정을 로드

마크다운으로 보면 이렇게 표기한다:

# lifecard CLAUDE.md

> 단일진실 = `hedvionCorp/ops` 의 `docs/server-global-CLAUDE.md`.
> 이 파일은 전사 공통 설정을 상속하며, 
> lifecard 사이트별 추가 규칙을 여기 정의한다.

이렇게 하면 각 파일을 열었을 때 "이건 누구의 설정인가", "어떤 상위 규칙을 따르나"가 즉시 명확해진다. 개발자가 설정을 추가할 때도 "전사 공통인지, 이 사이트만인지" 판단하기 쉬워진다.

서버 검증의 중요성

커밋 메시지에 "(서버검증)"이라고 달았다. 이게 중요한 이유는, 설정 문서는 작성만으로 끝나는 게 아니기 때문이다. 실제로 봇이 서버에서 실행될 때 이 설정이 제대로 로드되고, 캐스케이드 구조가 의도대로 동작하는지 확인해야 한다.

예를 들면:
- 서버에서 git pull 후 디렉토리 구조가 맞는지
- symlink가 올바르게 걸려 있는지
- 봇 호출 시 상위 설정이 먼저 로드되고 하위 설정으로 오버라이드되는지

이걸 확인하지 않고 문서만 남겨두면, 며칠 뒤 누군가 "어? 왜 이 설정이 적용 안 돼?"라고 물을 때 낭패를 본다. 특히 프로덕션 환경에서는 더욱.

캐스케이드의 실제 이점

이 구조를 도입하니 몇 가지가 달라졌다:

특히 팀이 커지면서 "이 설정은 누가 정했어?", "왜 이 사이트는 다르지?"라는 질문이 줄었다. 문서 자체가 구조를 명확히 하니까.

회고하며

처음엔 "설정 파일이 몇 개 뿐인데, 뭐하러 이렇게까지?" 싶었다. 하지만 프로젝트 규모에 상관없이, 나중을 생각하면 처음부터 구조를 잡는 게 낫다. 특히 설정처럼 "여러 곳에서 참조하는" 문서는 더욱.

또 하나 배운 게, 문서화만 해선 부족하다는 것. 실제로 서버에서 동작하는지 손으로 확인하는 그 과정이 버그를 많이 잡아낸다. "작성 완료"가 아니라 "서버 검증 완료"를 마일스톤으로 삼아야 한다.

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

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

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