Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 01. 23:17

명세서에서 PR까지: Claude Code를 위한 agentflow의 동적 멀티 에이전트 워크플로우

요약

agentflow는 Claude Code를 전문화된 에이전트들의 협업 팀으로 변모시키는 동적 멀티 에이전트 워크플로우입니다. BA부터 배포까지 이어지는 고정된 파이프라인을 통해 작업을 분해하고 병렬로 실행하여 단일 에이전트의 한계를 극복합니다.

핵심 포인트

  • 단일 에이전트의 계획 부재 및 충돌 문제 해결
  • BA, 구현, 리뷰 등 역할별 에이전트 분리 및 협업
  • 명세서 승인과 푸시 승인 시점에만 인간 개입
  • 작업을 파일 단위 웨이브로 분해하여 병렬 실행

🚀 요약 (TL;DR)

agentflow는 Claude Code를 전문화된 에이전트들의 협업 팀으로 변모시킵니다. 기능 요청은 다음과 같은 고정된 파이프라인(pipeline)을 통해 흐릅니다 —
BA(비즈니스 분석) → branch(브랜치 생성) → plan(계획) → implement(구현) → review(리뷰) → verify(검증) → test(테스트) → ship(배포) —
이 과정에서 느린 멀티 에이전트(multi-agent) 중간 단계는 작업을 파일 단위로 분리된 웨이브(waves)로 분해하고 에이전트들을 병렬로 배치하는 **하나의 동적 워크플로우(dynamic workflow)**로 실행됩니다. 인간은 오직 두 지점에서만 개입합니다: 명세서(spec) 승인, 그리고 푸시(push) 승인.

📑 목차

  • "하나의 거대한 에이전트"가 가진 문제점
  • 구조(The shape of it)
  • 두 부분: 계획(planning) 및 실행(execution)
  • 워크플로우 내부: 6단계
  • 게이트(The gate)
  • 기능으로서의 규율(Discipline as a feature)
  • 기술(Skills)
  • 사용해 보기
  • 왜 이렇게 설계했는가

😵 "하나의 거대한 에이전트"가 가진 문제점

대부분의 사람들은 AI 코딩 에이전트를 동일한 방식으로 사용합니다: 채팅창을 열고, 기능을 설명한 뒤, 단일 에이전트가 코드베이스 전체를 제멋대로 돌아다니게 두는 방식입니다. 이는 연습용 작업에는 작동할지 모르지만, 실제 작업에서는 무너집니다.

아마 여러분도 다음 상황들을 모두 겪어보셨을 것입니다:

❌ 증상실제로 일어나는 일
계획 없음 (No plan)에이전트가 14개의 파일을 무작위 순서로 수정하며, 그 과정에서 두 개의 수정 사항이 서로 충돌함.
...

본능적으로 더 긴 시스템 프롬프트(system prompt)를 작성하려 할 것입니다. 하지만 계획, 코딩, 리뷰, 테스트, git 작업을 모두 수행하는 단일 컨텍스트 윈도우(context window)는 관심사 분리(separation of concerns)가 이루어지지 않은 범용 전문가일 뿐입니다. 리뷰어(reviewer)와 작성자(author)가 동일한 개체이므로, 리뷰는 형식적인 연극에 불과합니다.

💡 agentflow는 반대의 선택을 합니다: 각 관심사에 고유한 에이전트를 부여하고, 이들을 고정된 파이프라인에 연결하며, 인간은 실제로 중요한 결정 지점에만 참여하게 합니다.

🗺️ 구조 (The shape of it)

기능 요청은 다음 파이프라인을 통해 흐릅니다:

  사용자 요청 (User request)
       │
       ▼
...

사람이 어디에 위치하는지 주목하세요: 오직 양 끝에만 있습니다. 당신은 명세서(spec)를 승인하고, 푸시(push)를 승인합니다. 그 사이의 모든 과정 — 지루하고 오류가 발생하기 쉬운 부분 — 은 자율적으로 실행됩니다. (워크플로우는 질문을 하기 위해 일시 정지할 수 없으므로, 상호작용이 필요한 양 끝단은 의도적으로 워크플로우
_외부(outside)_에 존재합니다.)

