Claude Code를 팀에서 운용하기 위한 CLAUDE.md 설계와 커스텀 에이전트 분담

Claude Code를 다루기 시작하면서 "생각보다 똑똑하네"라고 느끼고 나면, 다음에 찾아오는 고민은 "이것을 팀에서 제대로 활용하려면 어떻게 설계해야 할까"가 아닐까요? 개인 이용이라면 머릿속의 문맥으로 보완할 수 있지만, 여러 명이 사용하는 리포지토리(Repository)에서는 규칙을 언어화하지 않으면 순식간에 "사람마다 AI의 움직임이 다르다"는 상황이 발생합니다.

본 기사에서는 입문 기사 다음의 단계로서, CLAUDE.md · 커스텀 에이전트(Custom Agent) · MCP/훅(Hook)이라는 세 가지 메커니즘을 "어떻게 역할 분담을 시킬 것인가"라는 관점에서 정리합니다.

• CLAUDE.md를 "개인 메모"에서 "팀의 암묵지"로 키우기 위한 계층 설계의 사고방식
• 커스텀 에이전트 · 서브 에이전트 · 슬래시 커맨드(Slash Command)의 책임 분담을 어떻게 나눌 것인가
• MCP 서버와 훅 중 어느 쪽으로 자동화해야 하는지를 판단하는 구체적인 기준
• 운용해 보면 알 수 있는 흔히 발생하는 함정과 회피책

Claude Code 도입 직후에 자주 발생하는 실패는 "편리한 기능을 전부 때려 넣으려다가 결국 규칙이 지켜지지 않게 되는" 패턴입니다. CLAUDE.md에 세세한 코딩 규약을 적고, 커스텀 에이전트를 5~6개나 만들고, 훅으로 lint까지 실행하게 합니다. 돌아가는 동안에는 기분이 좋지만, PR(Pull Request)의 지적 사항이 늘어날 때마다 CLAUDE.md는 비대해지고 아무도 읽지 않게 됩니다.

여기서 의식해야 할 점은, Claude Code는 어디까지나 "문맥에 따라 움직이는 실행자"이며, 규칙 설계의 책임은 팀에 있다는 것입니다. 즉, "무엇을 기억시킬까"보다 "무엇을 기억시키지 않을까"를 결정하는 것이 더 오래 지속 가능한 운용이 됩니다.

CLAUDE.md는 "리포지토리 직하단", "서브 디렉토리", "사용자 글로벌(~/.claude/CLAUDE.md)"의 3개 계층으로 읽힙니다. 많은 현장에서는 리포지토리 직하단에 전부 적는 경향이 있지만, 책임을 나누어 배치하면 변경이 쉬워집니다.

계층	작성 내용	예시
사용자 글로벌	개인의 취향, 도구 선택	"일본어로 응답", "git push 전에 확인"
...	frontend/의 상태 관리 규약

포인트는, 리포지토리 직하단의 CLAUDE.md에는 "코드를 읽으면 알 수 있는 것"을 적지 않는 것입니다. 아키텍처의 대원칙이나 리포지토리 전체에 적용되는 비자명한 제약에만 집중하고, 리뷰에서 논쟁이 생길 때마다 추가해 나가는 운용 방식으로 전환하면 유지보수 부하가 크게 줄어듭니다.

예를 들어 모노레포(Monorepo)에서 packages/api/와 packages/web/을 가지고 있는 경우, 각각의 하위에 CLAUDE.md를 두는 것이 효과적입니다.

<!-- packages/api/CLAUDE.md -->
## 이 디렉토리의 제약
- DB 액세스는 반드시 `src/repository/`를 경유하며, 핸들러에서 직접 Prisma를 호출하지 않는다
...

이 기술이 있으면, Claude Code가 packages/api/ 하위를 편집할 때만 이 제약을 고려해 줍니다. 반대로 packages/web/의 프론트엔드 작업 시에는 읽히지 않으므로, 불필요한 제약으로 모델의 판단을 흐리지 않게 할 수 있다는 장점이 있습니다.

커스텀 에이전트(서브 에이전트)를 만들 때의 판단 기준은, **"메인 대화 문맥으로부터 분리하고 싶은가"**로 생각하면 이해하기 쉽습니다. 구체적으로는 다음과 같은 상황이 후보가 됩니다.

• 대량의 파일을 읽어 들이는 탐색계 태스크 (메인 문맥을 압박하고 싶지 않음)
• 독립된 역할로 움직이고 싶은 전문가 태스크 (리뷰어, 테스트 작성, SQL 튜너 등)
• 병렬로 실행하고 싶은 독립 태스크

