[Guild Plugin] 에이전트 조직의 구조와 개발 흐름

개요

AI로 개발할 때 우리는 보통 하나의 프롬프트, 또는 하나의 에이전트에게 분석부터 구현·테스트까지 전부 맡깁니다. 작은 작업이라면 괜찮지만, 규모가 커지면 한 명이 모든 걸 하는 방식은 금세 한계에 부딪힙니다.

Guild Plugin은 다른 접근을 택했습니다. 레포마다 역할을 나눈 전용 에이전트 조직을 만들고, 그 조직이 개발 흐름을 협업으로 수행하게 하는 Claude Code 플러그인입니다. 이 글에서는 그 조직이 어떻게 구성되어 있고, 개발이 어떤 흐름으로 도는지를 살펴봅니다.

Guild Plugin의 소스 코드와 설치 방법은 dev-yakuza/deku-claude-plugins 저장소에서 확인할 수 있습니다.

이 글은 Guild Plugin 시리즈의 2부입니다.

1부. Skill이 아니라 조직을 키운다 — 왜 만들게 되었나

2부. 에이전트 조직의 구조와 개발 흐름 (이 글)

3부. 성장 엔진 ①② — 결과물과 개발자의 공진화

4부. 성장 엔진 ③ + 안전 — 감독자(사람)도 함께 자란다

왜 한 명이 아니라 조직인가

에이전트 하나에게 분석·설계·구현·테스트·리뷰를 모두 시키면 세 가지 문제가 생깁니다.

컨텍스트 과부하 — 한 대화에 모든 맥락(요구사항·설계·코드·테스트)이 뒤섞여 점점 흐릿해집니다.
자기 검토의 함정 — 자기가 짠 코드를 자기가 검토하면 확증 편향에 빠집니다. 사람도 자기 코드의 버그는 잘 못 봅니다.
전문성 희석 — 보안, 접근성, 성능처럼 서로 다른 관점을 한 페르소나가 동시에 챙기긴 어렵습니다.

사람 조직은 이 문제를 분업과 독립적인 검토로 풉니다. 만드는 사람과 검토하는 사람을 나누고, 필요할 때 전문가를 부릅니다. Guild plugin도 똑같이 합니다 — 역할을 나누고, 만든 역할과 검토하는 역할을 분리합니다.

길드의 구성원

/gld init을 실행하면 그 레포를 분석해 전용 길드(조직)가 창단됩니다. 구성원은 크게 둘로 나뉩니다.

리더 (길드 마스터)

리더는 별도의 에이전트가 아니라, 메인 세션이 그 역할을 맡습니다. 작업마다 필요한 팀을 조립하고, 각 역할에 일을 위임하고, 결과가 엇갈리면 중재하고, 완료 여부를 판정합니다. 즉 오케스트레이터입니다.

역할 로스터 (16종)

init이 레포의 스택·컨벤션·위험 지점을 분석해, 역할들을 그 레포에 맞게 특화해 만듭니다.

항상 참여하는 중추 역할 — 리더, 테크리드, 개발자, 테스터, QA
필요할 때만 소집되는 전문가 — 프로덕트 오너, 디자이너, 보안, i18n, DBA, 성능, 애널리틱스, 인프라, 테크라이터, 릴리스 매니저, 서포트 트리아지

핵심은 다 부르지 않는다는 것입니다. 작은 변경에는 최소 인원만, UI를 건드리면 디자이너를, 인증·외부 노출을 건드리면 보안을 — 리더가 변경의 표면과 위험을 보고 그때그때 소집합니다. 조직의 규모를 작업 크기에 맞추는 셈입니다.

역할들은 어떻게 협업하는가

역할들은 사람들로 구성된 팀처럼 협업 규칙(프로토콜) 아래에서 움직입니다. 그중 편향을 막기 위한 규율 몇 가지가 특히 중요합니다.

뼈대(skeleton) 우선 — 테크리드가 설계의 뼈대(모듈 경계·확장점)를 먼저 잡고, 개발자는 그 위에 구현합니다.
테스트 우선, 편향 없이 — 테스터는 개발자의 구현을 보지 않고, 수용 기준(AC)만으로 테스트 케이스를 먼저 작성합니다. 구현에 맞춘 테스트가 아니라, 요구사항을 지키는 테스트가 됩니다.
자기 검토 금지 — 어떤 역할도 자기 산출물을 자기가 통과시키지 않습니다. 다른 역할이 적합성 검사·리뷰를 맡아, 확증 편향을 구조적으로 차단합니다.
파일로 주고받기 — 역할 간 산출물은 대화가 아니라 파일로 전달합니다. 방대한 코드 변경 내역(diff)을 메인 대화에 그대로 쏟지 않아 컨텍스트를 아끼고, 세션이 끊겨도 산출물이 남습니다.

