Claude Code의 멀티 에이전트 조직은 큰 변경을 하지 않아도 조용히 부패가 진행된다. 본 기사에서는 잘못된 디렉토리에서 실행함으로써 CLAUDE.md가 의도치 않게 증식한 케이스와, 참조원이 끊긴 채 아무에게도 호출되지 않게 된 Playbook이라는 케이스를 실례로 기록한다. 둘 다 "문제를 일으키려고 의도한 조작"이 아니다. 일상적인 조작 실수 하나, 업데이트 누락 하나 — 그것만으로 부패는 쌓여간다. 발견의 동기가 외부에서 오지 않는 종류의 부패를 어떻게 검출할 것인가가 이 기사의 테마다.

이 기사는 멀티 에이전트 조직 시리즈의 후편이다. 전편에서는 "244개 파일 이동이라는 대수술 후에 부패가 발견되었다"라는 이야기를 썼다.

전편의 부패는 "대수술이 트리거"였다. 이번에는 다르다. 무언가 큰 일을 한 것도 아닌데, 부패는 조용히 시작되고 있었다.

부패 패턴 1: 이상한 디렉토리에서 실행했더니, CLAUDE.md가 생겨났다

2026년 4월 13일, devops/CEO 에이전트가 조직 건전성 점검 리포트를 제출해 왔다. 리포트의 결론은 "전체적으로 건전"이었다 (content/reports/research/2026-04-13_org-health-check.md).

다만, 그 리포트의 계기가 된 것은 별개의 문제였다.

CLAUDE.md가 3개, 의도치 않게 증식해 있었다.

workspaces/writer/CLAUDE.md
workspaces/secretary/CLAUDE.md
workspaces/resarcher/CLAUDE.md

이것들은 내가 의도해서 만든 파일이 아니다. 작업 중에 잘못된 디렉토리에서 Claude Code를 실행했을 때, Claude Code가 자동 생성하여 남긴 파일이다. git log로 추적하면, 루트의 CLAUDE.md가 먼저 존재하며, 이 워크스페이스 하위의 파일들은 커밋 6f3057fe (2026-04-07)에서 리포지토리에 포함되었다. 그리고 중복 규칙을 정리하는 커밋 171f2d4 (2026-04-12)로 대응하기 전까지, 오래된 규칙을 품은 채 계속 존재했다.

문제는 이 파일이 "오래된 규칙을 가진 채 살아남아 있었다"는 점이다.

구체적으로는 다음 3가지 규칙이 4곳(루트 CLAUDE.md + 워크스페이스 3개)에 중복되어 있었다.

• 일본어로 응답할 것
• 경로는 상대 경로로 기술할 것
• 결과물에 인계 헤더를 붙일 것

이것들은 나중에 global-rules.md로 집약된 규칙들이다. 집약 후에도 워크스페이스의 파일에는 오래된 기술이 그대로 남아 있었다.

나는 이 상태를 알지 못했다.

devops/CEO 에이전트가 스캔하여 처음으로 검출했다. 건전성 점검 리포트에 기재된 것은 "규칙 파일 간의 모순: ◯ (모순 없음)"이었지만, 중복 정리는 별도의 커밋으로 대응했다. 커밋 171f2d4의 변경 내용을 확인하면, 5개 파일의 변경으로 7행 추가 · 23행 삭제. 그 커밋 메시지는 다음과 같이 적혀 있다.

refactor: 일본어 응답 · 경로 기술 · 인계 헤더의 중복을 global-rules로 일원화
CLAUDE.md · 워크스페이스 3개 · agents/writer.md로부터
global-rules.md와 중복되는 규칙 기술을 삭제.
...

함께 a567fa1 커밋에서는 에이전트 이름의 철자 오류인 resarcher를 researcher로 수정하고 있다. 디렉토리 이름 · 에이전트 정의 · 각종 참조 파일 합계 15개 파일에 걸친 수정이다. 이 철자 오류가 언제부터 존재했는지, 나는 파악하지 못하고 있었다.

부패에 사건은 필요 없다. 이상한 디렉토리에서 무심코 실행했을 뿐인데, 의도하지 않은 파일이 생겨나고, 오래된 규칙이 증식한다.