당신은 단 하나의 명령으로 이 모든 것을 시작합니다:

/opsx:feature

🧩 두 개의 절반: 계획(planning) 및 실행(execution)

agentflow는 보통 "하나의 거대한 에이전트(one big agent)" 설정에서 누락되는 두 가지를 결합합니다.

1️⃣ OpenSpec — 구조화된 계획 (structured planning)

코드가 작성되기 전에, BA 에이전트(Opus에서 실행, 요구사항 수집은 레버리지가 높은 단계이기 때문)가 2~3차례의 질문을 던지고, 코드베이스를 읽고, 구조화된 산출물(artifacts)을 작성합니다:

openspec/changes/<change-id>/
├── proposal.md   # 무엇을, 왜 (what & why)
├── design.md     # 어떻게 (how)
...

이것이 바로 **계약(contract)**입니다. 하위 단계의 에이전트들은 범위를 즉흥적으로 결정할 수 없으며, 반드시 _이것_을 구현해야 합니다.

2️⃣ opsx-feature-core — 실행 워크플로우 (the execution workflow)

agentflow의 핵심은 _"명세서가 존재함"_과 "푸시 준비 완료" 사이의 모든 것을 자동화하는 단일 Claude Code 워크플로우입니다. 이는 **6단계(six phases)**로 실행됩니다 ↓

⚙️ 워크플로우 내부: 6단계

① Plan — 웨이브(waves) 단위로 분해

dev-lead 에이전트가 OpenSpec 변경 사항을 읽고 구조화된 작업 계획(structured task plan)(산문 형태가 아님)을 생성합니다. 핵심 아이디어는 **파일이 중복되지 않고(file-disjoint), 의존성 순서로 정렬된 웨이브(dependency-ordered waves)**입니다:

  • 🟢 한 웨이브 _내부(within)_의 작업들은 **서로 다른 파일(disjoint files)**을 다룹니다 → **병렬(in parallel)**로 실행해도 안전합니다.
  • 🔵 의존성이 있는 작업은 **나중 웨이브(later wave)**로 배치됩니다 → 선행 조건이 항상 먼저 완료됩니다.

계획은 기계가 소비할 수 있도록 JSON 스키마(JSON schema)로 강제됩니다:

