multi-agent-mux/.agents/MULTI_AGENT_RULES.ko.md

# MULTI_AGENT_RULES.md

본 문서는 새로운 프로젝트에 **MQTT 메시징 백플레인 및 Tmux 기반 멀티 에이전트 오케스트레이션 워크플로우**를 도입하고, 협업하는 에이전트들이 일관된 규칙과 아키텍처에 따라 안전하고 견고하게 작업을 수행할 수 있도록 정의한 공통 지침 및 규약입니다.

새로운 프로젝트에서 작업하는 모든 에이전트는 작업을 시작하기 전 이 문서를 반드시 정독하고 규약을 준수해야 합니다.

> [!NOTE]
> 이 저장소는 두 가지 별도의 지침을 사용합니다: 범용 LLM 행동 지침([AGENTS.md](../AGENTS.md)) 및 프로젝트 고유의 멀티 에이전트 오케스트레이션 규약([.agents/MULTI_AGENT_RULES.md](MULTI_AGENT_RULES.md)).

---

## 1. 에이전트의 역할 정의 (Agent Roles)

역할군 간의 책임 및 권한을 명확히 분리하여 병목을 줄이고 작업의 완성도를 높입니다.

### 👑 General Manager (총괄 매니저)
- **주요 책무**: 사용자와 직접 소통하여 요구사항 접수, 상세 작업 계획 수립, 팀장 에이전트 할당 및 작업 위임, 전체 워크플로우 통제 및 최종 완료 보고.
- **모호성 제거**: 사용자의 요구사항에 모호한 부분이 있다면 작업을 추측하여 진행하지 말고, 즉시 사용자에게 질문하여 명확히 해야 합니다 (`/grill-me` 슬래시 명령어 권장).

### 👥 Team Leaders (팀장)
새롭게 생성되는 에이전트(`antigravity`, `claude`, `cline`, `hermes` 등)는 각 팀의 **팀장** 역할을 수행합니다. 총괄 매니저로부터 작업을 위임받아 개발 또는 리뷰 워크플로우를 주도합니다.
- **Developer Team Leader (개발 팀장)**:
  - 총괄 매니저로부터 작업을 위임받습니다.
  - **작업 분석 및 계획**: 주어진 작업을 철저히 분석하고, 작은 단위로 문제를 나누어 세부 계획을 수립합니다.
  - **내부 병렬 처리**: 내부적으로 subagent를 활용해 위임받은 작업을 병렬적으로 처리할 수 있습니다.
  - **리뷰 타당성 검증 및 거부**: 리뷰어가 지적한 피드백을 면밀히 검토합니다. 타당한 제안은 수렴하여 코드를 수정하지만, 타당하지 않다고 판단되는 안건은 반영하지 않고 **그 명확한 이유를 작성하여 리뷰어에게 되돌려 보냅니다** (상세 태그 규약은 §3.1 '[REBUT:]' 참조).
  - **완료 신호 송신**: 모든 리뷰어들로부터 `PASS`를 획득하고 변경 사항이 검증되면, 최초 작업을 위임받았던 개발 팀장이 총괄 매니저에게 최종 작업 완료 신호를 송신합니다.
- **Reviewer Team Leader (리뷰어 팀장)**:
  - 개발 팀장으로부터 리뷰 요청을 접수합니다.
  - **문제 제시에 대한 이유와 개선 방향 포함**: 단순한 반려(`NOT PASS`) 통보는 금지됩니다. 이슈를 제기할 때는 **반드시 해당 문제가 발생하는 구체적인 이유와 확실한 개선 방향(코드 대안 포함)을 함께 작성**해야 합니다.
  - **합의 루프**: 모든 지적 사항이 해결되고 최종 `PASS`를 발행할 때까지 리뷰 루프에 동참합니다.
  - **재심 수행 의무 (Re-adjudication Duty)**: 개발 팀장의 반론(`[REBUT:]` 태그)을 수신한 경우, 리뷰어 팀장은 반드시 해당 안건을 재심하여 `[ADJUDICATION: SUSTAINED]` (지적 철회) 또는 `[ADJUDICATION: OVERRULED]` (지적 유지)를 명시해야 합니다. 수신된 반론을 무시하거나 재심을 우회하는 것은 금지됩니다.

