multi-agent-mux/OPTIMIZATION.md

🛠️ Multi-Agent Mux Loop (/multi-agent-mux-loop) 최적화 및 개선 분석서 (OPTIMIZATION.md)

본 문서는 /multi-agent-mux-loop 스킬 및 오케스트레이션 스크립트(run_loop.sh)의 불필요한 문구, 스킬 명세와 실제 코드 구현 간의 괴리, 필수 절차의 기계적 강제성 부족 항목을 분석하고, 이를 코딩적으로 강제 및 최적화하기 위한 최종 해결 방안을 정의한 분석서입니다.

---

1. 🔍 불필요한 문구, 모순 및 중복 항목 (Redundant & Inconsistent Issues)

ISSUE-1: CLI 옵션 상호 배타성 및 충돌 경고의 취약함

• 현상: --all-reviewer 옵션과 --reviewer "A,B" 옵션을 함께 전달할 경우, run_loop.sh에서 경고 메시지만 출력하고 --reviewer 목록을 무시함. 또한 --plan 모드가 비활성화된 상태에서 --plan-talk N을 전달할 경우 역시 경고 후 턴 설정을 무시하고 진행됨.
• 문제점: 에이전트나 사용자가 잘못된 파라미터 조합을 주입했을 때 스크립트가 조기에 에러로 실패(Fail-Fast)하지 않고 진행하여 혼선을 야기함.
• 해결 방안:
  1. 파라미터 파싱 단계에서 상호 배타적인 옵션이 포함된 경우 경고로 넘기지 않고 즉시 에러(exit 1)를 반환하도록 검증 로직 강화.
  2. SKILL.md 문서 내의 옵션 예시(Workflow 섹션) 중 두 옵션이 동시에 사용된 오류 표기를 상호 배타 규격에 맞게 정정.

ISSUE-2: SKILL.md 명세 문서 내 레거시 용어 및 문구

• 현상: 스킬 명세서 문서 내 일부 설명 및 주석에 TMUX 시절의 표현이나 레거시 파라미터 관련 설명이 혼재되어 있음.
• 해결 방안: Herdr 엔진 기반으로 완전히 마이그레이션된 현재 구조에 맞춰 스킬 명세서(SKILL.md) 내 문구를 정돈하고 불필요한 레거시 언급을 제거함.

---

2. ⚠️ 명세(Specification)에는 정의되어 있으나 코드로 강제되지 않은 작업 절차 (Specification vs Implementation Discrepancies)

ISSUE-3: [VERDICT: PASS] 판정 포맷 템플릿의 기계적 검증 및 가이드 부족

• 현상: 스킬 명세 및 규약에서는 리뷰어 보고서의 "마지막 줄 단독 행"에 [VERDICT: PASS] 또는 [VERDICT: NOT PASS] 토큰이 명시되어야 함을 요구함. 하지만 리뷰어 에이전트 프롬프트에 텍스트 문구로만 지시될 뿐, 작성 전후 양식을 검증하거나 보정하는 장치가 스크립트 레벨에 없음.
• 문제점: 리뷰어가 보고서 작성 시 줄바꿈 미입력, 마크다운 코드블록 인용, 기타 형식 오류를 범할 경우 내용이 통과이더라도 파서가 fail-closed로 동작하여 무조건 NOT PASS 처리됨.
• 해결 방안: 리뷰어 지시 프롬프트에 정확한 템플릿 포맷 예시를 강화하고, 필요시 파싱 실패 시 1회 구조화 재작성 지시(Fix-up prompt) 기계적 트리거 마련.

ISSUE-4: Definition of Done (DoD) 및 원자적 커밋(Atomic Commit)의 기계적 검증 부재

• 현상: 규약 및 스킬 명세에는 Creator(작업자)가 구현 완료 후 DoD 체크리스트를 실행하고 원자적 커밋을 수행한 뒤 리뷰어에게 전달하도록 명시되어 있음.
• 문제점: run_loop.sh는 Creator 잡이 종료된 후 실제 git status 변경 유무나 커밋 생성 여부를 확인하지 않고 단순히 지시 프롬프트에만 의존함. 커밋이 수행되지 않거나 변경분(diff)이 0건인 경우에도 루프가 그대로 진행되어 무의미한 리뷰가 수행됨.
• 해결 방안: Phase 2 (구현 단계) 완료 직후 dod_changed_paths 헬퍼 및 git diff 누적 관제를 수행하여, 변경 경로가 0건인 경우 exit 1로 즉시 실패 처리하고 원자적 커밋 미수행 시 1회 경고 및 재지시를 내리는 코딩 게이트 구축.

ISSUE-5: 기획-구현 대화 루프(--plan-talk)의 이의제기 수렴 여부 판단 부재