const PLAN_SCHEMA = {
  type: 'object',
  properties: {
...

🛠️ 설계 노트 (Design note): 이전 버전은 외부 이슈 DB (Beads)를 통해 작업을 라우팅했습니다. 즉, 플래너(planner)가 작업을 가져오고(imported), DEV 에이전트들이 이를 다시 당겨오는(pulled) 방식이었습니다. 이는 느리고 임계 경로(critical path)에 대한 의존성을 발생시켰습니다. 이제 플래너는 구조화된 출력(structured output)으로 작업을 방출하며, 워크플로우는 이를 바탕으로 메모리 상에서 에이전트들을 직접적으로 확장(fans agents over it directly)합니다. 외부 DB가 빌드를 차단하는 일이 없습니다.

② Implement — 웨이브당 병렬 DEV 에이전트

각 웨이브(wave)마다 dev-be (Python/FastAPI)와 dev-fe (React/Vite)가 병렬로 작업을 수행합니다. 플래너가 서로 겹치지 않는 파일(disjoint files)을 보장하므로 이 방식은 안전합니다. 각 작업은 독립적이며, DEV 에이전트는 전체 명세서(spec)를 다시 읽지 않습니다. 에이전트들은 브랜치에 커밋(commit)만 수행하며, 절대로 푸시(push)하지 않습니다.

⏱️ 웨이브는 순차적으로 실행되지만, 하나의 웨이브 내의 작업들은 동시에 실행됩니다. 실제 소요 시간(Wall-clock cost)은 _작업의 수_가 아니라 _웨이브의 수_에 비례합니다.

③ Review — 4인의 전문가 확장

차이점(diff)이 생성되면, 네 명의 리뷰어가 각각 좁은 권한(mandate)을 가지고 동시에 실행됩니다:

👀 리뷰어 (Reviewer)탐색 대상
python-reviewerPython 정확성, 관용구(idioms), 타입 문제
...

⚠️ 리뷰어는 작성자가 아닙니다. 이러한 분리가 리뷰를 자기만족적인 행위가 아닌 실제적인 과정으로 만듭니다.

④ Verify — 적대적 투표 (Adversarial voting)

리뷰어는 오탐(false positives)을 낼 수 있습니다. 따라서 모든 CRITICAL/HIGH 발견 사항은 투표에 부쳐집니다. 세 개의 독립적인 "관점 렌즈(perspective lenses)"가 그것이 실제 문제인지 판단합니다. 발견 사항은 2/3 이상의 투표를 얻었을 때만 유지되며, 그렇지 않으면 노이즈로 간주되어 폐기됩니다. 이 과정은 (개방형 분석이 아닌 예/아니오에 집중하는) 더 저렴한 모델에서 실행됩니다.

⑤ Critic — 완전성 검사 (Completeness check)

완전성 비평가(completeness critic)는 반대의 질문을 던집니다. "리뷰어들이 놓친 것은 무엇인가?" 이 에이전트는 네 명의 전문가를 통과해 버린 HIGH/CRITICAL 이슈를 구체적으로 찾아냅니다. 이는 단일 에이전트 설정에서는 결코 수행할 수 없는, "여기에 없는 것"을 찾아내는 단계입니다.

⑥ Test — 누락된 테스트 작성 및 실행

tester 에이전트는 새로운 코드에 대해 존재해야 하는 단위 테스트(unit tests)를 작성한 다음, 전체 테스트 스위트(suite)를 실행합니다. 테스트 통과(green suite) 없이는 다음 단계로 넘어갈 수 없습니다(No gate).

🚦 게이트(The gate), 그리고 그것이 중요한 이유

워크플로우가 실행된 후에는 엄격한 게이트(gate)가 존재합니다:

  blockingFindings === 0   AND   tests pass   ⇒   ✅ ready to push

만약 조건을 충족하지 못하면, 워크플로우는 발견된 문제점(findings)을 드러내고 루프(loop)를 돕니다. 즉, 사용자에게 에스컬레이션(escalation)하기 전까지 최대 3회(3 rounds) 동안 재실행하거나 타겟팅된(targeted) 수정 사항을 적용합니다. 검토되지 않았거나 테스트되지 않은 코드가 "준비 완료(ready)" 상태에 도달하는 경로는 존재하지 않습니다.

그리고 나서 멈춥니다. agentflow는 스스로 푸시(push)하거나 PR(Pull Request)을 생성하지 않습니다. 로컬에 커밋하고 기다립니다. 오직 _사용자_가 승인한 후에만 devops 에이전트가 브랜치를 푸시하고, 각 리포지토리(repo)당 하나의 PR을 dev로 생성합니다.

🔒 작업을 로컬에만 남겨두는 것은 허용됩니다. 허가 없이 푸시하는 것은 허용되지 않습니다.

🧱 일급 기능으로서의 규율 (Discipline as a first-class feature)

제가 가장 확고한 의견을 가진 부분은 오케스트레이션(orchestration)이 아니라 바로 **제약 사항(constraints)**입니다. agentflow는 에이전트들이 흔히 저지르는 짜증 나는 행동들을 차단하는 규칙들을 내장하고 있습니다:

  • ✂️ 정밀한 변경(Surgical changes)만 수행 — 작업에 필요한 부분만 수정합니다. 인접한 코드를 "개선"하지 마세요. 모든 변경된 라인은 작업 내용과 추적 가능해야 합니다.
  • 🙋 추측하지 말고 드러내기(Surface, don't assume) — 작업에 여러 가지 해석이 가능할 경우, 조용히 하나를 선택하는 대신 그 해석들을 제시합니다.
  • 🏷️ 데드 코드(dead code)는 언급하되, 삭제하지 말 것 — 관련 없는 데드 코드는 플래그(flag)가 지정될 뿐, 제거되지 않습니다.
  • 🛑 승인 없이 절대 푸시하지 말 것 — 완전한 중단입니다.

이 규칙들은 도구에 구애받지 않는(tool-agnostic) AGENTS.md 파일에 존재하며(따라서 Cursor, Aider 또는 Codex가 동일한 규칙을 읽을 수 있습니다), Claude Code를 위해서는 **CLAUDE.md**가 이를 임포트(import)합니다.

🎛️ 기술(Skills): 에이전트가 작동하는 _방식_을 변경하기

에이전트 자체를 넘어, agentflow는 **약 48개의 행동 기술(behavioral skills)**을 제공합니다. 이는 에이전트가 무엇을 하는지가 아니라 에이전트가 어떻게 작동하는지를 바꾸는 작은 지침 모듈(instruction modules)입니다. 각 에이전트는 자신의 역할과 관련된 것만 로드합니다:

  • 🧪 공학적 규율 (Engineering discipline) — test-driven-development, systematic-debugging, verification-before-completion
  • 🐍 백엔드 (Backend) — python-patterns, fastapi-templates, postgres-patterns, api-design-principles
  • ⚛️ 프론트엔드 및 디자인 (Frontend & design) — frontend-patterns, vercel-react-best-practices, web-design-guidelines
  • 🔐 리뷰 및 보안 (Review & security) — requesting-code-review, security-review

여기에 더해, 기존의 UI나 코드를 필요에 따라 강화하기 위한 17개의 단일 목적 명령 (single-purpose commands) — /polish · /harden · /audit · /simplify · /optimize 등 — 이 포함되어 있습니다.

📦 3단계로 시작하기

agentflow는 템플릿 (template) 입니다. 특정 제품에 종속되지 않습니다. 템플릿을 복사한 후 몇 개의 플레이스홀더 (placeholders)만 교체하면 됩니다.

# 1. agentflow 클론 (Clone)
git clone https://github.com/VoVuongThanhDat/agentflow.git

...

<PROJECT_NAME> / <specs-repo> / <backend-repo> / <frontend-repo>를 교체하고, 대상 저장소 (Target Repos) 테이블(에이전트가 접근할 수 있는 저장소당 한 행씩 작성)을 채운 다음, /opsx:feature를 실행하여 원하는 내용을 설명하고, 명세 (spec)를 승인한 뒤 파이프라인 (pipeline)이 실행되도록 두세요. 게이트 (gate)가 녹색으로 변하면 푸시 (push)를 승인하면 됩니다.

🧷 단일 저장소인가요? 명세 저장소와 코드 저장소를 동일한 디렉토리로 취급하세요. 에이전트가 두 레이아웃을 모두 처리합니다.

🤔 왜 이런 방식으로 만들었는가

제가 얻은 교훈은 다음과 같습니다: 자율성 (autonomy)과 통제 (control)는 반대 개념이 아닙니다. 문제는 인간을 어디에 배치하느냐의 문제입니다.

모든 코드 수정 단계마다 인간을 배치하면 → 느린 페어 프로그래머 (pair-programmer)를 만든 셈이 됩니다.
인간을 완전히 제거하면 → 위험 요소 (liability)를 만든 셈이 됩니다.

agentflow는 인간을 정확히 두 지점 — 명세 (spec)와 푸시 (push) — 에 배치하며, 그 사이의 실제 게이트 (gate)를 통과하기 위해 기계가 스스로 가치를 증명하도록 만듭니다.

🔗 링크

직접 시도해 보신다면, 여러분의 파이프라인이 무엇을 만들어냈는지 꼭 듣고 싶습니다 — 댓글을 남겨주세요! 👇

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0