부패 패턴 2: 작성한 Playbook이, 아무에게도 호출되지 않고 있었다

또 다른 패턴은 더욱 조용하다.

어느 때, cowork-mining-rules.md라는 Playbook을 다시 쓰려고 했다. 그 순간, 사용자로부터 질문이 왔다.

"이 규칙, 언제 트리거되나요?"

조사해 보니, global-rules.md로부터의 참조가 이미 삭제되어 있었다. session-idea-mining.md에 참조가 남아 있었지만, 그 섹션 자체가 기능하지 않는 상태였다. 즉 cowork-mining-rules.md

는 어디에서도 호출되지 않는 고립된 Playbook이 되어 있었다.

나는 "삭제할까요?"라고 제안했다.

사용자의 답변은 다음과 같았다. "제대로 호출되도록 만들고 싶다."

이 차이는 매우 크다. 삭제는 현 상태에 대한 부정(denial)이지만, 재연결은 기능의 회복이다. 삭제해 버리면 CoWork이 다시 활용될 때 처음부터 다시 작성해야 한다. 사용자의 의도는 "안 쓰니까 지운다"가 아니라 "제대로 작동하게 만든다"였다.

대응책으로 session-idea-mining.md의 CoWork 섹션을 Claude Code/Chat용으로 다시 작성하고, global-rules.md에 참조를 복구시켰다.

왜 Playbook은 고립되는가

Playbook을 작성할 때, 사람은 "무엇을 할지"를 쓴다. 거기서 멈춘다. "언제·누구로부터·어떤 규칙을 경유하여 호출되는지"를 쓰지 않는다.

참조원이 없는 Playbook은 기술적으로는 존재하지만, 기능적으로는 존재하지 않는다. 선반에 넣어둔 매뉴얼과 같다. 정성스럽게 작성되어 있을수록 "참조되고 있을 것"이라는 선입견이 강해져, 고립을 알아차리기 어렵다.

커밋 b2266cb (타임존 설명이 담긴 global-rules.md로의 단일화)도 같은 구조다. 2개의 파일로 중복되어 있던 규칙을 한 곳으로 집약할 때, 참조원이 제대로 업데이트되지 않으면 집약된 이후의 규칙에 도달할 수 없게 된다.

두 가지 패턴에 공통되는 구조

전편의 부패는 "대수술을 트리거로 발견했다". 이번의 2가지 패턴은 모두 "일상적인 조작"이 트리거가 되어 부패가 시작되었다.

전편의 8건은 "대수술 이후"라는 맥락이 있었기에 점검하려는 동기가 생겨났다. 이번의 2가지 패턴은 그 동기조차 생기지 않는 곳에서 부패했다.

**"아무것도 하지 않았는데"**라는 말은 정확히 말하면 옳지 않다. 무언가를 하고 있다—다만, 부패를 의도하지 않았을 뿐이다. 잘못된 디렉토리에서 실행하는 것도, Playbook의 참조원을 업데이트하는 것을 잊어버리는 것도, 둘 다 "문제를 일으키려고 의도한 조작"은 아니다. 부패는 의도하지 않은 조작의 부산물로서 쌓여간다.

탐지 메커니즘이 없다면, 부패는 보이지 않는다

전편의 8건은 "디렉토리 정리하는 김에"라는 우연한 맥락에서 발견했다. CLAUDE.md의 증식은 devops/CEO의 정기 스캔을 통해 발견했다. Playbook의 고립은 사용자의 "언제 트리거되는 거야?"라는 질문을 통해 발견했다.

3가지 패턴의 발견 모두 "의도적으로 탐지하려고 했던" 것은 아니었다.

이것이 문제의 본질이다. 부패는 조용히 진행된다. 움직이고 있는 것처럼 보이는 동안에는 아무도 눈치채지 못한다. 발견은 우연에 의존하고 있다.

대책으로 생각하고 있는 것은 두 가지다.

1. 구조 변경(디렉토리 추가·Playbook 신규 생성)을 수행할 때, 참조원을 세트로 확인한다

새로운 Playbook을 만들 때, "무엇을 할지"뿐만 아니라 "어떤 규칙 파일에서 참조될지"를 동시에 결정한다. 참조원이 없다면 완성되는 순간 고립된다.

