에이전트 설정의 산재를 단일 진실로 정리하다

여러 에이전트가 각자 AGENT.md를 들고 있었고, 메인 설정과 동기화가 안 되어 있던 상황을 정리했다. 이 작업 통해 "단일진실 공급원"이라는 원칙이 얼마나 중요한지 다시 한번 체감했다.

문제: 설정이 여기저기 흩어져 있다

지금껏 프로젝트가 커지면서 에이전트가 늘어났다. 백엔드 자바, DB 마리아DB, 데브옵스 깃허브, 프론트엔드 JSP. 각각 자신만의 AGENT.md를 갖고 있었고, 메인 CLAUDE.md도 있었다. 문제는 이들 사이에 정보가 중복되고, 때론 어떤 파일이 정답인지 불분명해지는 일이 빈번했다는 거다.

예를 들어 특정 에이전트의 권한 범위나 도구 설명이 메인 CLAUDE.md와 해당 AGENT.md에서 다를 수 있었다. 팀원이 새 프로젝트를 셋업할 때 어느 파일을 참고해야 하는지 헷갈렸고, 설정을 업데이트할 때도 여러 곳을 동시에 고쳐야 한다는 불편함이 있었다.

이건 조직이 작을 땐 버티지만, 인원이 늘거나 프로젝트가 복잡해질수록 정보 불일치로 인한 버그와 혼란이 기하급수적으로 증가한다. "문서를 봤는데 다르네?" 하는 상황은 신뢰도를 떨어뜨린다.

해결책: 단일진실 공급원 확립

핵심 원칙은 이렇다: CLAUDE.md가 부모, 각 AGENT.md는 자식 역할. 메인 설정에서 변경하면, 각 에이전트는 그 설정을 상속받는다. 중복 정의를 없앴다.

# 개선 전 구조
├── .claude/CLAUDE.md (에이전트 A의 도구 목록 v1)
├── .claude/agents/backend-java-agent/AGENT.md (도구 목록 v1.1)
├── .claude/agents/db-mariadb-agent/AGENT.md (도구 목록 v1.2)
└── ...여러 버전이 흩어짐

# 개선 후 구조
├── .claude/CLAUDE.md (진실의 원천 - 도구 목록 v2.0)
├── .claude/agents/backend-java-agent/AGENT.md (→ CLAUDE.md 참조)
├── .claude/agents/db-mariadb-agent/AGENT.md (→ CLAUDE.md 참조)
└── ...일관된 참조

이렇게 하면 업데이트가 필요할 때 한 곳만 손대면 된다. 새 에이전트를 추가할 때도 명확한 패턴이 있어서 온보딩이 빨라진다.

실무에서 배운 점

1. 초기 규모는 중복을 눈감아줄 수 있지만, 성장 속도가 곱해진다

5개 에이전트일 때는 수동 동기화가 가능했다. 하지만 10, 20개로 늘어나면? 한두 번 빠뜨리는 순간 설정 지옥이 된다. 이 작업을 좀 더 일찍 했으면 하는 아쉬움이 있다.

2. 문서/설정도 코드 같은 원칙이 필요하다

프로그래밍에서 DRY(Don't Repeat Yourself)는 기본이다. 설정과 문서도 마찬가지다. 산재된 설정은 버그와 다름없다. 처음부터 "이건 어디가 진실일까?" 고민하면서 설계하는 게 좋다.

3. 변경 영향도를 명확히 하면 리뷰가 쉬워진다

이번 작업에서 "CLAUDE.md가 진실이고, AGENT.md는 참조만 한다"는 원칙을 명시했다. 다음 누군가가 이 파일들을 수정할 때 "어느 파일을 먼저 수정하지?" 하는 고민이 줄어든다. 특히 팀이 커질수록, 이런 명확한 거버넌스가 시간을 아껴준다.

4. 한 번에 정리하는 게 여러 번 정리하는 것보다 낫다

부분 정리는 혼란만 가중시킨다. "이 파일은 갱신했는데 저 파일은?" 이런 의문을 남기지 않으려면, 한 번에 모든 참조 지점을 찾아 정렬해야 한다. 이 과정에서 PRODUCT_SUPPLY_DESIGN.md 같은 다른 문서까지 발견해서 함께 갱신할 수 있었다.

결국 이런 "문서 정리" 작업이 지루해 보일 수 있지만, 팀의 인지 부하를 줄이고 실수를 방지하는 든든한 기초 공사다. 특히 멘토링 관점에서, 새 팀원이 온 뒤 "설정을 어디서 봐야 하나요?"라는 질문이 줄어들면 그것만으로도 충분한 가치가 있다.

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

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

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