docs(isolation): commit session isolation design documents and guidelines

2026-07-10 12:28:06 +09:00
parent 768cfe5c6d
commit d76e470942
8 changed files with 589 additions and 4 deletions
@@ -122,8 +122,12 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해
 - **핵심 원칙**: TMUX `send-keys`나 입력 버퍼를 통해 긴 지시사항을 직렬로 입력하는 과정에서 문자 누락이나 레이아웃 유실이 발생하는 것을 방지하기 위해, 에이전트 간의 모든 주요 협업 소통은 파일 기반 마크다운 문서 생성을 원칙으로 합니다.
 - **세부 규칙 및 규약**:
  - **예외 사항**: 1~2줄 내외의 매우 단순한 재평가 요청, 상태 확인, 수락 진행 등의 단발성 프롬프트는 기존처럼 tmux 입력을 통해 직접 보낼 수 있습니다.
-  - **작업 위임**: 상세 사양과 계획 수립 등의 복잡한 작업 지시는 먼저 로컬 마크다운 파일(예: `.mam/jobs/brief-<job_id>.md` 또는 지정된 워크스페이스 경로)로 작성한 후, 에이전트에게 `"Read <파일경로> and execute."` 라는 단순화된 실행 명령만 전달하십시오.
-  - **결과 안내 및 피드백**: 상세 리뷰 결과, 설계 제안서, 구현 완료 리포트 및 감사 주석 등은 반드시 마크다운 파일로 영속화하여 제공해야 합니다. 모든 에이전트는 `.mam/jobs/<agent_name>/` 아래에 자신만의 전용 디렉터리를 생성하고, 자신의 작업 결과 보고 마크다운 파일은 해당 디렉터리 내부에 저장해야 합니다 (예: `.mam/jobs/<agent_name>/report-<job_id>.md`). 수신 에이전트는 잘린 터미널 화면 캡처에 의존하는 대신 디스크에서 해당 파일을 직접 로드하여 확인합니다.
+  - **작업 위임**: 상세 사양과 계획 수립 등의 복잡한 작업 지시는 먼저 로컬 마크다운 파일(예: `.mam/reports/brief-<job_id>.md` 또는 지정된 워크스페이스 경로)로 작성한 후, 에이전트에게 `"Read <파일경로> and execute."` 라는 단순화된 실행 명령만 전달하십시오.
+  - **결과 안내 및 피드백**: 상세 리뷰 결과, 설계 제안서, 구현 완료 리포트 및 감사 주석 등은 반드시 마크다운 파일로 영속화하여 제공해야 합니다. 기계 전용인 잡 레지스트리 평면(`.mam/jobs/`)과의 물리적 분리를 위해, 모든 에이전트는 `.mam/reports/<tmux_session_name>/` 아래에 전용 디렉터리를 형성하고 결과 보고 마크다운 파일을 저장해야 합니다 (여기서 `<tmux_session_name>`은 `.mam/agent-sessions.yaml`의 `name` 필드와 완전히 일치해야 합니다. 예: `.mam/reports/<workspace_slug>-creator-<agent>/report-<job_id>.md`). 수신 에이전트는 잘린 터미널 화면 캡처에 의존하는 대신 디스크에서 해당 파일을 직접 로드하여 확인합니다.
+  - **디스크 정리 및 보존 정책 계약 (Cleanup & Retention)**:
+    - `.mam/reports/` 폴더 아래의 파일들은 감사 이력(audit-trail) 산출물로 보존됩니다.
+    - 해당 격리 디렉터리들은 `stop_session.sh` 등을 통해 세션이 정상적으로 종료되거나 파기(`--purge-conversation`)될 때 자동으로 함께 정리되어야 합니다.
+    - 버전 관리가 필요한 영구 보존용 주요 산출물(최종 설계 계획, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(예: `docs/` 또는 `artifacts/` 등)로 명시적으로 복사하여 기록을 이관 보존해야 합니다.

 ### ⏱️ 타임아웃 구성 및 정렬 규칙
 - **잡 실행 제한 (`timeout_sec` & `idle_timeout_sec`)**: 각 잡은 전체 실행 만료 시간(`timeout_sec`, 기본 3600s)과 메세지 미수신 유휴 시간(`idle_timeout_sec`, 기본 120s)을 독립적으로 가집니다.
@@ -122,8 +122,12 @@ To ensure that agents running in TMUX environments do not lose debug logs or pre
 - **Core Principle**: To prevent TUI character loss, truncation, and layout breakage during sequential input typing, all collaborative workflows must favor file-based markdown communication.
 - **Rules & Protocols**:
  - **Exception**: Extremely simple prompts (e.g., "Re-evaluate", "Check status", "Proceed") of 1 or 2 lines may be sent directly via tmux input buffers.
-  - **Task Delegation**: All detailed task briefs, specifications, and instructions must be written to a local Markdown file (e.g., `.mam/jobs/brief-<job_id>.md` or a workspace path) first. The sender then issues a simple trigger command: `"Read <file_path> and execute."`
-  - **Result Reporting & Feedback**: All detailed review results, design proposals, implementation reports, and audit comments must be saved as Markdown files. Every agent must create a dedicated directory for itself under `.mam/jobs/<agent_name>/` and save its job output/report Markdown files inside this folder (e.g., `.mam/jobs/<agent_name>/report-<job_id>.md`). The recipient reads these files directly from disk instead of relying on truncated terminal screen captures.
+  - **Task Delegation**: All detailed task briefs, specifications, and instructions must be written to a local Markdown file (e.g., `.mam/reports/brief-<job_id>.md` or a workspace path) first. The sender then issues a simple trigger command: `"Read <file_path> and execute."`
+  - **Result Reporting & Feedback**: All detailed review results, design proposals, implementation reports, and audit comments must be saved as Markdown files. To separate human-readable documents from the machine job registry (`.mam/jobs/`), every agent must save its outputs under `.mam/reports/<tmux_session_name>/` (using the full tmux session name matching the `name` field in `.mam/agent-sessions.yaml`, e.g., `.mam/reports/<workspace_slug>-creator-<agent>/report-<job_id>.md`) to ensure strict isolation across multiple roles/instances.
+  - **Cleanup & Retention Contract**:
+    - Files under `.mam/reports/` are audit-trail artifacts.
+    - These folders should be cleaned up automatically during `stop_session.sh` when a session is gracefully stopped or purged (`--purge-conversation`).
+    - Durable outcomes (such as final design plans or security audit reports) that require version control must be explicitly copied to tracked directory paths (e.g., `docs/` or `artifacts/`) instead of remaining in the gitignored `.mam/` runtime tree.

 ### ⏱️ Timeout Configuration & Alignment Rules
 - **Job Execution Limits (`timeout_sec` & `idle_timeout_sec`)**: Each job independently manages its overall execution timeout (`timeout_sec`, default 3600s) and idle timeout without receiving messages (`idle_timeout_sec`, default 120s).
@@ -0,0 +1,105 @@
+# Multi-Agent Collaboration Workflow Reference Guide
+
+본 문서는 대규모 프로젝트나 정밀한 설계·구현 요구사항을 처리하기 위해 **Planner, Developer, Reviewer** 에이전트 간의 역할 분담 및 피드백 루프를 운영하는 **다중 에이전트 협업 워크플로우(Multi-Agent Collaboration Workflow)**를 정의합니다.
+
+---
+
+## 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`를 바탕으로 개별 검증을 수행하고 보고서 형태의 리뷰 피드백을 출력합니다.
+   - **반려 (`NOT PASS`)** -> 피드백 요약본을 Planner 에이전트에게 전송하여 상위 레벨 계획(Rev.n) 개시.
+   - **통과 (`PASS`)** -> 모든 검토 사항이 해결되었음을 명시.
+3. 모든 리뷰어가 PASS를 발행하면 작업을 완결하고 세션을 안전하게 종료(`multi-agent-mux-stop`)합니다.
+
+---
+
+## 3. Best Practices & 템플릿
+
+### 3.1. 작업 시작 시 Planner 에이전트 프롬프트 템플릿
+```
+[역할 요구]
+프로젝트의 구조 및 내용을 파악하고, 현재 작업 요건에 맞춰 구현 계획서(implementation_plan.md) 및 태스크 체크리스트(task.md)를 작성해 주세요. 
+
+[검토 초점]
+- 설계 수준에서 논리적 모순이 발생할 여지가 없는지
+- naive 구현과 대비되는 핵심 차별점이 코드 명세에 정확히 명시되었는지
+```
+
+### 3.2. 피드백 루프 환류 시 프롬프트 템플릿
+```
+Reviewer 검토 결과 구현 코드 차원에서 아래의 블로킹(NOT PASS) 피드백이 발생했습니다.
+위 피드백을 수용하여 설계 문서를 수정하는 계획을 수립하고, implementation_plan.md (Rev.[N]) 및 task.md 내용을 업데이트해 주세요.
+
+[피드백 내용]
+- [블로킹 항목 1]
+- [블로킹 항목 2]
+```