“만드는 사람 따로, 검토하는 사람 따로”라는 조직의 상식을, 에이전트들 사이의 계약으로 옮긴 것입니다.

개발 흐름

개발은 정해진 **중추(spine)**를 따라 흐릅니다. 이 순서는 바뀌지 않습니다.

분석 → 설계 → 실행 → 테스트 → QA

분석 — 무엇을, 왜 만드는지 정리하고 검증 가능한 수용 기준(AC)을 세웁니다.
설계 — 어떻게 만들지 뼈대를 잡습니다. 동시에 테스터가 (구현을 보지 않고) 테스트 케이스를 작성합니다.
실행 — 실제 구현. 작업 종류에 따라 기능 구현·버그 수정·리팩터링으로 자동 분기됩니다.
테스트 — 자동화된 정확성 검증. 통과했다고 말하려면 실제 실행 결과(원문 로그)가 있어야 합니다.
QA — 사람 관점의 품질. 자동 테스트가 못 잡는 탐색적·사용자 흐름 검증을 하고, 사람이 직접 확인해야 하는 항목은 따로 표면화합니다.

그렇다면 진행 상태는 어디에 있을까요? GitHub 이슈와 PR의 라벨에 있습니다. 어느 단계까지 왔는지가 라벨로 남기 때문에, 세션이 끊겨도 라벨만 보고 그 지점부터 이어서 재개할 수 있습니다. (이 상태 관리 방식은 SDD Plugin에서 이어받은 것입니다.)

Guild를 쓰는 명령들

실제로는 몇 개의 명령으로 이 조직을 부립니다. 대표적인 것만 추리면 이렇습니다.

/gld init — 레포를 분석해 하네스와 길드, 표준 문서를 세웁니다. (레포당 한 번)
/gld plan <문서|이슈> — 설계 문서(파일)나 큰 에픽 이슈를 개발 단위 이슈들로 분해합니다. 프로젝트 명세에서 백로그를 만드는 역할입니다.
/gld dev <이슈> — 이슈 하나를 중추 흐름 전체로 개발합니다. (가장 자주 씁니다)
/gld review <이슈|PR> — 사람과 함께 PR을 논리 단위로 하나씩 짚어 가는 가이드 리뷰입니다.
/gld audit, /gld evolve — 조직을 진단하고 성장시키는 명령입니다. 이 둘이 다음 편들의 주인공입니다.

정리하면, init으로 조직을 세우고 → plan으로 할 일을 이슈로 나누고 → dev로 개발하고 → review로 함께 확인하는 흐름입니다.

SDD Plugin과 무엇이 다른가

제가 이전에 만든 SDD Plugin은 GitHub Issue를 기반으로 분석 → 설계 → 구현 → 테스트 단계를 거치게 하는 Claude Code 플러그인입니다. 그러면 이런 의문이 들 수 있습니다. “Guild Plugin도 결국 비슷한 단계형 흐름 개발 아닌가?”

가장 큰 차이는 단계형 흐름을 누가 리드하는가입니다.

SDD Plugin — 사람이 4단계 흐름을 직접 리드합니다. 흐름은 고정되어 있고, 그 흐름을 수행하는 스킬은 사람이 관리합니다.
Guild Plugin — 흐름을 에이전트 조직이 수행합니다. 역할들이 협업하고, 리더가 팀을 조립하며, plan으로 백로그 만들기까지 조직의 일이 됩니다. 그리고 (다음 편들의 주제인) 그 조직이 스스로 성장합니다.

한 문장으로 하면, SDD Plugin이 **“프로세스”**라면 Guild Plugin은 **“그 프로세스를 수행하는, 성장하는 팀”**입니다. Guild Plugin은 SDD Plugin의 문제의식을 이어받아 한 단계 일반화한 결과입니다.

완료

정리하면, Guild Plugin은 이렇게 생겼습니다.

리더가 작업마다 팀을 조립하고,
레포에 특화된 역할 에이전트 팀에서 필요한 전문가만 소집되어,
협업 프로토콜(뼈대 우선·테스트 우선·자기 검토 금지) 아래
중추 흐름(분석 → 설계 → 실행 → 테스트 → QA)을 수행하며,
진행 상태는 GitHub에 남아 언제든 재개할 수 있습니다.

여기까지는 “개발을 어떻게 하는가”였습니다. 하지만 Guild Plugin의 진짜 핵심은 이 조직이 개발 흐름을 넘어 어떻게 스스로 성장하는가입니다. 다음 3부에서는 그 성장 엔진 — 결과물과 개발자(조직 자신)가 함께 자라는 공진화 — 를 본격적으로 다룹니다.