### 🛡️ 역할 범위 준수 원칙 (Role Suitability Check)
- 모든 에이전트는 자신에게 부여된 역할에 부합하는 작업만을 수행해야 합니다. (예: 개발 팀장은 최종 PASS 여부를 결정하지 않으며, 리뷰어 팀장은 직접 프로젝트 소스코드를 작성하지 않습니다.)
- **자신의 역할에 맞지 않는 작업이 지시된 경우**, 에이전트는 반드시:
  1. 해당 작업을 수행하기에 가장 적합한 에이전트 세션을 추천하여 위임을 유도하거나,
  2. 프로젝트 연속성을 위해 극히 필요한 경우 직접 작업을 수행합니다.

---

## 2. 메시징 백플레인 & 레지스트리 규약

에이전트 간의 비동기 소통과 상태 관리는 분산 이벤트 채널 및 파일/DB 레지스트리를 통해 제어됩니다.

### 📡 MQTT 백플레인 (MQTT Backplane)
- **이벤트 라이프사이클**: 
  - `started` (작업 개시) ➡️ `progress`/`permission_required` (진행 상황 공유) ➡️ `completed` (성공 종료) 또는 `error` (실패 종료)
  - `completed` 및 `error`는 단 한 번만 발행되는 단말(Terminal) 이벤트입니다.
- **메시지 발행/구독 규칙**:
  - MQTT는 영속 큐를 보장하지 않으므로, 에이전트 구동 전 **반드시 구독자(`job_subscriber.py`)가 먼저 백그라운드에서 대기**해야 합니다 (Subscribe-before-Publish 원칙).
  - 단말 이벤트 발행 시 브로커에 `retain=True`로 영속화하여 늦게 합류한 구독자도 최종 상태를 읽을 수 있도록 조치합니다.
  - 전송 데이터에는 비밀번호, 개인키 등의 중요 비밀 정보나 절대 경로가 포함되지 않도록 보편화(Generalised)해야 합니다.

### 🗃️ 레지스트리 및 상태 관리
- 본 아키텍처는 목적에 따라 두 가지 레지스트리를 분리하여 운영합니다:
  - **잡 레지스트리 (Job Registry)**: 각 비동기 잡의 메타데이터와 생명주기는 개별 JSON 파일(`.mam/jobs/<id>.json`)로 기록되며, 다중 세션 간의 동시 청구(claiming) 경합은 파일 단위의 `fcntl` advisory lock(`registry_lock` via `registry.py`)을 통해 방어합니다.
  - **세션 레지스트리 (Session Registry)**: TMUX 모니터링 상태 및 에이전트 구동 정보는 SQLite WAL 데이터베이스(`.mam/agent-sessions.db`)를 통해 단일 호스트 내에서 안정적인 동시 트랜잭션으로 일관되게 제어합니다. 단, SQLite WAL 모드는 NFS(네트워크 파일 시스템) 환경에서는 완전한 파일 락이 보장되지 않으므로 로컬 파일 시스템 사용을 권장합니다.

### 🔑 세션 ID 생명주기 및 자동 할당 프로토콜
- **생성 시 자동 할당**: 신규 `claude` 세션은 생성 시 무작위 UUID(`mam_gen_uuid`)를 생성하여 `claude --session-id <uuid>`로 전달합니다. `.mam/agent-sessions.yaml`에는 `claude_session_id_own` 값과 함께 `session_id_source: assigned`, `session_id_verified: false`로 기록됩니다.
- **첫 메시지 구체화**: 트랜스크립트 `.jsonl` 파일은 사용자의 첫 프롬프트 메시지가 전달될 때 디스크에 구체화(materialize)됩니다.
- **모니터 확정 (C0)**: 모니터 루프(`reconcile.sh`)는 디스크상의 트랜스크립트 존재를 검증한 후 `session_id_verified: true` 및 `last_visible_status: pinned`로 승격시킵니다.
- **모호성 방어 (C-ambiguous)**: 미할당 세션에 대해 다수의 트랜스크립트 후보가 발견되면 임의 고정 없이 `C-ambiguous` 상태로 보고합니다.
- **경로 정규화 일치**: 모든 경로 계산(`mam_abs_workspace`, `mam_workspace_key`)은 심볼릭 링크를 실경로로 정규화(`cd -P && pwd -P` / `os.path.realpath`)하여 100% 키 일치를 보장합니다.

