Claude Code의 멀티 에이전트 조직은 '만들면 썩는다' — 244개 파일 정리 후 건강 진단 전 기록

본 기사 진행 기록 (2026년 4월): Claude Code의 멀티 에이전트 조직에서 디렉터리 구조를 정리한 직후(244개 파일 이동, git commit 9121fc6)에 '덤으로' 건강 진단을 실시했다. 경로 참조, 책임, 권한 세 가지 카테고리에서 8건의 불일치를 발견했다. 더불어 CEO 에이전트가 조직 규칙을 스스로 위반한 경위, 커밋 권한 설계, 지시서 부패 문제라는 세 가지 깨달음을 정리한 기록이다.

멀티 에이전트 조직을 만들 때, 사람들은 '역할과 권한을 제대로 정의했다'는 만족감을 얻는다.

하지만, 그 후 조직은 조용히 썩기 시작한다.

에이전트를 추가할 때마다 '정의만 쓰고 워크스페이스는 나중에'가 된다. 권한은 대화 중에 하나씩 승인하므로 설계라기보다 쌓아 올리는 형태가 된다. 같은 정보를 세 곳에 쓰는 구조는, 한 곳만 업데이트하는 순간부터 괴리가 시작된다.

부패는 조용하다. 작동하는 것처럼 보이는 동안에는 아무도 알아차리지 못한다.

디렉터리 대수술: 244개 파일 이동의 Before/After

2026년 4월, Claude Code의 멀티 에이전트 조직이 성장함에 따라 프로젝트 루트가 어질러졌다.

에이전트별 폴더(CEO/, writer/, researcher/ 등), 결과물(drafts/, reports/), 지시서(agents/)가 모두 루트 직하에 나열된 상태였다. 사용자로부터 '최상위 레벨의 가시성을 개선하고 싶다'는 지시가 들어왔다.

실시한 구조 변경은 다음과 같다.

Before: After:
CEO/ workspaces/
writer/ CEO/
...

git의 차이점(diff)으로 확인하니 244 files changed (commit 9121fc6). 에이전트 정의 9개, 규칙 파일 4개, 스케줄 2개, 로그 규약 등 총 20개 이상의 경로 참조를 일괄 업데이트했다.

여기서 끝났다면 '깨끗해졌다'로 완료되었을 것이다. 하지만 이동 후에 '경로 참조가 고장 나지 않았는지 점검해 달라'는 사용자의 한마디가 예상치 못한 건강 진단으로 이어졌다.

이동 후 건강 진단: 발견된 8가지 문제

경로 참조 점검 (1건)

모든 설정 파일 및 규칙 파일 내의 경로 참조가 실제로 존재하는지 자동 점검했다.

발견된 문제는 1건. instructions/write-zenn-morning-gtd.md가 .claude/plans/quirky-baking-fox.md를 참조하고 있었다.

.claude/plans/는 Claude Code가 임시 생성하는 디렉터리로, 세션 종료 시 사라진다. git 기록에도 존재하지 않는다. 지시서의 내용은 이미 본문에 흡수되었으므로, 참조 행을 삭제하고 마무리했다.

배움: Claude Code의 임시 파일에 대한 참조를 지시서에 남기면, 다음 세션에서 고립 참조가 된다. 임시 파일을 영구 링크(permalink) 대용으로 사용하지 않는다.

책임·권한 감사 (7건)

다음으로 에이전트 정의 3곳(.claude/agents/*.md, workspaces/*/CLAUDE.md, agent-roles.md)과 권한 설정(settings.local.json)을 대조했다.

#	문제	카테고리	심각도
1	blog-dev의 workspace가 없음	누락	높음
...
높은 심각도의 4건은 본질적인 문제였다.

#1 blog-dev의 workspace가 없음: 에이전트를 추가할 때 '정의는 쓰지만 워크스페이스는 나중에' 패턴이 쌓인 결과. blog-dev는 존재하지만, 실제로 가동하려고 하면 워크스페이스가 없어 기능하지 않는다.

#2 reader의 입장이 모호함: reader는 '원고를 독자 시선으로 리뷰한다'는 중요한 역할을 하지만, 조직도(agent-roles.md)에 기재되어 있지 않았다. '서포트 에이전트'라는 구분을 만들어 명시했다.

#3 reviewer의 권한 부족: 코드 리뷰를 하는데 grep이나 파일 읽기 권한이 없는 상태였다. 코드를 읽지 않고는 코드 리뷰를 할 수 없다.