기존 Playbook이 고립되어 있지 않은지 확인하려면, 각 Playbook 파일의 파일 경로를 Playbook 그룹 외부에서 grep으로 검색하여 참조가 0인 파일을 찾아내는 절차가 유효하다. "참조되고 있을 것"이라는 선입견을 외부에서 깨뜨리는 것이 목적이며, 결과에 놀라게 될 것이다.

CLAUDE.md의 의도치 않은 증식을 확인하려면, 리포지토리 내에 존재하는 모든 CLAUDE.md를 나열하고, 루트 이외의 경로에서 예상치 못한 장소에 파일이 있는지 확인한다. 나의 경우, 그때까지 존재를 인식하지 못했던 워크스페이스 하위의 3개 파일이 이 방법을 통해 가시화되었다.

2. 건전성 점검을 "대수술을 하는 김에" 하도록 설계한다

전편에서 배운 교훈을 재확인하는 것이기도 하다. 정기 점검 스케줄을 정해두면 "지금은 다른 작업이 우선"이 되기 쉽다. 하지만 구조 변경·에이전트 추가·스크립트 이동은 이미 전체를 조망하는 컨텍스트(Context)가 갖춰져 있는 상태다. 그 흐름에서 건강검진을 수행하는 것이 가장 자연스럽게 기능한다.

부패에 사건은 필요 없다

전편과 후편을 나란히 놓고 보면, 부패에는 두 가지 기점이 있다는 것을 알 수 있다.

• 대수술을 하는 김에 발견하는 부패 (전편): 사건이 있기 때문에 알아차릴 기회가 생긴다.
• 일상 운용이 쌓아 올리는 부패 (후편): 사건이 없기 때문에 알아차릴 기회가 생기지 않는다.

후자가 더 심각하다. 발견의 동기가 외부에서 오지 않기 때문이다.

Claude Code의 멀티 에이전트 조직을 운영하다 보면 Playbook은 계속 늘어난다. CLAUDE.md에 대한 기술(description)은 쌓여간다. 에이전트도 추가된다. 그때마다 참조 관계가 업데이트되지 않을 가능성이 생기며, 의도하지 않은 파일이 생성될 가능성이 생긴다.

부패에는 사건이 필요 없다. 조직이 존재하는 것만으로도 일상적으로 부패는 시작된다. 그러므로 발견 메커니즘을 의도적으로 설계할 필요가 있다.

첫걸음을 뗀다면, 자신의 리포지토리(repository)에 있는 모든 CLAUDE.md의 위치를 확인하는 것이다. 의도하지 않은 경로에 파일이 있다면, 그것이 현재 부패의 기점이 되고 있을 가능성이 높다. 그다음, 최근에 작성한 Playbook을 하나 골라 "이 파일명이 다른 규칙 파일로부터 참조되고 있는가"를 확인해 본다. 참조하는 곳이 없다면 고립되어 있는 것이다. 이 두 가지 확인은 대대적인 점검을 하기 전의 준비 운동으로서 지금 바로 실행할 수 있다.

이 글에서 다룬 멀티 에이전트 조직의 설계·운용 전체상——역할 정의 방법, 권한 설계 방식, Playbook 관리 방법——은 Zenn Books에 정리해 두었다. 모두 서장은 무료로 읽을 수 있다.

• 코드를 쓸 줄 모르는 내가 Claude Code로 "AI 팀"을 만들기까지 (¥900 / 서장·제1부 무료)
• 코드를 쓸 줄 모르는 내가 Claude Code로 "AI 팀"을 운영하기까지 (¥900 / 서장 무료)

Claude Code로 멀티 에이전트 운용을 시도해 보고 싶은 분들을 위한 실전 입문서도 나와 있다. 조직 설계 전에 기초적인 사용법을 다져두면, 에이전트 간의 권한 설계나 Playbook 작성법을 정리하기가 훨씬 수월해진다.

• Claude Code를 통한 AI 주도 개발 입문 (히라카와 토모히데 저)
• 실전 Claude Code 입문 (니시미 키미히로·요시다 신고·오시마 유키 저)

이 글은 はてなブログ(Hatena Blog)로부터의 크로스 포스트입니다.

Discussion