공개 문서
STRUCTURE-DESIGN.md
아래는 learn/canonical/STRUCTURE-DESIGN.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# 구조 설계 — MultiAgentSystem (MULTIAGENT-CURSOR canonical)
**설치 폴더**: `multi-agent-system/` = `<설치한-폴더>` = `MULTIAGENT_ROOT`
> **설계 토대**: 매뉴얼 v2.0 폴더 트리(04장)를 **그대로** 따른다.
> Cursor host는 **워크스페이스 루트** `.cursor/` adapter만 추가한다. `_shared` · `_templates` · `tasks/` 3층은 manual과 동일하다.
**상태**: Phase 112–117 `COMPLETION_100_EXCLUDING_PHASE_D` · baseline [`baseline-realignment-2026-06-10`](https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10)
---
## 0. 워크스페이스 토폴로지
`MULTIAGENT_ROOT`는 **git repo 루트가 아니다**. LAB 저장소 `MultiAgentSystem/` 안의 **cursor 정본 설치본**이다.
```
MultiAgentSystem/ # git repo 루트 (LAB)
├── CLAUDE.md # 워크스페이스 규칙 · canonical immutability
├── multi-agent-starter/ # 플러그인·generator 소스 (templates/claude|codex|antigravity|cursor)
│
├── multi-agent-system/ # ★ MULTIAGENT_ROOT · MULTIAGENT-CURSOR canonical
│ ├── AGENTS.md · _shared/ · _templates/ · tasks/ · runs/ · docs/ …
│ └── (본 문서가 설명하는 트리)
│
├── multi-agent-cursor/ # LAB install (gitignored) — init.py 재생성 OK
├── multi-agent-claude/ # LAB install (gitignored)
├── multi-agent-codex/ # LAB install (gitignored) — legacy `my-system/` 대체
├── multi-agent-antigravity/ # LAB install (gitignored)
│
└── .cursor/ # Cursor host adapter (MULTIAGENT_ROOT **밖**)
├── rules/multi-agent-harness.mdc # globs: multi-agent-system/**
├── skills/ # configure-multiagent, codex, gemini, …
└── mcp.json # codex MCP (cursor host)
```
| 경로 | 역할 | 수정 정책 |
|------|------|-----------|
| `multi-agent-system/` | 운영 정본 · `runs/` · validate 기준 | **기본 수정 금지** — [`AGENTS.md`](./AGENTS.md) § Canonical immutability |
| `multi-agent-{flavor}/` | 4-flavor LAB 설치본 | `init.py --target` 로만 갱신 |
| `multi-agent-starter/.../templates/cursor/` | cursor 금형 | 정본에서 **읽기 전용 복사** ([`run-089`](./runs/run-089-template-sync-lab-reinit/)) |
| `.cursor/` | Cursor 편의 계층 | 워크스페이스 루트에서 관리; 정본 대체 아님 |
4-flavor 명명: [`docs/FOUR-FLAVOR-NAMING.md`](./docs/FOUR-FLAVOR-NAMING.md)
---
## 문서 권위 (충돌 시)
| 순위 | 출처 | 비고 |
|------|------|------|
| 1 | 사용자 직접 지시 | Phase 지시문·확정 결정 |
| 2 | **매뉴얼 PDF v2.0** | **영상·교육 자료와 충돌 시 정본** |
| 3 | `multi-agent-starter` templates | 공식 구현체 |
| 4 | `AGENTS.md` | 운영 규칙 |
| 5 | `_shared/{routing,approval-policy,orchestrator-rules}.md` | |
| 6 | **본 문서** (`STRUCTURE-DESIGN.md`) | 구조·권위 보조 |
| 7 | `VIDEO-MANUAL-ANALYSIS.md` | 영상 요약·갭 참고 (규칙 아님) |
| 8 | YouTube 교육 영상 | 시연·동기 부여용 |
| 9 | `runs/` | historical truth (수정·삭제 금지) |
**확정 원칙**: 영상과 매뉴얼이 다르면 **매뉴얼 PDF**. LAB cursor-ext 해석이 manual과 충돌하면 **manual 우선**.
충돌 해소 시 `tasks/<task>/log.md`에 `[DECISION]`으로 근거·적용 출처를 남긴다.
**문서 빠른 탐색**: [`docs/STRUCTURE-INDEX.md`](./docs/STRUCTURE-INDEX.md)
---
## 전체 폴더 트리 (매뉴얼 04장 + canonical 확장)
### A. 핵심 3층 (매뉴얼 정본 — starter template sync 대상)
```
multi-agent-system/ # MULTIAGENT_ROOT
├── AGENTS.md # 운영 규칙 전문 (claude flavor: CLAUDE.md 대응)
├── README.md # 개요·baseline 링크
├── STRUCTURE-DESIGN.md # 본 문서
├── CHANGELOG.md · KNOWN_ISSUES.md # 변경·알려진 이슈
├── .gitignore # tasks/* · _local/* 기본 미추적
│
├── _shared/ # ── 규칙층 ──
│ ├── routing.md # 워커 선택 decision tree
│ ├── runtime-route-matrix.md # Phase 83+ verified 호출 경로
│ ├── three-worker-roles.md # canonical 역할 · mode 표
│ ├── approval-policy.md
│ ├── orchestrator-rules.md
│ ├── design-basis.md # 시스템 수정 시만 로드
│ ├── system-invariants.md
│ ├── learnings.md # append-only (시스템 일반)
│ ├── legacy-naming-reference.md # 구 worker명 → canonical
│ ├── backends.json # 디스패처 정본
│ ├── worker-alias-map.json # alias → canonical (기계 판독)
│ └── adapters/
│ ├── call_worker.sh # cli/api 디스패처
│ ├── gemini_api.sh # gemini API fallback (optional)
│ └── _run.py
│
├── _templates/ # ── 양식층 ──
│ ├── task.md · context.md · log.md
│ ├── worker-brief.md · worker-result.md
│ └── task-folder.md # 새 tasks/ 생성 가이드
│
├── _local/ # git 미추적 — 작성자 특화 교훈
│ └── .gitkeep
│
└── tasks/ # ── 실행층 ──
└── <task-name>/
├── task.md · context.md · log.md
├── sources/ # (선택) 긴 원본 — 경로 참조만
├── workers/<worker>/ # claude | codex | gemini ★
│ ├── brief.md # mode: implement | critique | analysis
│ └── result.md
└── artifacts/ # (선택)
```
★ `context.md` = **현재 시점 스냅샷**. 히스토리는 `log.md`, 배경·목표는 `task.md`.
**Legacy paths** (읽기 전용): `runs/` 내 `workers/codex-main/`, `worker-briefs/codex-planning/` 등 — 신규 `tasks/`에 사용 금지.
### B. canonical 전용 확장 (starter template sync **제외**)
```
multi-agent-system/
├── docs/ # 운영·UX·릴리스 (LAB 정본만)
│ ├── STRUCTURE-INDEX.md # 문서 맵
│ ├── learn/ # ★ Learning Hub SSOT (바이브코더·초급개발자)
│ │ ├── HUB-AUDIENCE-AND-VOICE.md # 대상·톤 · 금지용어 체크리스트 폐기
│ │ ├── HUB-CONTENT-SPEC.md # 챕터 IA · 사이드바 · diagram
│ │ ├── manual.manifest.json # Hub sync 입력
│ │ └── chapters/ # 매뉴얼 v2 §01–11 정렬 본문
│ ├── operator-runbook.md # E2E 운영자 절차서
│ ├── phase-c-operations-guide.md # legacy→canonical · template sync
│ ├── FOUR-FLAVOR-NAMING.md
│ ├── releases/
│ └── ux/ # routing 다이어그램 · envelope · 복구
│
├── learning-hub-sources/ # Hub import용 요약 Pack (Phase 27)
│ ├── README.md · phase-index.md · topic-map.md
│ ├── source-map.json # provenance ↔ runs/run-00N
│ └── import-readiness-report.md
│
├── runs/ # Phase 10+ 실험 아카이브 (읽기 전용)
│ ├── README.md
│ ├── run-NNN-<slug>/ # 신규 run 폴더 추가 금지 (historical)
│ └── _archive/ # superseded run 이동 ([APPROVAL] 후)
│
├── tasks/ # 참조 task는 `git add -f` 예외 추적 가능
│ ├── manual-core-flow-e2e/ # Phase 106 E2E (추적됨)
│ └── appendix-a-compliance-walkthrough/
│
└── VIDEO-MANUAL-ANALYSIS.md # 영상 요약 (규칙 아님; template sync 제외)
```
### C. repo 루트 참고
| 경로 | 용도 |
|------|------|
| `../references/` | 외부 레퍼런스 (읽기 전용) |
| `../MULTI_AGENT_STARTER_INVESTIGATION.md` | starter 조사 + LAB 정본 요약 |
---
## 3층 역할
| 층 | 폴더 | 역할 |
|----|------|------|
| **규칙** | `_shared/` | 모든 작업 공통. 시스템 수정 시 `design-basis` + `system-invariants` + validate |
| **양식** | `_templates/` | 새 `tasks/<task>/` 생성 시 복사 원본 |
| **실행** | `tasks/<task>/` | 작업 단위. 파일 = 메모리. 세션 끊겨도 재개 가능 |
---
## Orchestrator · Worker · 실행환경
| 개념 | 정의 |
|------|------|
| **Orchestrator** | 현재 host 세션 — task 조정·통합 (worker **아님**). **고정되지 않음** |
| **Worker (canonical)** | `claude` · `codex` · `gemini` — 별도 모델 호출, 승인 필요 |
| **mode** | brief: `implement` \| `critique` \| `analysis`(gemini) |
| **orchestrator_host** | `cursor` \| `claude-code` \| `codex` \| `antigravity` — task/envelope 기록 |
| **Cursor adapter** | repo 루트 `.cursor/` — rules · skills · mcp |
### flavor vs 본 워크스페이스
| flavor | Orchestrator host | LAB 폴더 |
|--------|-------------------|----------|
| cursor | Cursor Agent | `multi-agent-cursor/` (+ **정본** `multi-agent-system/`) |
| claude | Claude Code | `multi-agent-claude/` |
| codex | Codex | `multi-agent-codex/` |
| antigravity | agy / Gemini IDE | `multi-agent-antigravity/` |
cursor-ext ≠ claude flavor. 동일 worker pool을 **다른 orchestrator host**에서 재사용한다.
### Cursor adapter (워크스페이스 루트 — MULTIAGENT_ROOT 밖)
| 파일 | 역할 |
|------|------|
| `.cursor/rules/multi-agent-harness.mdc` | glob `multi-agent-system/**` · immutability · lifecycle |
| `.cursor/skills/configure-multiagent/` | `init.py` 진입 (LAB 4종만 target) |
| `.cursor/skills/codex/` · `gemini/` · `claude/` | canonical worker 스킬 |
| `.cursor/skills/codex-main/` · `codex-critic/` | **LEGACY compat** 배너만 — 신규 task 금지 |
| `.cursor/mcp.json` | codex MCP |
---
## Worker pool (canonical)
`<worker>` ∈ { `claude`, `codex`, `gemini` }
**금지 (신규 task)**: `codex-main`, `codex-critic`, `claude-main`, `claude-implementation`, `codex-planning`, `gemini-vision`, `cursor-critic`
**Legacy**: `runs/`·구 envelope·`call_worker.sh` alias compat — [`legacy-naming-reference.md`](./_shared/legacy-naming-reference.md) · [`worker-alias-map.json`](./_shared/worker-alias-map.json)
### Verified routes (cursor host · Phase 85)
```text
claude = call_worker.sh claude (Cursor agent shell OK)
codex = MCP primary / CLI fallback (Orchestrator direct)
gemini = Mac Terminal + agy primary (agent shell에서 call_worker.sh gemini 직접 호출 금지)
```
상세: [`_shared/runtime-route-matrix.md`](./_shared/runtime-route-matrix.md)
---
## Git 추적 정책
| 경로 | 기본 | 예외 |
|------|------|------|
| `_shared/`, `_templates/`, 루트 메타 6종 | 추적 | template sync 소스 |
| `tasks/*` | **미추적** (`.gitignore`) | 참조·E2E task: `git add -f` ([`run-086`](./runs/run-086-phase112-117-completion/)) |
| `_local/*` | 미추적 | `.gitkeep`만 |
| `runs/` | 추적 | 수정·삭제 금지; `_archive/` 이동만 [APPROVAL] |
| `docs/` | 추적 | starter template sync 제외 |
| `learning-hub-sources/` | **repo `.gitignore` 미추적** (Phase 67 hold) | Hub import Phase에서 `git add -f` 또는 ignore 해제 후 추적 |
| `VIDEO-MANUAL-ANALYSIS.md` | 추적 | starter template sync 제외 |
---
## Template sync 경계 (canonical → starter)
[`docs/phase-c-operations-guide.md`](./docs/phase-c-operations-guide.md) §5 · [`run-089`](./runs/run-089-template-sync-lab-reinit/)
| **복사됨** | **제외** |
|------------|----------|
| `AGENTS.md`, `README.md`, `STRUCTURE-DESIGN.md`, `KNOWN_ISSUES.md`, `CHANGELOG.md`, `.gitignore` | `runs/`, `docs/`, `tasks/`, `learning-hub-sources/` |
| `_shared/**`, `_templates/**` | `VIDEO-MANUAL-ANALYSIS.md` |
`init.py --target multi-agent-system` **금지**.
---
## learning-hub-sources
Learning Hub로 가져갈 **읽기 전용 요약 Pack** (run-001~017 → topic 7종).
| 파일 | 용도 |
|------|------|
| [`learning-hub-sources/README.md`](./learning-hub-sources/README.md) | Pack 시작점 |
| `phase-index.md` | Phase 10→26 타임라인 |
| `topic-map.md` | 학습 주제별 재분류 |
| `source-map.json` | Hub import 스크립트 입력 |
| `import-readiness-report.md` | GO/NO-GO · 민감정보 |
- 원본 `runs/`는 **덮어쓰지 않음**
- live Slack/Hermes API 없이 **문서 import만**
- **Hub 학습 본문 SSOT**: [`docs/learn/`](./docs/learn/) — 대상 **바이브코더·초급 개발자**, 매뉴얼 v2 밀도 · 기술 용어 적극 사용 ([`HUB-AUDIENCE-AND-VOICE.md`](./docs/learn/HUB-AUDIENCE-AND-VOICE.md))
---
## 구조 정합성 체크리스트
새 Phase·문서 변경 후 빠른 자가 점검:
- [ ] `_shared/backends.json` ↔ `runtime-route-matrix.md` ↔ `.cursor/mcp.json` 호출 경로 일치
- [ ] 신규 `tasks/` worker 폴더명이 canonical 3종만 사용
- [ ] `STRUCTURE-DESIGN.md` 트리와 실제 디렉터리 drift 없음
- [ ] starter `templates/cursor/` sync 시 **제외 목록** 준수
- [ ] canonical 편집 시 `[APPROVAL] canonical multi-agent-system edit` 기록
- [ ] `learning-hub-sources/source-map.json`이 참조하는 run 경로 존재
검증: `bash multi-agent-starter/tests/run.sh` · `validate.py` (flavor별)
---
## 새 작업 시작 (요약)
1. [`_templates/task-folder.md`](./_templates/task-folder.md) 가이드 따름
2. `tasks/<task-name>/`에 `task.md` · `context.md` · `log.md` 생성
3. [`_shared/routing.md`](./_shared/routing.md)로 최소 worker set 결정 → 승인 → brief → 호출 → result → `[VERIFICATION]`
자세한 운영: [`AGENTS.md`](./AGENTS.md) · E2E: [`docs/operator-runbook.md`](./docs/operator-runbook.md)
공개 문서 변환 코드 (HTML)
<h1>구조 설계 — MultiAgentSystem (MULTIAGENT-CURSOR canonical)</h1>
<p><strong>설치 폴더</strong>: <code>multi-agent-system/</code> = <code><설치한-폴더></code> = <code>MULTIAGENT_ROOT</code></p>
<blockquote>
<p><strong>설계 토대</strong>: 매뉴얼 v2.0 폴더 트리(04장)를 <strong>그대로</strong> 따른다.<br>Cursor host는 <strong>워크스페이스 루트</strong> <code>.cursor/</code> adapter만 추가한다. <code>_shared</code> · <code>_templates</code> · <code>tasks/</code> 3층은 manual과 동일하다.</p>
</blockquote>
<p><strong>상태</strong>: Phase 112–117 <code>COMPLETION_100_EXCLUDING_PHASE_D</code> · baseline <a href="https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10"><code>baseline-realignment-2026-06-10</code></a></p>
<hr>
<h2>0. 워크스페이스 토폴로지</h2>
<p><code>MULTIAGENT_ROOT</code>는 <strong>git repo 루트가 아니다</strong>. LAB 저장소 <code>MultiAgentSystem/</code> 안의 <strong>cursor 정본 설치본</strong>이다.</p>
<pre><code>MultiAgentSystem/ # git repo 루트 (LAB)
├── CLAUDE.md # 워크스페이스 규칙 · canonical immutability
├── multi-agent-starter/ # 플러그인·generator 소스 (templates/claude|codex|antigravity|cursor)
│
├── multi-agent-system/ # ★ MULTIAGENT_ROOT · MULTIAGENT-CURSOR canonical
│ ├── AGENTS.md · _shared/ · _templates/ · tasks/ · runs/ · docs/ …
│ └── (본 문서가 설명하는 트리)
│
├── multi-agent-cursor/ # LAB install (gitignored) — init.py 재생성 OK
├── multi-agent-claude/ # LAB install (gitignored)
├── multi-agent-codex/ # LAB install (gitignored) — legacy `my-system/` 대체
├── multi-agent-antigravity/ # LAB install (gitignored)
│
└── .cursor/ # Cursor host adapter (MULTIAGENT_ROOT **밖**)
├── rules/multi-agent-harness.mdc # globs: multi-agent-system/**
├── skills/ # configure-multiagent, codex, gemini, …
└── mcp.json # codex MCP (cursor host)
</code></pre>
<table>
<thead>
<tr>
<th>경로</th>
<th>역할</th>
<th>수정 정책</th>
</tr>
</thead>
<tbody><tr>
<td><code>multi-agent-system/</code></td>
<td>운영 정본 · <code>runs/</code> · validate 기준</td>
<td><strong>기본 수정 금지</strong> — <a href="./AGENTS.md"><code>AGENTS.md</code></a> § Canonical immutability</td>
</tr>
<tr>
<td><code>multi-agent-{flavor}/</code></td>
<td>4-flavor LAB 설치본</td>
<td><code>init.py --target</code> 로만 갱신</td>
</tr>
<tr>
<td><code>multi-agent-starter/.../templates/cursor/</code></td>
<td>cursor 금형</td>
<td>정본에서 <strong>읽기 전용 복사</strong> (<a href="./runs/run-089-template-sync-lab-reinit/"><code>run-089</code></a>)</td>
</tr>
<tr>
<td><code>.cursor/</code></td>
<td>Cursor 편의 계층</td>
<td>워크스페이스 루트에서 관리; 정본 대체 아님</td>
</tr>
</tbody></table>
<p>4-flavor 명명: <a href="./docs/FOUR-FLAVOR-NAMING.md"><code>docs/FOUR-FLAVOR-NAMING.md</code></a></p>
<hr>
<h2>문서 권위 (충돌 시)</h2>
<table>
<thead>
<tr>
<th>순위</th>
<th>출처</th>
<th>비고</th>
</tr>
</thead>
<tbody><tr>
<td>1</td>
<td>사용자 직접 지시</td>
<td>Phase 지시문·확정 결정</td>
</tr>
<tr>
<td>2</td>
<td><strong>매뉴얼 PDF v2.0</strong></td>
<td><strong>영상·교육 자료와 충돌 시 정본</strong></td>
</tr>
<tr>
<td>3</td>
<td><code>multi-agent-starter</code> templates</td>
<td>공식 구현체</td>
</tr>
<tr>
<td>4</td>
<td><code>AGENTS.md</code></td>
<td>운영 규칙</td>
</tr>
<tr>
<td>5</td>
<td><code>_shared/{routing,approval-policy,orchestrator-rules}.md</code></td>
<td></td>
</tr>
<tr>
<td>6</td>
<td><strong>본 문서</strong> (<code>STRUCTURE-DESIGN.md</code>)</td>
<td>구조·권위 보조</td>
</tr>
<tr>
<td>7</td>
<td><code>VIDEO-MANUAL-ANALYSIS.md</code></td>
<td>영상 요약·갭 참고 (규칙 아님)</td>
</tr>
<tr>
<td>8</td>
<td>YouTube 교육 영상</td>
<td>시연·동기 부여용</td>
</tr>
<tr>
<td>9</td>
<td><code>runs/</code></td>
<td>historical truth (수정·삭제 금지)</td>
</tr>
</tbody></table>
<p><strong>확정 원칙</strong>: 영상과 매뉴얼이 다르면 <strong>매뉴얼 PDF</strong>. LAB cursor-ext 해석이 manual과 충돌하면 <strong>manual 우선</strong>.</p>
<p>충돌 해소 시 <code>tasks/<task>/log.md</code>에 <code>[DECISION]</code>으로 근거·적용 출처를 남긴다.</p>
<p><strong>문서 빠른 탐색</strong>: <a href="./docs/STRUCTURE-INDEX.md"><code>docs/STRUCTURE-INDEX.md</code></a></p>
<hr>
<h2>전체 폴더 트리 (매뉴얼 04장 + canonical 확장)</h2>
<h3>A. 핵심 3층 (매뉴얼 정본 — starter template sync 대상)</h3>
<pre><code>multi-agent-system/ # MULTIAGENT_ROOT
├── AGENTS.md # 운영 규칙 전문 (claude flavor: CLAUDE.md 대응)
├── README.md # 개요·baseline 링크
├── STRUCTURE-DESIGN.md # 본 문서
├── CHANGELOG.md · KNOWN_ISSUES.md # 변경·알려진 이슈
├── .gitignore # tasks/* · _local/* 기본 미추적
│
├── _shared/ # ── 규칙층 ──
│ ├── routing.md # 워커 선택 decision tree
│ ├── runtime-route-matrix.md # Phase 83+ verified 호출 경로
│ ├── three-worker-roles.md # canonical 역할 · mode 표
│ ├── approval-policy.md
│ ├── orchestrator-rules.md
│ ├── design-basis.md # 시스템 수정 시만 로드
│ ├── system-invariants.md
│ ├── learnings.md # append-only (시스템 일반)
│ ├── legacy-naming-reference.md # 구 worker명 → canonical
│ ├── backends.json # 디스패처 정본
│ ├── worker-alias-map.json # alias → canonical (기계 판독)
│ └── adapters/
│ ├── call_worker.sh # cli/api 디스패처
│ ├── gemini_api.sh # gemini API fallback (optional)
│ └── _run.py
│
├── _templates/ # ── 양식층 ──
│ ├── task.md · context.md · log.md
│ ├── worker-brief.md · worker-result.md
│ └── task-folder.md # 새 tasks/ 생성 가이드
│
├── _local/ # git 미추적 — 작성자 특화 교훈
│ └── .gitkeep
│
└── tasks/ # ── 실행층 ──
└── <task-name>/
├── task.md · context.md · log.md
├── sources/ # (선택) 긴 원본 — 경로 참조만
├── workers/<worker>/ # claude | codex | gemini ★
│ ├── brief.md # mode: implement | critique | analysis
│ └── result.md
└── artifacts/ # (선택)
</code></pre>
<p>★ <code>context.md</code> = <strong>현재 시점 스냅샷</strong>. 히스토리는 <code>log.md</code>, 배경·목표는 <code>task.md</code>.</p>
<p><strong>Legacy paths</strong> (읽기 전용): <code>runs/</code> 내 <code>workers/codex-main/</code>, <code>worker-briefs/codex-planning/</code> 등 — 신규 <code>tasks/</code>에 사용 금지.</p>
<h3>B. canonical 전용 확장 (starter template sync <strong>제외</strong>)</h3>
<pre><code>multi-agent-system/
├── docs/ # 운영·UX·릴리스 (LAB 정본만)
│ ├── STRUCTURE-INDEX.md # 문서 맵
│ ├── learn/ # ★ Learning Hub SSOT (바이브코더·초급개발자)
│ │ ├── HUB-AUDIENCE-AND-VOICE.md # 대상·톤 · 금지용어 체크리스트 폐기
│ │ ├── HUB-CONTENT-SPEC.md # 챕터 IA · 사이드바 · diagram
│ │ ├── manual.manifest.json # Hub sync 입력
│ │ └── chapters/ # 매뉴얼 v2 §01–11 정렬 본문
│ ├── operator-runbook.md # E2E 운영자 절차서
│ ├── phase-c-operations-guide.md # legacy→canonical · template sync
│ ├── FOUR-FLAVOR-NAMING.md
│ ├── releases/
│ └── ux/ # routing 다이어그램 · envelope · 복구
│
├── learning-hub-sources/ # Hub import용 요약 Pack (Phase 27)
│ ├── README.md · phase-index.md · topic-map.md
│ ├── source-map.json # provenance ↔ runs/run-00N
│ └── import-readiness-report.md
│
├── runs/ # Phase 10+ 실험 아카이브 (읽기 전용)
│ ├── README.md
│ ├── run-NNN-<slug>/ # 신규 run 폴더 추가 금지 (historical)
│ └── _archive/ # superseded run 이동 ([APPROVAL] 후)
│
├── tasks/ # 참조 task는 `git add -f` 예외 추적 가능
│ ├── manual-core-flow-e2e/ # Phase 106 E2E (추적됨)
│ └── appendix-a-compliance-walkthrough/
│
└── VIDEO-MANUAL-ANALYSIS.md # 영상 요약 (규칙 아님; template sync 제외)
</code></pre>
<h3>C. repo 루트 참고</h3>
<table>
<thead>
<tr>
<th>경로</th>
<th>용도</th>
</tr>
</thead>
<tbody><tr>
<td><code>../references/</code></td>
<td>외부 레퍼런스 (읽기 전용)</td>
</tr>
<tr>
<td><code>../MULTI_AGENT_STARTER_INVESTIGATION.md</code></td>
<td>starter 조사 + LAB 정본 요약</td>
</tr>
</tbody></table>
<hr>
<h2>3층 역할</h2>
<table>
<thead>
<tr>
<th>층</th>
<th>폴더</th>
<th>역할</th>
</tr>
</thead>
<tbody><tr>
<td><strong>규칙</strong></td>
<td><code>_shared/</code></td>
<td>모든 작업 공통. 시스템 수정 시 <code>design-basis</code> + <code>system-invariants</code> + validate</td>
</tr>
<tr>
<td><strong>양식</strong></td>
<td><code>_templates/</code></td>
<td>새 <code>tasks/<task>/</code> 생성 시 복사 원본</td>
</tr>
<tr>
<td><strong>실행</strong></td>
<td><code>tasks/<task>/</code></td>
<td>작업 단위. 파일 = 메모리. 세션 끊겨도 재개 가능</td>
</tr>
</tbody></table>
<hr>
<h2>Orchestrator · Worker · 실행환경</h2>
<table>
<thead>
<tr>
<th>개념</th>
<th>정의</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Orchestrator</strong></td>
<td>현재 host 세션 — task 조정·통합 (worker <strong>아님</strong>). <strong>고정되지 않음</strong></td>
</tr>
<tr>
<td><strong>Worker (canonical)</strong></td>
<td><code>claude</code> · <code>codex</code> · <code>gemini</code> — 별도 모델 호출, 승인 필요</td>
</tr>
<tr>
<td><strong>mode</strong></td>
<td>brief: <code>implement</code> | <code>critique</code> | <code>analysis</code>(gemini)</td>
</tr>
<tr>
<td><strong>orchestrator_host</strong></td>
<td><code>cursor</code> | <code>claude-code</code> | <code>codex</code> | <code>antigravity</code> — task/envelope 기록</td>
</tr>
<tr>
<td><strong>Cursor adapter</strong></td>
<td>repo 루트 <code>.cursor/</code> — rules · skills · mcp</td>
</tr>
</tbody></table>
<h3>flavor vs 본 워크스페이스</h3>
<table>
<thead>
<tr>
<th>flavor</th>
<th>Orchestrator host</th>
<th>LAB 폴더</th>
</tr>
</thead>
<tbody><tr>
<td>cursor</td>
<td>Cursor Agent</td>
<td><code>multi-agent-cursor/</code> (+ <strong>정본</strong> <code>multi-agent-system/</code>)</td>
</tr>
<tr>
<td>claude</td>
<td>Claude Code</td>
<td><code>multi-agent-claude/</code></td>
</tr>
<tr>
<td>codex</td>
<td>Codex</td>
<td><code>multi-agent-codex/</code></td>
</tr>
<tr>
<td>antigravity</td>
<td>agy / Gemini IDE</td>
<td><code>multi-agent-antigravity/</code></td>
</tr>
</tbody></table>
<p>cursor-ext ≠ claude flavor. 동일 worker pool을 <strong>다른 orchestrator host</strong>에서 재사용한다.</p>
<h3>Cursor adapter (워크스페이스 루트 — MULTIAGENT_ROOT 밖)</h3>
<table>
<thead>
<tr>
<th>파일</th>
<th>역할</th>
</tr>
</thead>
<tbody><tr>
<td><code>.cursor/rules/multi-agent-harness.mdc</code></td>
<td>glob <code>multi-agent-system/**</code> · immutability · lifecycle</td>
</tr>
<tr>
<td><code>.cursor/skills/configure-multiagent/</code></td>
<td><code>init.py</code> 진입 (LAB 4종만 target)</td>
</tr>
<tr>
<td><code>.cursor/skills/codex/</code> · <code>gemini/</code> · <code>claude/</code></td>
<td>canonical worker 스킬</td>
</tr>
<tr>
<td><code>.cursor/skills/codex-main/</code> · <code>codex-critic/</code></td>
<td><strong>LEGACY compat</strong> 배너만 — 신규 task 금지</td>
</tr>
<tr>
<td><code>.cursor/mcp.json</code></td>
<td>codex MCP</td>
</tr>
</tbody></table>
<hr>
<h2>Worker pool (canonical)</h2>
<p><code><worker></code> ∈ { <code>claude</code>, <code>codex</code>, <code>gemini</code> }</p>
<p><strong>금지 (신규 task)</strong>: <code>codex-main</code>, <code>codex-critic</code>, <code>claude-main</code>, <code>claude-implementation</code>, <code>codex-planning</code>, <code>gemini-vision</code>, <code>cursor-critic</code></p>
<p><strong>Legacy</strong>: <code>runs/</code>·구 envelope·<code>call_worker.sh</code> alias compat — <a href="./_shared/legacy-naming-reference.md"><code>legacy-naming-reference.md</code></a> · <a href="./_shared/worker-alias-map.json"><code>worker-alias-map.json</code></a></p>
<h3>Verified routes (cursor host · Phase 85)</h3>
<pre><code class="language-text">claude = call_worker.sh claude (Cursor agent shell OK)
codex = MCP primary / CLI fallback (Orchestrator direct)
gemini = Mac Terminal + agy primary (agent shell에서 call_worker.sh gemini 직접 호출 금지)
</code></pre>
<p>상세: <a href="./_shared/runtime-route-matrix.md"><code>_shared/runtime-route-matrix.md</code></a></p>
<hr>
<h2>Git 추적 정책</h2>
<table>
<thead>
<tr>
<th>경로</th>
<th>기본</th>
<th>예외</th>
</tr>
</thead>
<tbody><tr>
<td><code>_shared/</code>, <code>_templates/</code>, 루트 메타 6종</td>
<td>추적</td>
<td>template sync 소스</td>
</tr>
<tr>
<td><code>tasks/*</code></td>
<td><strong>미추적</strong> (<code>.gitignore</code>)</td>
<td>참조·E2E task: <code>git add -f</code> (<a href="./runs/run-086-phase112-117-completion/"><code>run-086</code></a>)</td>
</tr>
<tr>
<td><code>_local/*</code></td>
<td>미추적</td>
<td><code>.gitkeep</code>만</td>
</tr>
<tr>
<td><code>runs/</code></td>
<td>추적</td>
<td>수정·삭제 금지; <code>_archive/</code> 이동만 [APPROVAL]</td>
</tr>
<tr>
<td><code>docs/</code></td>
<td>추적</td>
<td>starter template sync 제외</td>
</tr>
<tr>
<td><code>learning-hub-sources/</code></td>
<td><strong>repo <code>.gitignore</code> 미추적</strong> (Phase 67 hold)</td>
<td>Hub import Phase에서 <code>git add -f</code> 또는 ignore 해제 후 추적</td>
</tr>
<tr>
<td><code>VIDEO-MANUAL-ANALYSIS.md</code></td>
<td>추적</td>
<td>starter template sync 제외</td>
</tr>
</tbody></table>
<hr>
<h2>Template sync 경계 (canonical → starter)</h2>
<p><a href="./docs/phase-c-operations-guide.md"><code>docs/phase-c-operations-guide.md</code></a> §5 · <a href="./runs/run-089-template-sync-lab-reinit/"><code>run-089</code></a></p>
<table>
<thead>
<tr>
<th><strong>복사됨</strong></th>
<th><strong>제외</strong></th>
</tr>
</thead>
<tbody><tr>
<td><code>AGENTS.md</code>, <code>README.md</code>, <code>STRUCTURE-DESIGN.md</code>, <code>KNOWN_ISSUES.md</code>, <code>CHANGELOG.md</code>, <code>.gitignore</code></td>
<td><code>runs/</code>, <code>docs/</code>, <code>tasks/</code>, <code>learning-hub-sources/</code></td>
</tr>
<tr>
<td><code>_shared/**</code>, <code>_templates/**</code></td>
<td><code>VIDEO-MANUAL-ANALYSIS.md</code></td>
</tr>
</tbody></table>
<p><code>init.py --target multi-agent-system</code> <strong>금지</strong>.</p>
<hr>
<h2>learning-hub-sources</h2>
<p>Learning Hub로 가져갈 <strong>읽기 전용 요약 Pack</strong> (run-001~017 → topic 7종).</p>
<table>
<thead>
<tr>
<th>파일</th>
<th>용도</th>
</tr>
</thead>
<tbody><tr>
<td><a href="./learning-hub-sources/README.md"><code>learning-hub-sources/README.md</code></a></td>
<td>Pack 시작점</td>
</tr>
<tr>
<td><code>phase-index.md</code></td>
<td>Phase 10→26 타임라인</td>
</tr>
<tr>
<td><code>topic-map.md</code></td>
<td>학습 주제별 재분류</td>
</tr>
<tr>
<td><code>source-map.json</code></td>
<td>Hub import 스크립트 입력</td>
</tr>
<tr>
<td><code>import-readiness-report.md</code></td>
<td>GO/NO-GO · 민감정보</td>
</tr>
</tbody></table>
<ul>
<li>원본 <code>runs/</code>는 <strong>덮어쓰지 않음</strong></li>
<li>live Slack/Hermes API 없이 <strong>문서 import만</strong></li>
<li><strong>Hub 학습 본문 SSOT</strong>: <a href="./docs/learn/"><code>docs/learn/</code></a> — 대상 <strong>바이브코더·초급 개발자</strong>, 매뉴얼 v2 밀도 · 기술 용어 적극 사용 (<a href="./docs/learn/HUB-AUDIENCE-AND-VOICE.md"><code>HUB-AUDIENCE-AND-VOICE.md</code></a>)</li>
</ul>
<hr>
<h2>구조 정합성 체크리스트</h2>
<p>새 Phase·문서 변경 후 빠른 자가 점검:</p>
<ul>
<li><input disabled="" type="checkbox"> <code>_shared/backends.json</code> ↔ <code>runtime-route-matrix.md</code> ↔ <code>.cursor/mcp.json</code> 호출 경로 일치</li>
<li><input disabled="" type="checkbox"> 신규 <code>tasks/</code> worker 폴더명이 canonical 3종만 사용</li>
<li><input disabled="" type="checkbox"> <code>STRUCTURE-DESIGN.md</code> 트리와 실제 디렉터리 drift 없음</li>
<li><input disabled="" type="checkbox"> starter <code>templates/cursor/</code> sync 시 <strong>제외 목록</strong> 준수</li>
<li><input disabled="" type="checkbox"> canonical 편집 시 <code>[APPROVAL] canonical multi-agent-system edit</code> 기록</li>
<li><input disabled="" type="checkbox"> <code>learning-hub-sources/source-map.json</code>이 참조하는 run 경로 존재</li>
</ul>
<p>검증: <code>bash multi-agent-starter/tests/run.sh</code> · <code>validate.py</code> (flavor별)</p>
<hr>
<h2>새 작업 시작 (요약)</h2>
<ol>
<li><a href="./_templates/task-folder.md"><code>_templates/task-folder.md</code></a> 가이드 따름 </li>
<li><code>tasks/<task-name>/</code>에 <code>task.md</code> · <code>context.md</code> · <code>log.md</code> 생성 </li>
<li><a href="./_shared/routing.md"><code>_shared/routing.md</code></a>로 최소 worker set 결정 → 승인 → brief → 호출 → result → <code>[VERIFICATION]</code></li>
</ol>
<p>자세한 운영: <a href="./AGENTS.md"><code>AGENTS.md</code></a> · E2E: <a href="./docs/operator-runbook.md"><code>docs/operator-runbook.md</code></a></p>