### 🛡️ 보안 프로토콜 (HMAC-SHA256)
- **무인증 PoC 모드**: 잡 레지스트리 생성 시 `auth_token`이 `null`로 지정된 경우(PoC 기본 모드), 별도의 서명 검증을 생략하고 모든 이벤트를 수용합니다 (`verify_hmac`이 항상 `True`를 반환).
- **인증 Production 모드**: 실배포 환경이나 인증이 필요한 연동 단계에서는 각 잡마다 고유 암호화 토큰(`auth_token`)을 발급합니다. 퍼블리셔는 이 토큰을 키로 삼아 `hmac_sig` 서명을 페이로드에 동반해야 하며, 수신단(`verify_hmac`)에서 서명이 없거나 일치하지 않는 메시지는 즉시 드랍하여 다운그레이드 공격을 원천 차단합니다.
- **롤아웃 전략**: 보안 스킴 갱신 시 송수신 노드 간 불일치로 인한 이벤트 드랍을 피하기 위해, 과도기적 하이브리드 포맷 전송(평문 유출 위험 있음)을 배제하고 **모든 노드를 일제히 업데이트하는 "동시 롤아웃(Simultaneous Rollout)"**을 채택해야 합니다.

---

## 3. 협업 워크플로우 실행 절차 (Workflow Loop)

```mermaid
sequenceDiagram
    autonumber
    actor User as 사용자
    participant GM as General Manager
    participant DTL as Developer Team Leader
    participant RTL as Reviewer Team Leaders
    participant M as MQTT Backplane

    User->>GM: 요구사항 전달
    GM->>DTL: 작업 위임 (예: 랜딩 페이지 제작)
    Note over DTL: 작업 분석, 세분화 및 subagent 병렬 구동
    DTL->>M: 'started' 이벤트 발행
    Note over DTL: 코드 변경 및 구현
    DTL->>M: 'completed' 발행
    DTL->>RTL: 리뷰 요청 (랜딩 페이지를 제작했습니다. 리뷰를 진행해주세요)
    Note over RTL: 교차 분석 & 검증
    alt 결함 발견 (리뷰어 피드백)
        RTL->>DTL: NOT PASS / 피드백 (반드시 이유와 확실한 개선 방향 포함)
        Note over DTL: DTL이 피드백의 타당성 검증
        alt 타당한 피드백
            Note over DTL: DTL이 수용하여 코드 수정
        else 타당하지 않은 피드백
            DTL->>RTL: 반론 및 거부 이유 전달 (부적절한 항목 미반영)
        end
        DTL->>RTL: 재리뷰 요청 (리뷰 안건 수정 완료)
    else 검증 통과
        RTL->>DTL: PASS
    end
    DTL->>GM: 최종 완료 신호 송신
    GM->>User: 사용자에게 작업 완료 통보
```

1. **계획 수립 및 할당**: 총괄 매니저는 개발 팀장에게 작업을 인가합니다.
2. **분석 및 내부 실행**: 개발 팀장은 작업을 분석하고 세분화하여 계획을 세운 뒤 내부 subagent를 가동하여 구현을 완료합니다. 이후 `started`를 거쳐 `completed` 이벤트를 발행하고 리뷰어에게 검수를 요청합니다.
3. **이의 제기 및 정제 루프**:
   - 리뷰어 팀장은 상세 피드백 시 반드시 이유와 보완 방향을 제시해야 합니다.
   - 개발 팀장은 의견을 검토해 타당하면 수정하고, 타당하지 않으면 반론과 근거를 회신합니다.
   - 리뷰어 전원이 `PASS`를 인가할 때까지 이 과정이 반복됩니다.
4. **최종 보고**: 개발 팀장이 총괄 매니저에게 완료 신호를 보내면 총괄 매니저가 사용자에게 완료를 알립니다.

### 3.1 Rebuttal & Adjudication Protocol (이의제기 및 재심 프로토콜)