반대로, "메인 대화에서 인간이 리뷰하며 진행하고 싶은 작업"은 서브 에이전트로 분리하지 않는 편이 결과가 더 좋습니다. 에이전트를 너무 늘리면 인간 측의 인지 부하도 높아지기 때문입니다.

슬래시 커맨드는 "같은 프롬프트를 몇 번이고 반복하는 작업"을 줄이기 위한 것이며, 독립된 에이전트와는 별개입니다. 다음과 같이 구분해서 사용하면 심플합니다.

슬래시 커맨드: 프롬프트의 템플릿화 (/review-pr, /write-tests)
서브 에이전트: 독립된 문맥 · 전문적 책임 (코드 리뷰어, 리서처)

슬래시 커맨드 안에서 서브 에이전트를 호출할 수도 있으므로, "/review-pr을 입력하면 리뷰어 에이전트가 기동하여 PR 차분을 독립된 문맥에서 리뷰한다"와 같은 조합을 깔끔하게 결정할 수 있습니다.

외부 시스템과 연동하는 자동화는 MCP 서버로 구현할지, 아니면 훅(PreToolUse / PostToolUse / Stop 등)으로 구현할지의 선택을 요구합니다. 기준은 간단합니다. **"모델에게 판단하게 하고 싶은가, 아니면 결정론적(Deterministic)으로 실행하고 싶은가"**로 나뉩니다.

메커니즘	적합한 용도	예시
MCP 서버	모델이 문맥에 따라 선택적으로 호출하기를 원하는 경우	DB 쿼리, Issue 트래커, 사내 Wiki 검색
훅 (Hook)	반드시 실행해야 하거나, 반드시 중단시켜야 하는 처리	편집 후 prettier 실행, push 전 lint 실행, 기밀 파일 보호

훅으로 "반드시 지켜야 할 규율"을 담보하고, MCP로 "지능적으로 활용하고 싶은 연동"을 제공합니다. 이러한 역할 분담을 의식하면, CLAUDE.md에 "push 하기 전에 테스트를 작성해 줘"와 같은 모호한 지시를 적지 않아도 됩니다. 반드시 지키게 만들고 싶다면, 부탁이 아니라 훅으로 만들어 버리는 것이 운영상 강력합니다.

실제로 팀에 도입한 후 자주 깨닫게 되는 몇 가지 함정을 나열해 두겠습니다.

• CLAUDE.md의 비대화: "지시를 늘리면 똑똑해질 것"이라고 착각하기 쉽지만, 모순되는 지시가 섞이면 오히려 판단력이 흐려집니다. 한 달에 한 번은 정리(Inventory)를 하세요.
• 에이전트의 과도한 분할: "테스트 작성", "구현", "리팩토링"을 별도의 에이전트로 나누면 문맥 공유(Context Sharing) 비용이 급증합니다. 처음에는 1~2개면 충분합니다.
• 훅을 통한 과도한 금지: 무엇이든 전부 차단하면 모델이 스스로 복구하지 못하고 멈춰버립니다. 훅은 "최후의 보루"로만 한정하는 것이 현실적인 해답입니다.
• 개인 설정과 팀 설정의 혼재: ~/.claude/CLAUDE.md에 작성해야 할 개인적인 선호도를 리포지토리 루트에 작성해 버리는 경우입니다. 리뷰 시 "이것은 개인 설정이 아닌가?"를 확인 포인트로 삼으면 좋습니다.

마지막으로 요점을 정리하겠습니다.

• CLAUDE.md는 세 개의 층으로 분할하며, "코드를 읽으면 알 수 있는 것"은 적지 않는 방침으로 운영한다.
• 커스텀 에이전트는 "메인 문맥에서 분리할 가치가 있는가"를 기준으로 입도(Granularity)를 결정한다.
• 슬래시 명령어는 프롬프트의 정형화, 서브 에이전트는 책임의 분리로 역할을 나눈다.
• 외부 연동은 MCP, 규율의 담보는 훅으로 구분하여 CLAUDE.md에 너무 의존하지 않는다.
• 규칙은 늘리는 것보다 버리는 것이 더 어렵다. 정기적인 정리를 운영 프로세스에 포함시킨다.

입문 기사를 한 차례 다 읽었다면, 자신의 리포지토리에 있는 CLAUDE.md를 다시 살펴보며 "지금 이 지시는 정말 필요한 것인가?"라고 한 줄씩 스스로에게 물어보세요. Claude Code를 육성하는 작업은 결국 팀의 암묵지(Tacit Knowledge)를 언어화하는 작업 그 자체라는 것을 깨닫게 될 것입니다.