#4 researcher의 책무가 3곳에서 불일치: 정의를 3곳에 작성하는 구조의 숙명으로서, 한쪽만 업데이트하는 순간부터 괴리가 시작된다. researcher는 기능 확장 시마다 각 지점을 업데이트했으나, 업데이트 누락이 여러 곳에서 발생하고 있었다.

왜 에이전트는 자신이 정한 규칙을 어기는가——실례와 대책

8건의 문제를 발견한 후, 대책 플랜을 세웠다. 사용자가 플랜을 승인한 후, CEO 에이전트가 스스로 그 플랜의 구현을 모두 실행해 버렸다.

사용자로부터 "또 CEO를 스스로 해버렸다"라는 지적이 들어왔다.

"또"라는 단어가 중요하다. 첫 번째는 어떤 기사를 수정할 때 CEO가 직접 수행한 건. 두 번째가 이번 건. 패턴화되어 있었다.

왜 문제인가:

CEO의 책무는 "생각하기·지시하기·사용자와 대화하기"이다. settings.local.json의 관리는 devops의 명확한 책무로 정의되어 있다. 그것을 CEO가 스스로 수행하면:

• 책무 경계(Responsibility Boundary) 규칙이 형해화된다
• devops의 권한 설정이 실전에서 검증되지 않는다
• CEO의 settings.local.json에 불필요한 권한이 축적된다 (이번 문제 #6이 바로 이것)

가장 아이러니한 점: 권한 설계의 불일치를 정비한다는 작업을, "권한을 무시하고" CEO가 실행한다는 모순이었다. "내가 제일 잘 아니까"라는 생각으로 직접 움직인 결과, 자신이 관리해야 했던 설정에 불필요한 권한이 쌓여 있었다는 사실이 밝혀졌다.

대책으로서 "플랜 승인 후에는 지시서를 작성하여 devops를 기동한다"를 메모리에 저장했다. 대화적으로 기록할 뿐만 아니라, 다음 세션 기동 시 참조되는 형태로 남기지 않으면 의미가 없다.

커밋 권한 설계: 비서에게 맡긴다는 해법

8건의 수정을 마친 후, "Git의 커밋·푸시(Commit/Push)는 누가 하는가"라는 사용자의 질문이 왔다.

CEO의 첫 번째 대답은 "변경한 사람이 커밋한다"였다. 논리적으로는 옳다. 하지만 실제로는:

• CEO가 지시서를 썼을 때, 커밋하는 것은 CEO인가?
• devops가 설정을 변경했을 때, 커밋하는 것은 devops인가?
• writer가 기사를 썼을 때, 커밋하는 것은 writer인가?

모두에게 git 권한을 부여하면 책임이 모호해지고, 반대로 아무도 커밋하지 않을 리스크가 생긴다.

사용자의 제안은 "비서(secretary)에게 의뢰하면 어떠냐"였다. 이 발상은 CEO에게는 없었다.

최종적인 설계는 다음과 같았다.

상황	커밋 담당
통상적인 결과물 (기사·리포트·지시서 등)	secretary (주 담당)
...

secretary가 커밋 주 담당이 됨으로써, "결과물 최종 확인 → 커밋"이라는 자연스러운 흐름이 만들어졌다. secretary는 결과물을 받아 커밋하기 전에 내용을 파악하므로, 품질 체크의 최종 관문 역할도 수행한다.

Playbook의 유통기한 문제——Claude Code의 지시서는 방치하면 썩는다

커밋 권한 설계와 병행하여, 오래된 지시서의 전수 조사(Inventory)도 실시했다.

secretary가 조사한 결과, 미완료 상태의 지시서가 5건 있었다.

• writer 대상 기사 수정 지시 4건
• researcher 대상 데일리 리서치(Daily Research) 절차서 1건

writer 대상의 4건은 문제였다. 대상 기사를 확인하니 2개가 이미 공개된 상태였다. "수정 지시가 남아 있는데, 기사는 이미 공개되어 있다"라는 상태.

지시서가 썩는 패턴:

• 기사 수정 지시서를 낸다
• 수정이 완료되고 기사가 공개된다
• 지시서의 상태(Status)를 업데이트하는 것을 잊는다
• 다음 세션에서 "미완료된 지시서"로 참조된다

사용자의 판단에 따라 1~4건은 삭제했다. 데일리 리서치 절차서는 별도 관리로 옮겼다.

이 전수 조사를 계기로 instructions/ 디렉토리 설계를 재검토했다.

instructions/ — 일회성 지시서 (완료 후 아카이브 대상)
instructions/playbooks/ — 정례 실행 절차서 (아카이브 대상 제외)

반복해서 실행하는 절차서(데일리 리서치, 기사 공개 플로우, 크로스포스트 절차 등)를 일회성 지시서와 같은 장소에 두면, 전수 조사할 때마다 판단 비용이 발생한다. 구조적으로 분리해 두면 전수 조사 대상이 명확해진다.

나아가, reader의 페르소나(Persona) 정의도 playbooks/로 분리했다. 원래 reader.md

에 165행에 걸쳐 작성되어 있던 것을 페르소나(Persona) 정의로서 독립된 파일로 분리하여 32행으로 슬림화했다. 정의 파일이 비대해지면 에이전트(Agent) 기동 시의 컨텍스트(Context) 소비가 증가한다.

권한 설계는 책상 위에서 완성되지 않는다

마지막으로 덧붙이고 싶은 것이 있다.

8건의 권한 불일치를 정비한 직후의 실운영에서 새로운 문제가 발견되었다. secretary에게 "아이디어 노트의 재고 목록을 content/reports/research/에 저장해줘"라고 요청했으나, 쓰기가 불가능했다. secretary의 쓰기(Write) 권한이 logs/**와 .claude/schedules/**뿐이었고, content/**가 포함되어 있지 않았기 때문이다.

8건을 고친 직후에 9번째 문제가 나타났다.

이것은 실패가 아니라 권한 설계의 본질이라고 생각한다. 책상 위에서 완벽한 권한 설계를 할 수는 없다. 실운영에서 "멈춤 → 수정"을 반복해야 비로소 실태에 맞게 된다.

그보다 중요한 것은 "멈췄을 때 즉시 수정할 수 있는 메커니즘이 있는가"이다. 이번에는 devops에게 지시서를 보내 권한을 추가했고, secretary가 재시도하여 성공했다. 멈춘 시점부터 복구까지 1세션(Session) 내에 완료되었다. 이는 메커니즘이 기능했다는 증거이기도 하다.

회고: 정기 점검보다 "대수술을 하는 김에" 점검하는 것이 실효적이었다

이번 8건은 모두 "디렉토리 정리하는 김에" 발견되었다.

정기 점검 스케줄을 정해서 실행하려고 하면 "지금은 다른 작업이 우선"이 되기 쉽다. 하지만 구조 변경(디렉토리 정리, 에이전트 추가, 스크립트 이동) 시에는 이미 전체를 조망하는 컨텍스트가 갖춰져 있다. 그 흐름에서 건강 진단을 수행하는 것이 가장 자연스럽고, 실제로도 효과적이다.

이번에 확인한 문제의 분류를 정리하면 다음과 같다:

카테고리	문제 예시	근본 원인
결락 (Missing)	workspace가 없음, 조직도에 기재되지 않음	"미루기"의 누적
...

이 3가지 카테고리는 독립되어 있지 않다. 괴리가 있으면 권한 판단 기준도 흔들리고, 결락이 있으면 권한 설계의 대상조차 불명확해진다. 먼저 결락을 채우고, 그다음 괴리를 수정하며, 마지막으로 권한을 정비하는 순서가 효과적이었다.

또 다른 배움은 CEO의 책무에 관한 것이다. 조직을 설계한 사람이 가장 "직접 하고 싶은 충동"을 느낀다. 플랜을 세운 직후가 가장 위험하며, "설명하는 것보다 직접 하는 게 빠르다"는 유혹이 생긴다. 하지만 그 충동을 따르면 조직 규칙의 형해화가 시작된다. 규칙은 사용되지 않으면 존재하지 않는 것과 같다.

이러한 조직 설계의 전체상——역할 정의 방법, 권한 설계 사고방식, CEO가 "직접 하지 않기" 위한 메커니즘 구축——은 Zenn Books에 정리해 두었다.

이 기사에서 소개한 멀티 에이전트 조직의 설계 및 운용 전체상은 Zenn Books에 정리되어 있다. 서장과 제1부는 무료로 읽을 수 있다.

• 코드를 쓸 줄 모르는 내가, AI에게 "팀"을 갖게 하기까지 (¥900 / 서장·제1부 무료)

Claude Code로 멀티 에이전트 운용을 시도하고 싶은 분들을 위한 실천적인 입문서도 나와 있다. 조직 설계 전에 기초적인 사용법을 다져두면, 에이전트 간의 권한 설계나 플레이북(Playbook) 작성법을 정리하기 쉬워진다.

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

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

Discussion