개발 팀장이 리뷰어의 피드백이 타당하지 않거나 부적절하다고 판단하는 경우, 묵인하거나 수용하지 않고 정식 반론(Rebuttal)을 제기해야 합니다.

| 태그 | 발행 주체 | 의미 |
|---|---|---|
| `[REBUT: <리뷰어_세션명>]` | 개발자 | 지정된 리뷰어의 피드백을 공식 거부. 리포트에 상세 근거 서술 필수. 타당한 지적은 정상 반영. |
| `[ADJUDICATION: SUSTAINED]` | 리뷰어 | 개발자의 반론을 수용하여 이전 지적 사항을 철회함. |
| `[ADJUDICATION: OVERRULED]` | Reviewer | 개발자의 반론을 기각하고 이전 지적 사항을 유지함. |
| `[ARBITRATION: CREATOR]` / `[ARBITRATION: REVIEWER]` | 플래너 | 개발자와 리뷰어 간 교착 상태 시 최종 재정 (`--plan` 모드 한정). |

**프로토콜 불변 규칙**:
1. **반론은 PASS를 대체하지 않음**: 수용된 반론(`SUSTAINED`)은 해당 지적 사항만 철회시킵니다. 리뷰 루프가 완수되려면 여전히 모든 리뷰어로부터 만장일치 `[VERDICT: PASS]`를 획득해야 합니다.
2. **Fail-Closed 원칙**: 리뷰어가 명시적으로 `[ADJUDICATION: SUSTAINED]`를 발행하지 않는 한, 기존 지적 사항은 유효(`OVERRULED`)한 것으로 간주됩니다.
3. **예산 및 상한 제약**: 반론은 이터레이션 예산(`--max-rebut`, 기본 패스당 1회, 새 지적 발생 시 이터레이션별 리셋) 및 런 전체 상한(`MAX_REBUT x MAX_LOOP`)의 제약을 받습니다.
4. **교착 상태 에스컬레이션**: 리뷰어가 `OVERRULED`를 고수하고 플래너 모드(`--plan`)가 활성화된 경우 플래너가 재정합니다. 플래너가 없으면 리뷰어의 지적이 우선 반영됩니다(`Fail-Closed`).
5. **세션 매칭 및 중복 제거**: 반론 태그는 실제로 지적을 제기한 리뷰어 세션명을 지정해야 합니다. 단일 리포트 내 동일 리뷰어 대상 중복 태그는 단 1회의 재심 라운드로 병합됩니다.

---

## 4. 분석 인프라 패턴 & 실무 가이드 (Infra Patterns)

장기 실행 에이전트 분석 중 발생하는 유실 및 인프라적 장애를 예방하기 위한 중요 지침입니다.

### 📸 TUI 뷰포트 절단 방지 (Pane Snapshotting 3대 규칙)
TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해 이전 출력이나 장문의 디버깅 로그를 잃지 않도록 아래의 **스냅샷 패턴을 의무적으로 수행**합니다.
1. **Pre-brief Capture**: 작업 지침(Brief)을 전송한 직후, 즉시 해당 세션의 pane을 캡처(`capture-pane -S -200`)해두어 입력 기록의 시작점을 백업합니다.
2. **Loop Snapshot**: 장기 실행(5분 이상) 중인 에이전트 세션의 경우, 주기적으로(예: 30초마다) 뷰포트를 스캔하여 증분 데이터를 `/tmp/pane-snap.txt`에 계속 누적(append) 기록합니다.
3. **Post-job Capture**: 잡 완료/에러 반환 즉시 전체 pane 상태를 마지막으로 캡처하여 전체 작업 궤적을 보존합니다.

