From 7fde1d2b8aaeebc7f6e0530cf7d6755e4e853411 Mon Sep 17 00:00:00 2001 From: Godopu Date: Thu, 16 Jul 2026 13:26:17 +0900 Subject: [PATCH] docs(loop): merge multi_agent_workflow.md into SKILL.md, drop duplicate --- .agents/multi_agent_workflow.md | 121 ------------------- .agents/skills/lib.sh | 3 + .agents/skills/multi-agent-mux-loop/SKILL.md | 100 +++++++++++++-- AGENTS.md | 2 +- 4 files changed, 97 insertions(+), 129 deletions(-) delete mode 100644 .agents/multi_agent_workflow.md diff --git a/.agents/multi_agent_workflow.md b/.agents/multi_agent_workflow.md deleted file mode 100644 index e6266f2..0000000 --- a/.agents/multi_agent_workflow.md +++ /dev/null @@ -1,121 +0,0 @@ -# Multi-Agent Collaboration Workflow Reference Guide - -본 문서는 대규모 프로젝트나 정밀한 설계·구현 요구사항을 처리하기 위해 **Planner, Developer, Reviewer** 에이전트 간의 역할 분담 및 피드백 루프를 운영하는 **다중 에이전트 협업 워크플로우(Multi-Agent Collaboration Workflow)**를 정의합니다. 다수의 에이전트 간 협업을 위해서는 앞으로 수동 프롬프트 환류가 아닌, 자동화된 [multi-agent-mux-loop](skills/multi-agent-mux-loop/SKILL.md) 스킬만을 단독으로 사용하여 자율 루프를 기동합니다. - ---- - -## 1. 역할 정의 및 분담 (Roles & Responsibilities) - -협업 시스템은 각 에이전트의 책임 영역을 명확히 격리하여 상호 교차 검증을 강제합니다. - -``` - ┌──────────────────────┐ - │ User Prompt │ - └──────────┬───────────┘ - ▼ - ┌──────────────────────┐ - │ 1. Planner Agent │ ◄──────────────────┐ - │ - Plan & Checklist │ │ - └──────────┬───────────┘ │ - ▼ │ - ┌──────────────────────┐ │ - │ 2. Developer Agent │ │ - │ - Code & DoD Verify │ │ - └──────────┬───────────┘ │ - ▼ │ (NOT PASS Feedback) - ┌──────────────────────┐ │ - │ 3. Reviewer Agents │ │ - │ - Dual Peer Review │ ───────────────────┘ - └──────────┬───────────┘ - ▼ (PASS) - ┌──────────────────────┐ - │ 4. Done & Commit │ - └──────────────────────┘ -``` - -### 1.1. Planner Agent (설계 및 통제) -- **목적**: 요구사항을 명세화하고, 구현 단계의 설계 결함이나 모순(Contradiction)을 사전에 차단합니다. -- **역할**: - - 사용자 요구사항에 따른 구현 목표 및 범위 수립. - - `implementation_plan.md` 및 `task.md` (체크리스트) 작성 및 버전 관리(Rev.1, Rev.2, ...). - - 리뷰어 피드백 발생 시 설계 변경의 파급 범위를 계산하여 계획 갱신. -- **핵심 원칙**: 직접 코드를 수정하지 않고 오직 설계와 체크리스트 자산만 관리합니다. - -### 1.2. Developer Agent (구현 및 자가 검증) -- **목적**: Planner가 제공한 체크리스트를 기반으로 실제 리포지토리 코드를 물리적으로 수정 및 구현합니다. -- **역할**: - - `task.md`를 순차적으로 완료 상태(`[x]`)로 업데이트하며 구현 수행. - - 커밋 전 **Definition of Done (DoD)** 체크리스트를 자체 실행하여 금지된 코드 패턴, 메모리/구조적 사이드 이펙트 유무 자가 검토. - - 수정 사항을 단일 원자적(Atomic) 커밋으로 마감하고 리뷰어에게 전달. - -### 1.3. Reviewer Agents (교차 피드백 및 검증) -- **목적**: 구현된 결과물이 최초 설계서 및 학술적 제약 요건에 일치하는지 제3자의 관점에서 엄격하게 검토합니다. -- **역할**: - - **Reviewer A (Claude)**: 학술 서사와 코드 설계 간의 상위 논리적 정합성 및 결함(예: HOLB 해소 주장과 단일 커넥션 다이얼러의 모순 등) 검증. - - **Reviewer B (Cline)**: 전이 조건, 예외 처리, 타입 시그니처, 텔레메트리 매핑 등 하위 레벨 구현의 세부 사항 기계적 검증. -- **판정 규칙**: 두 리뷰어 모두 **PASS** 판정을 내릴 때까지 개발자는 마감할 수 없으며, 반려 시 **1단계(Planner)**로 피드백이 환류됩니다. - ---- - -## 2. 세부 운영 단계 (Step-by-Step Workflow) - -### 1단계: 설계 수립 (Planning Phase) -1. 사용자가 요구사항을 제시하면, **Planner 에이전트**가 프로젝트의 전반적인 구조를 파악합니다. -2. `implementation_plan.md` 및 `task.md`를 작성하여 개발을 위한 로드맵을 제공합니다. -3. 사용자가 해당 구현 계획을 승인하면 다음 단계로 이행합니다. - -### 2단계: 코드 구현 및 자가 검증 (Development Phase) -1. **Developer 에이전트**가 배정된 태스크의 코드를 수정합니다. -2. 작업 진행 중 예상치 못한 설계 변경 필요성이 감지되면 작업을 멈추고 **Planner 에이전트**에게 계획 수정을 먼저 위임합니다. -3. 구현 완료 후 아래의 **DoD 검증**을 수행합니다: - - 핵심 기능의 타입 매핑 확인. - - 공유 자원(`tls.Config` 등) 변경 시 사이드 이펙트 방지(복제 후 변이 적용 등). - - 문서-코드 간 주장의 정합성 체크. -4. 검증 완료 후 단일 커밋을 작성합니다. - -### 3단계: 피드백 루프 및 통과 (Review Phase) -1. Developer 에이전트가 리뷰어 세션에 작업 완료 사실과 변경 범위를 전달합니다. -2. 리뷰어들은 `git diff`를 바탕으로 개별 검증을 수행하고 보고서 형태의 리뷰 피드백을 출력합니다. - - **반려 (`[VERDICT: NOT PASS]`, 리포트 마지막에 단독 행으로)** -> 피드백 요약본을 Planner 에이전트에게 전송하여 상위 레벨 계획(Rev.n) 개시. - - **통과 (`[VERDICT: PASS]`, 리포트 마지막에 단독 행으로)** -> 모든 검토 사항이 해결되었음을 명시. -3. 모든 리뷰어가 PASS를 발행하면 작업을 완결하고, 다른 에이전트 세션들은 종료하지 않고 다음 태스크 지시가 있을 때까지 프롬프트 대기 상태(Standby)로 유지합니다. - ---- - -## 3. Best Practices & 자동화 지침 - -수동 템플릿 작성 및 전달은 폐지되었습니다. 모든 에이전트 간 피드백 루프는 [multi-agent-mux-loop](skills/multi-agent-mux-loop/SKILL.md)를 활용해 자동으로 오케스트레이션합니다. - -### 3.1. 개념-옵션 매핑 규격 - -워크플로우 단계별로 활용할 수 있는 `run_loop.sh` 옵션 규격은 다음과 같습니다: - -| 워크플로우 단계 | 해당 CLI 옵션 | 설명 | -| :--- | :--- | :--- | -| **Phase 1: Planning** | `--plan` | Planner 에이전트를 기동하여 최초 계획 작성을 강제합니다. | -| **Phase 1: Debate** | `--plan-talk N` | Planner와 Creator가 상호 대화식 챌린지 루프를 `N`회 돌며 계획을 교차 정제합니다. | -| **Phase 2: Execution** | (기본값) | `--target-agent`로 명시한 주 작업 세션에 코딩 태스크를 주입합니다. | -| **Phase 3: Review** | `--reviewer "A,B"` | 지정된 리뷰어 세션 리스트(`A`, `B` 등)에 교차 Peer Review를 위임합니다. | -| **Phase 3: Consensus** | `--all-reviewer` | 모든 리뷰어가 PASS를 냈을 때만 최종 통과를 허용합니다. (미지정 시 1명만 PASS여도 통과) | -| **Iterative Loop** | `--max-loop M` | NOT PASS 또는 린트 실패 시 최대 `M`회까지 Planner와 Creator 간 피드백 루프를 반복합니다. | - -### 3.2. 실전 자율 루프 기동 예시 - -```bash -bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ - --plan \ - --plan-talk 1 \ - --reviewer "canary-projects-multi-agent-mux-reviewer-cline,canary-projects-multi-agent-mux-reviewer-agy" \ - --all-reviewer \ - --max-loop 3 \ - --target-agent "canary-projects-multi-agent-mux-creator-agy" \ - --task "작업할 상세 요구사항을 여기에 입력..." -``` - -### 3.3. 동작성 제약 및 Pitfalls - -1. **세션 가동 전제**: `run_loop.sh` 기동 전에 타겟 세션(Planner, Target Agent, Reviewer)들이 모두 tmux 세션으로 기동되어 (`status.sh` 기준 `alive` 및 `running`) 있어야 합니다. -2. **동시 루프 기동 금지**: 동일한 작업 트리 내에서 다수의 `run_loop.sh` 제어기를 동시에 기동하면 SQLite DB 갱신 경합 및 YAML 데이터 오염이 발생하므로 절대로 병렬 기동하지 마십시오. -3. **정형 토큰 단독 행 작성 필수**: 앵커링 파서 하드닝에 의해, 리뷰 리포트 파일 내에서 `[VERDICT: PASS]` 또는 `[VERDICT: NOT PASS]` 토큰은 반드시 리포트의 **마지막에 단독 행으로** 기재되어야 합니다. 코드 인용이나 변경 diff 내의 토큰은 매칭 대상에서 완전 배제됩니다. -4. **결함 시 fail-closed**: 최종 Verdict 토큰이 누락되거나 리포트 픽업 실패 시, 파서는 안전을 위해 `NOT PASS`로 오픽업(Fail-closed) 판정하여 교정 사이클을 수행하므로 반드시 리포트 끝에 단독 행으로 토큰을 찍도록 지시해야 합니다. -5. **원자적 아카이빙 (Promotion)**: 루프 성공 종료 시 최종 계획서와 검증 리포트들은 `.agents/reports//` 디렉토리로 원자적으로 덮어쓰기(`mv -f`)되어 보존되므로, 해당 경로의 리포트들로 VCS 추적성을 확보해야 합니다. diff --git a/.agents/skills/lib.sh b/.agents/skills/lib.sh index eb75658..75322f6 100644 --- a/.agents/skills/lib.sh +++ b/.agents/skills/lib.sh @@ -1189,6 +1189,9 @@ send_keys_safe() { local cur_content cur_content=$(_pane_capture "$sess") # Hardened Submission Checks + if printf '%s\n' "$cur_content" | grep -Eq "● |Twisting|Thinking"; then + return 0 + fi if [ "$was_popup" = "0" ] && ! _pane_tail "$sess" 3 | grep -Fq "$marker" && [ "$cur_content" != "$pre_submit" ]; then return 0 elif [ "$was_popup" = "1" ] && \ diff --git a/.agents/skills/multi-agent-mux-loop/SKILL.md b/.agents/skills/multi-agent-mux-loop/SKILL.md index 86692c8..59eec7b 100644 --- a/.agents/skills/multi-agent-mux-loop/SKILL.md +++ b/.agents/skills/multi-agent-mux-loop/SKILL.md @@ -4,6 +4,8 @@ > **Safety Guard**: `--max-loop` and `--plan-talk` restrict API cost runaways. > **Single source of truth**: `./.mam/agent-sessions.yaml`. +수동 템플릿 작성 및 수동 프롬프트 환류는 폐지되었습니다. Planner, Creator, Reviewer 간의 모든 협업 피드백 루프는 본 스킬(`run_loop.sh`)만을 단독으로 사용하여 자동으로 오케스트레이션합니다. + ## What this skill does Run an autonomous planning-execution-review loop using multiple agents (Planner, Creator, Reviewers) in the workspace. It supports: @@ -16,6 +18,59 @@ Run an autonomous planning-execution-review loop using multiple agents (Planner, --- +## Roles & Responsibilities + +협업 시스템은 각 에이전트의 책임 영역을 명확히 격리하여 상호 교차 검증을 강제합니다. + +``` + ┌──────────────────────┐ + │ User Prompt │ + └──────────┬───────────┘ + ▼ + ┌──────────────────────┐ + │ 1. Planner Agent │ ◄──────────────────┐ + │ - Plan & Checklist │ │ + └──────────┬───────────┘ │ + ▼ │ + ┌──────────────────────┐ │ + │ 2. Creator Agent │ │ + │ - Code & DoD Verify │ │ + └──────────┬───────────┘ │ + ▼ │ (NOT PASS Feedback) + ┌──────────────────────┐ │ + │ 3. Reviewer Agents │ │ + │ - Dual Peer Review │ ───────────────────┘ + └──────────┬───────────┘ + ▼ (PASS) + ┌──────────────────────┐ + │ 4. Done & Standby │ + └──────────────────────┘ +``` + +### Planner (설계 및 통제) +- **목적**: 요구사항을 명세화하고, 구현 단계의 설계 결함이나 모순(Contradiction)을 사전에 차단합니다. +- **역할**: + - 사용자 요구사항에 따른 구현 목표 및 범위 수립. + - `implementation_plan.md` 및 `task.md` (체크리스트) 작성 및 버전 관리(Rev.1, Rev.2, ...). + - 리뷰어 피드백 발생 시 설계 변경의 파급 범위를 계산하여 계획 갱신. +- **핵심 원칙**: 직접 코드를 수정하지 않고 오직 설계와 체크리스트 자산만 관리합니다. + +### Creator (구현 및 자가 검증) +- **목적**: Planner가 제공한 체크리스트를 기반으로 실제 리포지토리 코드를 물리적으로 수정 및 구현합니다. +- **역할**: + - `task.md`를 순차적으로 완료 상태(`[x]`)로 업데이트하며 구현 수행. + - 커밋 전 **Definition of Done (DoD)** 체크리스트를 자체 실행하여 금지된 코드 패턴, 메모리/구조적 사이드 이펙트 유무 자가 검토. + - 수정 사항을 단일 원자적(Atomic) 커밋으로 마감하고 리뷰어에게 전달. + +### Reviewer Agents (교차 피드백 및 검증) +- **목적**: 구현된 결과물이 최초 설계서 및 제약 요건에 일치하는지 제3자의 관점에서 엄격하게 검토합니다. +- **역할**: + - 상위 논리적 정합성(설계 주장과 구현 간 모순 여부) 검증. + - 전이 조건, 예외 처리, 타입 시그니처 등 하위 레벨 구현의 세부 사항 기계적 검증. +- **판정 규칙**: 지정 또는 자동으로 수집된 모든 리뷰어 세션이 만장일치로 **PASS** 판정을 내릴 때까지 Creator는 마감할 수 없으며, 반려 시 **Planner**에게 피드백이 환류됩니다. + +--- + ## Specification & Flow ```mermaid @@ -27,7 +82,7 @@ sequenceDiagram participant Rev as Reviewer Agents Loop->>Loop: Parse args & validate session states - + alt --plan enabled Loop->>Plan: delegate plan design Plan-->>Loop: plan report generated @@ -39,10 +94,10 @@ sequenceDiagram else Self-Planning Loop->>Dev: notify direct task execution (Self-planned) end - + Loop->>Dev: delegate code implementation Dev-->>Loop: code modification complete - + loop up to --max-loop times (default 3) alt Reviewers specified (--reviewer / --all-reviewer) Loop->>Rev: delegate code validation @@ -57,7 +112,7 @@ sequenceDiagram Dev-->>Loop: verification complete fi end - + alt --cleanup enabled Loop->>Loop: purge temporary job folders end @@ -65,6 +120,33 @@ sequenceDiagram --- +## Feedback Loop Cadence + +1. **Planning Phase**: 사용자가 요구사항을 제시하면 Planner가 프로젝트 구조를 파악하고 `implementation_plan.md`/`task.md`로 로드맵을 제공합니다. 사용자가 승인하면 다음 단계로 이행합니다. +2. **Execution Phase**: Creator가 배정된 태스크의 코드를 수정합니다. 진행 중 예상치 못한 설계 변경 필요성이 감지되면 작업을 멈추고 Planner에게 계획 수정을 먼저 위임합니다. 구현 완료 후 DoD(타입 매핑, 공유 자원 사이드 이펙트 방지, 문서-코드 정합성)를 자체 검증한 뒤 단일 커밋을 작성합니다. +3. **Review Phase**: Creator가 리뷰어 세션에 작업 완료 사실과 변경 범위(`git diff`)를 전달합니다. 리뷰어는 검증 후 리포트 **마지막에 단독 행**으로 판정을 남깁니다: + - **반려 (`[VERDICT: NOT PASS]`)** → 피드백 요약을 Planner에게 전송하여 상위 레벨 계획(Rev.n)을 개시합니다. + - **통과 (`[VERDICT: PASS]`)** → 모든 검토 사항이 해결되었음을 명시합니다. +4. 지정되거나 자동 수집된 리뷰어 전원이 PASS를 발행해야 완결되며, `--max-loop N`회 내에 도달하지 못하면 안전을 위해 루프를 중단합니다. +5. 완결 후에도 에이전트 세션은 종료하지 않고, 다음 태스크 지시가 있을 때까지 프롬프트 대기 상태(Standby)로 유지됩니다. + +--- + +## CLI Option ↔ Workflow Phase Mapping + +워크플로우 단계별로 활용할 수 있는 `run_loop.sh` 옵션 규격은 다음과 같습니다: + +| 워크플로우 단계 | 해당 CLI 옵션 | 설명 | +| :--- | :--- | :--- | +| **Phase 1: Planning** | `--plan` | Planner 에이전트를 기동하여 최초 계획 작성을 강제합니다. | +| **Phase 1: Debate** | `--plan-talk N` | Planner와 Creator가 상호 대화식 챌린지 루프를 `N`회 돌며 계획을 교차 정제합니다. | +| **Phase 2: Execution** | (기본값) | `--target-agent`로 명시한 주 작업 세션에 코딩 태스크를 주입합니다. | +| **Phase 3: Review** | `--reviewer "A,B"` | 지정된 리뷰어 세션 리스트(`A`, `B` 등)에 교차 Peer Review를 위임합니다. | +| **Phase 3: Consensus** | `--all-reviewer` | 레지스트리에 등록된 모든 active 리뷰어 세션을 자동으로 수집하여 리뷰를 돌립니다. (지정/수집된 모든 리뷰어의 PASS 만장일치가 항상 필요합니다.) | +| **Iterative Loop** | `--max-loop M` | NOT PASS 또는 린트 실패 시 최대 `M`회까지 Planner와 Creator 간 피드백 루프를 반복합니다. | + +--- + ## Workflow ```bash @@ -74,10 +156,12 @@ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ --task "Fix typo in deploy/README.md" # 2. Collaborative planning + Targeted Reviewers + Safety limits +# (실전 자율 루프 기동의 표준 패턴 — 리뷰어 2인 지정 + 전원 합의 + 최대 3회 반복) bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ --plan \ --plan-talk 1 \ --reviewer "canary-projects-multi-agent-mux-reviewer-cline,canary-projects-multi-agent-mux-reviewer-claude" \ + --all-reviewer \ --max-loop 3 \ --verbose \ --target-agent "canary-projects-multi-agent-mux-creator-claude" \ @@ -94,6 +178,8 @@ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ ## Pitfalls -- **Incorrect Verdict format**: Reviewers MUST output `[VERDICT: PASS]` or `[VERDICT: NOT PASS]` in their final reports for the loop parser to recognize results. If missing, the parser falls back to scanning for "PASS" or "not pass" but warns. -- **Session Availability**: Ensure the referenced planner, creator, and reviewer sessions are running or alive before launching `run_loop.sh`. -- **NFS Lock Shadowing**: Spawning simultaneous loop processes will serialize job database transactions. Let one loop finish before launching another. +- **Incorrect Verdict format (앵커링 파서 하드닝)**: 리뷰 리포트 파일 내에서 `[VERDICT: PASS]` 또는 `[VERDICT: NOT PASS]` 토큰은 반드시 리포트의 **마지막에 단독 행**으로 기재되어야 합니다. 코드 인용이나 변경 diff 내에 등장하는 토큰은 매칭 대상에서 완전 배제됩니다. +- **Fail-closed on missing verdict**: 최종 Verdict 토큰이 누락되거나 리포트 픽업에 실패하면, 파서는 **경고 후 통과시키는 것이 아니라** 안전을 위해 즉시 `NOT PASS`로 판정(fail-closed)하고 교정 사이클을 수행합니다. 리뷰어에게는 반드시 리포트 끝에 단독 행으로 토큰을 찍도록 지시해야 합니다. +- **Session Availability**: `run_loop.sh` 기동 전에 참조되는 Planner, Target Agent, Reviewer 세션들이 모두 tmux 세션으로 기동되어 (`status.sh` 기준 `alive` 및 `running`) 있어야 합니다. +- **동시 루프 기동 금지 (NFS Lock Shadowing)**: 동일한 작업 트리 내에서 다수의 `run_loop.sh` 제어기를 동시에 기동하면 SQLite DB 갱신 경합 및 YAML 데이터 오염이 발생합니다. 하나의 루프가 끝날 때까지 다른 루프를 병렬로 기동하지 마십시오. +- **원자적 아카이빙 (Promotion)**: 루프 성공 종료 시 최종 계획서와 검증 리포트들은 `.agents/reports//` 디렉토리로 원자적으로 덮어쓰기(`mv -f`)되어 보존됩니다. 해당 경로의 리포트들로 VCS 추적성을 확보해야 합니다. diff --git a/AGENTS.md b/AGENTS.md index f239e30..f33cd48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,4 +67,4 @@ Strong success criteria let you loop independently. Weak criteria ("make it work **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. -Read [MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md) (or [Korean version](.agents/MULTI_AGENT_RULES.ko.md)) and [multi_agent_workflow.md](.agents/multi_agent_workflow.md) first before working and follow the instructions for orchestration and collaboration. \ No newline at end of file +Read [MULTI_AGENT_RULES.md](.agents/MULTI_AGENT_RULES.md) (or [Korean version](.agents/MULTI_AGENT_RULES.ko.md)) and [multi-agent-mux-loop/SKILL.md](.agents/skills/multi-agent-mux-loop/SKILL.md) first before working and follow the instructions for orchestration and collaboration. \ No newline at end of file