109 lines
6.1 KiB
Markdown
109 lines
6.1 KiB
Markdown
# 📑 자율 반복 정제 루프 스킬 (`multi-agent-mux-loop`) 개발 계획서
|
|
|
|
이 문서는 멀티 에이전트 자율 오케스트레이션 루프(`multi-agent-mux-loop`)의 **최종 안전/가드레일 옵션 규격을 포함하여 완벽하게 정제된 마스터 계획서**입니다.
|
|
리뷰어 에이전트들의 교차 2차 피드백(Verdict 파싱, 자가 리뷰 방지, 타임아웃 보강)을 완벽하게 수렴하여 정교하게 갱신되었습니다.
|
|
|
|
---
|
|
|
|
## 1. ⚙️ 최종 스킬 명령 및 전체 옵션 세트 명세 (CLI Spec)
|
|
|
|
```bash
|
|
$ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
|
|
[--plan] \
|
|
[--plan-talk N] \
|
|
[--reviewer "reviewer-1,reviewer-2"] \
|
|
[--all-reviewer] \
|
|
[--max-loop N] \
|
|
[--verbose] \
|
|
[--cleanup] \
|
|
--target-agent "<creator-session-name>" \
|
|
--task "수행할 작업 목표"
|
|
```
|
|
|
|
### 📥 옵션 상세 리스트 및 가드레일 제약
|
|
|
|
| 옵션명 | 기본값 | 분류 | 역할 및 안전 조치 |
|
|
|---|---|---|---|
|
|
| `--plan` | 비활성 | 기능 | Planner 에이전트를 기동하여 협력 계획 수립 및 토론 단계 개시. (비활성화 시 기존 계획서를 로드하며, 계획서가 없는 경우 Creator가 직접 계획 및 설계를 수립하여 구동) |
|
|
| `--plan-talk N` | `1` | 안전 | 플래너-작업자 간 토론 왕복 횟수 상한선. 토큰 낭비 무한 토론 차단. |
|
|
| `--reviewer "A,B"` | 비활성 | 기능 | 지정된 peer 리뷰어 에이전트 세션(들)에 피드백 루프 의뢰 (주 작업자 세션은 강제 제외). |
|
|
| `--all-reviewer` | 비활성 | 기능 | 레지스트리 상의 모든 `role: reviewer` 세션들을 전수 자동 수집하여 의뢰 (주 작업자 세션은 강제 제외). |
|
|
| `--max-loop N` | `3` | **안전 (필수)** | 반려(`NOT PASS`) 시 최대 수정 횟수 제한. **토큰 비용 폭주 방지 가드레일.** |
|
|
| `--verbose` | 비활성 | 편의 | 단계별 타임라인 진행 상태 및 잡 매핑 로그의 실시간 상세 출력. |
|
|
| `--cleanup` | 비활성 | 편의 | 루프 완료 후 성공한 임시 잡 파일(`.mam/jobs/`)들의 자동 클린업 청소. |
|
|
| `--target-agent` | (필수) | 인프라 | 구현을 처리할 주 개발자(Creator) 세션 이름 명시. |
|
|
| `--task` | (필수) | 인프라 | 자율 루프에 전달할 최종 구현 지시사항 텍스트. |
|
|
|
|
---
|
|
|
|
## 🔄 2. 자율 오케스트레이션 상세 파이프라인 (Sequence Flow)
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
actor User as 사용자 / run_loop.sh
|
|
participant Plan as Planner Agent
|
|
participant Dev as Creator Agent
|
|
participant Rev as Reviewer Agents
|
|
|
|
User->>User: run_loop.sh 기동 (옵션 세트 검증 및 대상 예외 필터링)
|
|
|
|
%% Planning & Challenge discussion
|
|
alt --plan 지정 시
|
|
User->>Plan: delegate-job (계획 수립 지시)
|
|
Plan-->>User: 계획서 도출 완료
|
|
loop 지정된 --plan-talk 횟수 동안 반복 (기본 1회)
|
|
User->>Dev: delegate-job (계획서 비판적 검토 및 이의제기 지시)
|
|
Dev->>Plan: 계획서의 맹점 1가지 이상 Challenge 메일 교환
|
|
Plan-->>Dev: 수정 반영 및 최종 계획 합의
|
|
end
|
|
else --plan 미지정
|
|
alt 기존 계획 존재 시
|
|
User->>Dev: 기존 계획서 로드 및 구현 지시
|
|
else 계획 미존재 시
|
|
User->>Dev: Self-planning 지시 (스스로 계획/설계 수립하여 구현)
|
|
end
|
|
end
|
|
|
|
%% Execution
|
|
User->>Dev: delegate-job (작업 지시)
|
|
Dev-->>User: 구현 완료 (git diff 발생)
|
|
|
|
%% Peer-Review Loop with Max-Loop constraint
|
|
loop 최대 --max-loop 횟수 동안 반복 (기본 3회)
|
|
alt 리뷰어 옵션 지정 시 (--reviewer or --all-reviewer)
|
|
User->>Rev: delegate-job (정식 peer 코드 리뷰 위임)
|
|
Rev-->>User: [VERDICT: PASS] 또는 [VERDICT: NOT PASS] 태그 리포트 제출
|
|
alt 100% PASS 충족 시
|
|
Note over User,Rev: 루프 즉시 탈출 (성공)
|
|
else NOT PASS 검출 시
|
|
User->>Dev: 피드백 전달 및 수정 지시 (피드백 난이도에 따라 Planner 우회 계획 갱신 적용)
|
|
end
|
|
else 리뷰어 미지정
|
|
User->>Dev: Self-Review 지시 (자가 검증 및 자율 종결)
|
|
end
|
|
end
|
|
|
|
%% Cleanup & Final Report
|
|
alt --cleanup 지정 시
|
|
User->>User: 임시 잡 폴더 청소
|
|
end
|
|
User-->>User: 최종 결과 요약 출력 및 마감
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ 3. 개발 로직 및 안전 파싱 체크포인트
|
|
|
|
### 1) Verdict 판정 파서 안전 가이드라인 (Fail-Closed & Precedence)
|
|
* **NOT PASS 우선권**: 리뷰 리포트 본문 내에 `[VERDICT: NOT PASS]` 가 단 한 번이라도 등장하면, `[VERDICT: PASS]` 문구 존재 여부와 상관없이 무조건 **NOT PASS**로 처리하여 오독 필터링을 방지합니다.
|
|
* **Fail-Closed 기본 실패주의**: 태그 누락이나 malformed 리포트로 인해 두 토큰이 모두 스캔되지 않을 경우, 통과시키지 않고 **NOT PASS(실패)** 로 취급하여 루프 무한 기동 및 맹점 통과를 원천 차단합니다.
|
|
* **템플릿 명시**: 리뷰어 위임 잡 발행 시, 최종 결과 요약 행에 정형화된 태그 `[VERDICT: PASS]` 혹은 `[VERDICT: NOT PASS]`를 리포트 본문 하단에 반드시 기재하도록 프롬프트 템플릿에 명시적으로 추가합니다.
|
|
|
|
### 2) 자가 리뷰 방지 가드 (Exclusion Rule)
|
|
* `--all-reviewer` 혹은 `--reviewer` 목록을 소집할 때, 해당 작업을 수행한 대상 개발자 세션인 `$TARGET_AGENT` 는 **리뷰어 매핑 목록에서 강제로 배제(Exclude)** 하도록 파싱 쉘 스크립트에서 필터링을 적용합니다.
|
|
|
|
### 3) 쉘 예외 처리 및 대기 타임아웃 (Error Guard & Timeout)
|
|
* `grep -oP` 나 `find | head` 시 매칭이 없을 때 `set -eo pipefail`에 의해 쉘 스크립트 전체가 비명횡사하지 않도록 `|| true` 가드 및 공백 체크문을 엄밀히 적용합니다.
|
|
* `wait_for_job` 함수 실행 시 타임아웃 가드레일(`WAIT_TIMEOUT`, 기본값 3600초)을 명시적으로 설계하여 무한 루프 행(Hang) 현상을 차단합니다.
|