### 📄 마크다운 기반 협업 및 결과 전달 (Markdown-Based Workflow & Communication)
- **핵심 원칙**: TMUX `send-keys`나 입력 버퍼를 통해 긴 지시사항을 직렬로 입력하는 과정에서 문자 누락이나 레이아웃 유실이 발생하는 것을 방지하기 위해, 에이전트 간의 모든 주요 협업 소통은 파일 기반 마크다운 문서 생성을 원칙으로 합니다.
- **세부 규칙 및 규약**:
  - **예외 사항**: 1~2줄 내외의 매우 단순한 요청, 상태 확인, 수락 진행 등의 단발성 프롬프트는 tmux 입력을 통해 직접 보낼 수 있습니다.
  - **작업 위임**:
    - *수동 경로*: 상세 사양과 계획 수립 등의 복잡한 작업 지시는 먼저 로컬 마크다운 파일(예: `.mam/reports/brief-<job_id>.md` 또는 지정된 워크스페이스 경로)로 작성한 후, 에이전트에게 `"Read <파일경로> and execute."` 라는 실행 명령만 전달하십시오.
    - *자동 경로*: 자동화 잡 런너(`multi-agent-mux-delegate-job submit`)는 잡 등록 시 `.mam/jobs/<job_id>/brief.md` 디렉터리에 지시서를 자동 집필하고 단일 라인 포인터 프롬프트만 에이전트 세션에 인가합니다.
  - **결과 안내 및 피드백**:
    - *수동/영구 리뷰*: 상세 리뷰 결과, 설계 제안서 등은 `.mam/reports/<tmux_session_name>/report-<job_id>.md` 경로에 저장합니다.
    - *자동화 잡 보고서*: 자동 위임된 비동기 작업의 완료 결과는 잡 디렉터리 하위인 `.mam/jobs/<job_id>/<agent_name>-reports/report-final.md` (루프/Discuss 위임 시에는 `<clean_session_name>-reports/`) 경로에 기록해야 합니다.
    - *버전 관리 이관*: 버전 관리가 필요한 주요 산출물(최종 설계 계획, 최종 리뷰 보고서, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(구체적으로 `.agents/reports/<tmux_session_name>/` 또는 `docs/reports/` 등)로 명시적으로 복사하여 이관 보존해야 합니다.
  - **디스크 정리 및 보존 정책 계약 (Cleanup & Retention)**: `.mam/jobs/<job_id>/` 및 `.mam/reports/` 폴더 아래의 파일들은 휘발성 감사 이력(audit-trail) 산출물입니다. 버전 관리가 필요한 문서들은 `.agents/reports/` 하위로 수동 복사하여 커밋해야 하며, `stop_session.sh` 세션 종료 스크립트는 이들 보고서 디렉터리를 자동으로 삭제하지 않으므로 수동 또는 주기적 클린업이 권장됩니다.

### 3.2 조건부 오케스트레이션 위임 가드 (Invocation-Aware Scoped Guard — O-3)

| 모드 | 오케스트레이터 행위 | 도구 허용 여부 |
|---|---|---|
| **일반 모드 (Normal Mode)** | 주 작업자 (직접 코드 및 문서 수정) | 모든 파일 수정 도구 허용 |
| **루프 활성 모드 (`/multi-agent-mux-loop`)** | 오케스트레이터 (`run_loop.sh` 자율 위임) | `file_change`, `edit_notebook`, `write_blob` **하드 블록** (`.agents/hooks.json`) |

- **Fail-Open 원칙**: 훅 내부 오류 또는 파싱 실패 시 무조건 `allow`로 처리하여 작업을 차단하지 않음.
- **신원 검증 (Identity Validation)**: PID 재사용으로 인한 영구 차단(Livelock)을 방지하기 위해 `pid` + `lstart`(프로세스 시작시각) 신원 대조 검증 수행.

### ⏱️ 타임아웃 구성 및 정렬 규칙
- **잡 실행 제한 (`timeout_sec` & `idle_timeout_sec`)**: 각 잡은 전체 실행 만료 시간(`timeout_sec`, 기본 3600s)과 메세지 미수신 유휴 시간(`idle_timeout_sec`, 기본 120s)을 독립적으로 가집니다.
- **모니터 유휴 대기 (`SUB_IDLE_TIMEOUT`)**: 모니터 스크립트(`reconcile.sh`)의 유휴 대기 시간(`SUB_IDLE_TIMEOUT`) 기본값은 잡 최대 예산에 맞춰 `3600s`(1시간) 이상으로 항상 넉넉히 설정해야 합니다. 모니터가 작업 완료 전에 유휴 감지로 조기 자동 종료되어 백그라운드 태스크 관리를 소실하는 문제를 방지하기 위함입니다.

---

## 5. 새 프로젝트 적용 체크리스트 (Setup Checklist)

새 프로젝트에 이 에이전트 오케스트레이션 모델을 구축할 때의 체크리스트입니다.

- [ ] **가상환경 의존성**: `pyyaml`, `paho-mqtt` 등 필요한 Python 패키지가 `.venv` 또는 `requirements.txt`에 포함되었는가?
- [ ] **환경 설정 파일**: MQTT 브로커 주소 및 보안 Credential이 `.mam.env` 파일에 안전하게 로드되고 공유되는가?
- [ ] **디렉토리 규약**: 레지스트리 경로(`.mam/jobs/`) 및 로깅 경로(`.mam/delegate_job_logs/`)가 `.gitignore`에 등록되었는가?
- [ ] **스크립트 구비**: `mqtt_common.py`, `publish_event.py`, `job_subscriber.py`, `registry.py` 등의 핵심 모듈이 배치되었는가?
- [ ] **HMAC 활성화**: 새로운 레지스트리 잡 발급 시 난수 기반의 `auth_token`이 정상적으로 주입되고, 서명 기반의 상호 인증이 활성화되는가?
- [ ] **운영 헌장 배치**: 본 규약 파일(`MULTI_AGENT_RULES.md`)이 새 프로젝트의 **.agents/ 디렉터리**에 배치되었는가? (프로젝트 루트를 깔끔하게 유지하면서도 온보딩하는 에이전트들이 규칙을 이해할 수 있도록 `.agents/` 경로 배치가 권장됩니다.)

---

## 6. 온보딩 핸드셰이크 프로토콜 (Onboarding Handshake)

새롭게 기동되는 팀장 에이전트는 실무 작업을 수임하기 전에 반드시 `--onboard` 메커니즘을 통해 맥락을 파악하고 동기화(Alignment)해야 합니다. 이를 통해 올바른 설계 규칙과 저장소 이력을 숙지한 상태에서 안전하게 협업에 참여할 수 있습니다.

### 🔄 온보딩 핸드셰이크 흐름 (Onboarding Handshake Sequence)
1. **온보딩 플래그와 함께 생성**: 총괄 매니저가 다음 명령을 통해 새 세션을 생성합니다:
   ```bash
   bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh --workspace "$(pwd)" --agent <agent> --role <role> --onboard
   ```
   이 자동화된 온보딩 워크플로우는 백그라운드 잡을 등록하여 `.mam/jobs/<job_id>/brief.md` 에 온보딩 지시서를 작성하고 에이전트 세션에 지시서 포인터만 입력합니다.
2. **에이전트 맥락 동기화**: 에이전트가 시작되면 아래 지시사항이 담긴 온보딩 brief를 자동으로 수임하여 확인합니다:
   - `README.md` 및 `.agents/MULTI_AGENT_RULES.md`를 필독하여 설계 규약과 제약사항을 인지한다.
   - `git status` 및 `git diff`를 실행하여 레포지토리의 활성 수정 내역을 분석한다.
   - `.mam/agent-sessions.yaml`을 읽어 현재 러닝 상태인 타 에이전트 목록을 확인하고, 자신의 지정된 `role`을 검증한다.
3. **핸드셰이크 완료 발행**: 에이전트는 위의 맥락 파악 작업을 완료한 후, `publish_event.py`를 호출하여 다음과 같은 단말 완료 이벤트를 발행합니다:
   - Detail: `"Onboarding complete; aligned with role <role>"`
4. **총괄 매니저 승인 게이트**: 총괄 매니저는 이 `completed` 핸드셰이크 신호가 오디팅 로그에 수렴될 때까지 대기(gating)해야 하며, 핸드셰이크가 통과된 것이 검증된 이후에야 해당 세션에 실무 또는 검수 작업을 위임합니다.

---

*본 가이드는 협업 효율성과 코드 보안의 엄격한 균형을 유지하기 위한 규범입니다. 변경 사항이 필요한 경우 총괄 매니저 및 전체 팀장의 합의를 거쳐 본 문서를 업데이트해야 합니다.*