봇 지침 중복 제거로 운영 복잡도 낮추기

여러 봇과 도구가 함께 작동하는 환경에서 각각의 설정 지침을 관리하는 것은 생각보다 복잡하다. 내 경우, 공용 서버에서 동작하는 여러 봇들이 각자의 CLAUDE.md 를 가지고 있었는데, 공통 정책은 항상 중복되고, 어느 것을 수정해야 하는지 불명확했다.

문제: 중복된 설정, 분산된 진실

처음에는 각 봇 디렉토리마다 CLAUDE.md 를 두었다. 공통 규칙들—예를 들어 "출력 포맷", "보안 정책", "토큰 관리" 같은 것들—이 다른 봇들과 겹쳤고, 한 곳을 수정하면 다른 곳은 빠뜨렸다. 특히 팀 규모가 커지고 정책이 자주 바뀔 때 이 문제는 심각했다.

• 중복 유지보수: 같은 규칙을 5-6개 봇에 복사하면, 1개 수정할 때 나머지 5개를 빠뜨릴 확률이 높다.
• 우선순위 불명확: "로컬 CLAUDE.md" vs "서버 글로벌 CLAUDE.md" 중 어떤 것이 먹히는가?
• 배포 불확실성: 서버에 pull 했을 때 실제로 어떤 설정이 로드되는지 보장할 수 없었다.

해결: 캐스케이드 + 단일 진실 원본

이번 커밋에서는 계층화된 지침 로드(cascade) 구조를 문서화했다:

┌─────────────────────────────────────────┐
│ 1. 글로벌 공통 지침                     │
│    (/opt/ops/docs/server-global-CLAUDE.md) │ ← 단일 진실 원본
│    (symlink: /home/hedvion/.claude/CLAUDE.md)    │
└────────────────────┬────────────────────┘
                     ↓
┌─────────────────────────────────────────┐
│ 2. 각 봇/프로젝트 특화 지침             │
│    (/opt/<repo>/CLAUDE.md)              │ ← 로컬 오버라이드
└────────────────────┬────────────────────┘
                     ↓
┌─────────────────────────────────────────┐
│ 3. 런타임 로드 (글로벌 → 로컬 우선순위) │
│    → 충돌 시 로컬이 이긴다              │
└─────────────────────────────────────────┘

핵심은 symlink다. 서버의 ~/.claude/CLAUDE.md 를 ops repo 의 server-global-CLAUDE.md 로 링크했다:

# mac 에서 ops 커밋
git commit docs/server-global-CLAUDE.md

# 서버에서 pull
cd /opt/ops && git pull
# → symlink 자동으로 최신 내용을 가리킴

이렇게 하면:
- DRY 원칙: 공통 규칙은 한 곳에만 존재
- 확정성: 서버에서 "어떤 지침이 로드되나?" 를 명확하게 추적 가능
- 배포 자동화: 각 봇이 git pull 할 때 최신 글로벌 규칙을 자동으로 받음

운영 관점: 캐스케이드의 일반론

설정 계층화는 클라우드 네이티브 환경에서 흔하다. Kubernetes 의 ConfigMap + 특화 환경 변수, Terraform 의 base + environment 모듈, Next.js 의 .env.local 같은 패턴들이 모두 이 원리다.

"서버검증"이라고 적은 이유는, 실제 서버에서 이 캐스케이드 로드 순서가 정말 작동하는지 확인했다는 뜻이다. Symlink 가 제대로 가리키는지, 각 봇이 글로벌 + 로컬을 순서대로 읽는지, 로컬이 정말 글로벌을 override 하는지.

팀 규모와 트레이드오프

이 구조는 팀이 커질수록 가치가 빛난다. 5-10명이 여러 자동화 도구를 만지작거릴 때, "이거 어디서 정해진 규칙이지?" 질문이 자주 생긴다. 캐스케이드가 명확하면:

• 온보딩이 쉬워진다 (새 팀원이 "글로벌은 ops, 로컬은 각 서비스" 를 이해하면 됨)
• 정책 변경이 빠르다 (공통 규칙 1회 커밋으로 전사 적용)
• 예외 관리가 명시적이다 (로컬 오버라이드는 의도적 결정, 코드리뷰로 추적)

다만 한 가지 주의할 점은, "로컬이 글로벌을 이긴다"는 구조를 모두가 이해해야 한다는 것. 그렇지 않으면 글로벌을 수정했는데 특정 서버에서 안 먹혀서 "왜 안 되지?" 하는 상황이 반복된다.

배운 점

이 작업은 작은 문서화 커밋처럼 보이지만, 실제로는 운영 자동화의 기초를 다지는 일이었다. 설정 관리가 명확해지면 실제 배포 오류가 줄어든다. 캐스케이드 구조를 문서화한 덕분에, 이제 다른 팀 멤버들도 "새 공통 규칙을 어디에 넣어야 하나?" 물어볼 때 답이 명확하다.

작은 팀이라도 "어디서 수정하지?" 하는 혼란이 생기면, 설정 계층화를 먼저 정리할 가치가 있다. 그래야 나중에 규모가 커질 때 문제가 커지지 않는다.

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

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

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