• 현상: --plan-talk N 설정 시 Planner와 Creator 간의 이의제기(Challenge) 및 계획 갱신(Refine) 대화가 N회 진행됨.
• 문제점: Creator의 이의제기가 실제로 Planner에 의해 수용 및 합의되었는지 논리적 종결 여부를 확인하지 않고, 무조건 지정된 턴 수(N)를 기계적으로 소모한 후 다음 단계로 진행함.
• 해결 방안: Planner 갱신 리포트에 [AGREEMENT: REACHED] 같은 수렴 판정 토큰을 도입하거나, 이의제기가 없는 경우 N회 턴 전이라도 조기 종료(Early Break)할 수 있는 로직 추가.

ISSUE-6: 타당하지 않은 리뷰 피드백 거부/반론 프로토콜의 스크립트 미지원

• 현상: MULTI_AGENT_RULES.md 1장 규약에는 "개발 팀장이 리뷰어의 타당하지 않은 피드백을 거부하고 명확한 이유를 회신할 수 있다"고 명시되어 있음.
• 문제점: run_loop.sh는 리뷰어의 NOT PASS 피드백 전체를 Creator에게 일방적으로 주입할 뿐, Creator가 특정 피드백을 거부하거나 반론을 제기하여 상호 조율하는 이의제기 채널이 코딩적으로 구현되어 있지 않음.
• 해결 방안: Creator 교정 단계 프롬프트에 반론 작성 템플릿을 허용하고, 반론 발생 시 Planner/Reviewer에게 재검토를 요청하는 이의제기 브랜칭 로직 설계.

---

3. 🛡️ 오케스트레이션 위임 및 안전성/동시성 강제안 (Orchestration Enforcement & Reliability)

ISSUE-7: 동일 워크스페이스 내 중복 루프 기동 방지 락 (Race-Free Lock) 설계 정교화

• 현상: 동일 작업 트리에서 다수의 run_loop.sh 스크립트가 병렬 기동될 경우 SQLite DB 갱신 경합 및 YAML 데이터 오염이 일어날 수 있음.
• 문제점: 단순 PID 파일 존재 여부만 체크할 경우, PID Rollover(프로세스 ID 재사용) 또는 mkdir과 PID 기록 사이의 생성 창(Grace Window)에서 살아있는 락을 타 프로세스가 훔쳐가는 "락 도난(Live-lock theft)" 현상 발생.
• 해결 방안:
  1. 락 소유자 레코드를 단순 PID에서 PID + 시작시각(lstart) + 워크스페이스 3중 구조로 결합하여 PID 재사용을 결정적으로 차단.
  2. mkdir 직후 생성 창 유예 대기(Sleep Grace Period)를 부여하여 락 도난 방지.
  3. ps CLI 부재 시 Fails-Open(락 무시) 대신 Fails-Safe(락 존중 + 경고) 로 전환하여 DB/YAML 오염 원천 방지.

ISSUE-8: 비동기 잡 모니터링 타임아웃 및 헬스체크 최적화

• 현상: wait_for_job 기본 타임아웃이 3900초(65분)로 설정되어 있어, 에이전트 세션 패닉이나 사망 시 오케스트레이터가 과도하게 오랫동안 대기함.
• 해결 방안: 모니터링 수집 루프 내에서 herdr 세션의 라이브 상태(alive)를 매 주기마다 핑(Ping) 확인하여 세션 사망 시 즉시 fail-fast 하도록 개선.

ISSUE-9: 조건부 오케스트레이션 위임 가드 (Invocation-Aware Scoped Guard)

• 현상: 오케스트레이터(Antigravity)가 평상시에는 Main Creator로서 코드 및 문서를 직접 집필해야 하지만, /multi-agent-mux-loop 슬래시 커맨드/스킬이 인보크된 상황에서도 이를 인지하지 못하고 에이전트들에게 위임하는 대신 직접 수정을 시도하는 지침 이탈 발생.
• 문제점: 오케스트레이터의 파일 직접 수정 권한을 무조건 뺏으면(1번 방안 부작용) 일반 작업이 불가능해지고, 자연어 지침에만 의존하면 슬래시 커맨드 호출 시 위임을 건너뛰는 모순 발생.
• 해결 방안:
  • 평상시 (일반 요청): 오케스트레이터가 Main Creator로서 소스 및 마크다운 파일 직접 작성/수정 도구(write_to_file, replace_file_content)를 자유롭게 사용하여 단독 구현 수행.
  • /multi-agent-mux-loop 호출 시 (스킬 활성화 상태): 스킬 인터셉터 가드(Guardrail)가 작동하여 직접 수정 도구 호출을 거부(Interception)하고, **"슬래시 커맨드가 인보크되었으므로 직접 수정을 중단하고 run_loop.sh를 실행하여 위임하십시오"**라는 에러를 반환해 run_loop.sh 자율 위임 실행을 코딩적으로 강제.

---

본 분석서는 Planner(claude)와 Creator(agy)의 협업 계획(Job 96b6e07b) 및 리뷰어 만장일치 PASS 합의를 바탕으로 최종 작성된 수합 최적화 명세서입니다.