# 설계: Fan-out 협업 모델 + 설계→구현 handoff + 2단 보고(YAML/MD)

- 상태: Approved (사용자 승인 2026-07-07)
- 대상 저장소: company-haness (Org OS 하네스)
- 관련 원칙: org-os가 SoT · 다양성은 11 렌즈 · evidence 접지 · guard_tools/validate_report 불변식 유지

## 1. 문제 (왜)

62개 역할을 26개 capability-family로 collapse해 효율은 얻었지만, **한 family가 2~7개 역할을 하나의 subagent·하나의 보고서로 통합**한다. 결과:

- 같은 family 안 역할들의 **개별 depth가 희석**되고, 여러 역할이 한 context를 공유해 **context 오염**이 생긴다. (예: FAM-UX-RESEARCH = 정성 리서처 + 정량 분석가가 한 context에 섞임)
- 상위 직무자가 **요약만 받아** 관점이 유실될 수 있다.
- **설계→구현 협업 구조가 부재**하다: PM/PO/아키텍트가 도메인 설계를 하고 구현자가 그 설계로 개발하는 handoff, 그리고 GTM↔Product↔Build 그룹 간 협업 엣지가 명시되어 있지 않다.
- 산출물이 `.report.yaml`(기계용)만 있어 **대표(사용자)가 읽기 좋은 형태**가 없다.

## 2. 원칙 (사용자 확정)

> **코드·실행 산출물을 만드는 family만 collapse(효율). 판단·설계·분석·수익 산출물을 만드는 family는 fan-out(각자 독립 보고서).**
>
> 설계는 하나로 억지 병합하지 않는다. 하위가 조금씩 다른 설계를 내도 **상위 직무자가 원본 보고서를 전부 읽고 최종 결정 문서**를 남긴다(재적재 비효율 감수 — 대표가 직접 확인해야 하므로).

캐스케이드:
```
① 결정(fan-out → CEO 종합)
   → ② 설계(fan-out → 큰 설계문서)
     → ③ 세부 구현문서
       → ④ 구현(collapse family)
```

## 3. 컴포넌트

### 3.1 family 분류 — `collaboration-default`

`capability-families.yaml`의 각 family에 필드 추가: `collaboration-default: fan-out | collapse`. 라우팅 단위는 여전히 family. 이 값은 **기본값**이며 tier/mode가 오버라이드한다.

| collaboration-default | family | 멤버수 | 멤버별 subagent 분리? |
|---|---|---|---|
| **fan-out(의사결정)** | FAM-CEO, FAM-CTO, FAM-CPO, FAM-CFO, FAM-COO, FAM-CPTO, FAM-VPENG | 각 1 | 이미 개별. CEO/parent가 종합 |
| **fan-out(설계·분석)** | FAM-PRODUCT-MGMT(4), FAM-UX-RESEARCH(2), FAM-DESIGN(3), FAM-ARCHITECTURE-TECH(7), FAM-ARCHITECTURE-BIZ(2), FAM-SECURITY(3), FAM-DATA(3), FAM-STRATEGY(1) | 1~7 | 멤버≥2면 ✅ 분리 |
| **fan-out(GTM·수익)** | FAM-REVOPS(2), FAM-GTM-GROWTH(4), FAM-GTM-SALES(3), FAM-LEGAL(1) | 1~4 | 멤버≥2면 ✅ 분리 |
| **collapse(구현·실행)** | FAM-ENG-FRONTEND(3), FAM-ENG-BACKEND(6), FAM-ENG-SPECIAL(2), FAM-PLATFORM-INFRA(5), FAM-OPS-DELIVERY(2), FAM-QA(1) | 1~6 | ❌ family 1보고서 |
| **n/a(조율)** | FAM-ORCH | 1 | 조율자, 산출 결정 아님 |

- 합계: fan-out 19(=7 exec + 8 design + 4 gtm) · collapse 6 · orch 1 = 26.
- **실제 멤버 분리가 일어나는 fan-out family(멤버≥2)는 10개**: PRODUCT-MGMT, UX-RESEARCH, DESIGN, ARCHITECTURE-TECH, ARCHITECTURE-BIZ, SECURITY, DATA, REVOPS, GTM-GROWTH, GTM-SALES.
- 단일 멤버 fan-out(STRATEGY·LEGAL·7 executives)은 이미 1 에이전트라 내부 분리 없이 **독립 보고서 유지 + 상위 종합**만 적용.
- **오버라이드 규칙**(execution-policy에 명시):
  - tier=heavy → collapse family도 적대적 검증 위해 강제 fan-out 허용.
  - mode=converge & tier=light → fan-out family도 단일 종합만(멤버 분리 생략) 허용.
  - context-package에 `fan-out-roles: [...]` 명시 시 그 역할만 분리.

### 3.2 fan-out 실행 + 원본 보고서 재적재

```
family lead (호출자)
 ├─ 멤버역할 A subagent → 격리 context(자기 관점·근거만) → A.report.yaml → 반환: 경로 + 1줄 BLUF
 ├─ 멤버역할 B subagent → 격리 context               → B.report.yaml → 반환: 경로 + 1줄 BLUF   [병렬]
 └─ lead / 상위 직무자: A·B 보고서 파일을 ▶전부 Read◀ → 종합/최종결정 report.yaml
        (합의 vs 충돌 보존, 요약으로 축소 금지, dissent 삭제 금지)
```

- **반환값 계약**: fan-out 하위 subagent의 최종 메시지 = `report-path` + 1줄 bottom-line. (Claude Code subagent는 파일 + 최종 메시지로만 소통하므로, parent가 경로를 받아 직접 Read.)
- **rehydration override**: 결정/종합 지점은 `rehydration-at-synthesis: read-full-subreports`. 기존 `re-hydration-control`(요약만 전달)을 이 지점에서 오버라이드.
  - 단, **raw 로그·툴 트레이스·secrets·PII는 여전히 배제**(forbidden-context 유지). 보고서(.report.yaml)는 구조화 산출물이므로 "raw log 금지"에 해당하지 않는다.
- 종합 산출물은 collaboration-modes의 converge 규칙(트레이드오프·dissent 보존)과 ExecutiveDecisionPacket 규칙(합의/충돌/근거품질/권고)을 그대로 따른다.

### 3.3 설계→구현 handoff + 그룹 간 협업 엣지 — `collaboration-map.yaml`(신설)

`org-os/06-agent-work/collaboration-map.yaml`. 플로우차트를 기계가 읽는 계약으로 인코딩.

- **cascade-phases**: DECIDE → DESIGN → DETAIL → BUILD. 각 phase의 담당 family class와 산출물 타입, 다음 phase로의 입력 계약.
- **design-to-build-contract**: 설계 family 산출물(PRD, RFC/ADR, data-model, api-contract, threat-model)은 대응 build family의 **must-read 선행조건**. 설계 승인 전 구현 시작 금지(state-transition과 정합).
- **cross-group-edges**(양방향, 플로우차트 그대로):
  | from | to | 교환물 |
  |---|---|---|
  | FAM-GTM-GROWTH(Demand) | FAM-PRODUCT-MGMT(Product) | ICP·포지셔닝·캠페인 ↔ 제품가치·로드맵·출시맥락 |
  | FAM-REVOPS/GTM-GROWTH(Conversion) | FAM-ENG-*(Build) | 온보딩·PQL·전환실험 ↔ 제품사용이벤트·한도·계측 |
  | FAM-GTM-SALES(Expansion) | FAM-PRODUCT-MGMT | 이탈위험·기능채택 ↔ 개선계획·릴리스노트 |
  | FAM-REVOPS(RevenueIntel) | FAM-STRATEGY | Forecast·LeadScore·PipelineHealth ↔ 시장·비용·가정 |
  | FAM-GTM-SALES(SalesMotion) | FAM-PRODUCT-MGMT | 고객요구·딜장애물·데모피드백 ↔ 가치제안·기능범위·FAQ |
  | FAM-LEGAL/REVOPS(RevenueRisk) | FAM-GTM-SALES | 가격·계약·컴플라이언스 제약 ↔ 할인·MSA·보안요구 |
- 각 엣지는 `handoff-artifact`(교환 문서 타입)와 방향을 갖는다. team-topology-map의 revenue-stack-layers/EA-layers와 cross-reference.

### 3.4 2단 보고 — YAML(SoT) → `render_report.py` → MD(대표용)

- **단일 원천**: 에이전트는 `.report.yaml`만 쓴다(validate_report/stop_validate가 검증). MD는 여기서 **결정적으로 렌더**(손으로 안 씀) → drift 없음.
- **`.claude/hooks/render_report.py`(신설)**:
  - 입력: 하나의 `.report.yaml`(또는 디렉터리). 옵션: fan-out 멤버 보고서 목록을 받아 "역할별 핵심결론 표"로 집계.
  - 출력: 같은 basename `.md` + `org-os/06-agent-work/reports/INDEX.md`(목차 자동생성).
  - template id(report-templates.yaml) → MD 레이아웃 매핑.
- **대표용 MD 템플릿**(가독성 우선):
  ```markdown
  # 🟢 [결정] <title>
  > **결론** — <bottom-line>
  > **결정 필요** — ✅ 예 · 승인자 `HUMAN-001`   (또는 — 아니오)
  > **확신도** — Med (E3 근거)

  `repo: company-haness` · `<YYYY-MM-DD HH:MM>` · `<workflow-id>`

  ## 🎯 결정해야 할 질문
  ## ✅ 권고안
  ## 👥 역할별 핵심 결론        ← fan-out 보고서 집계 표
  | 역할 | 관점 | 핵심 결론 | 확신도 |
  ## ⚖️ 합의 / 충돌             ← dissent 보존
  ## 📎 근거                    ← source-uri + 등급 표
  ## 📂 상세(에이전트용) — 역할별 .report.yaml 링크
  ```
- 렌더는 read-only 변환이라 guard_tools 대상 아님(Write는 org-os 내부 경로만).

## 4. 변경 파일

| 파일 | 변경 |
|---|---|
| `org-os/00-role-registry/capability-families.yaml` | 26 family에 `collaboration-default` 추가 |
| `org-os/06-agent-work/execution-policy.yaml` | fan-out/collapse 실행 규칙 + rehydration override + 오버라이드 규칙 |
| `org-os/06-agent-work/collaboration-map.yaml` | **신설**: cascade-phases + design-to-build-contract + cross-group-edges |
| `org-os/06-agent-work/context-package-spec.yaml` | `fan-out-roles`, `report-return-contract`, design→build must-read 필드 |
| `org-os/06-agent-work/report-templates.yaml` | MD 렌더 매핑(human-render) 메타 추가 |
| `.claude/hooks/gen_agents.py` | fan-out family 에이전트에 "멤버별 분리 호출 + 원본 재적재 종합" 지시 삽입 |
| `.claude/hooks/render_report.py` | **신설**: YAML→MD + INDEX |
| `.claude/commands/run-wave.md` | fan-out 실행 절차(멤버 분리→경로 반환→상위 전부 읽기→종합) |
| `.claude/tests/test_enforcement.py` | render_report·분류·collaboration-map 정합 테스트 |

## 5. 불변식(유지)

- 다양성은 11 렌즈에서 나온다 — fan-out은 렌즈 다양성을 **강화**(더 이상 collapse로 희석 안 함). 서로 다른 렌즈 병합 금지 유지.
- 모든 산출물은 report-header(BLUF)로 시작. evidence 없는 confidence:High 금지. E4/E5는 실행/실존 아티팩트 필요.
- external side-effect 기본 금지(guard_tools). MD 렌더는 org-os 내부 Write만.
- tier=heavy는 plan-signoff 전 실행 금지. 사람 게이트를 self-report로 대체 금지.
- 62 역할은 참조 분류로 보존, 라우팅 단위는 26 family. `.claude/agents/*.md`는 생성물.

## 6. 테스트

- 분류: 26 family 모두 `collaboration-default` 존재, 값은 fan-out|collapse|n/a, 합계 19/6/1.
- collaboration-map: 모든 참조 family-id가 실존, cross-group-edges 양방향 쌍 정합.
- render_report: good YAML → MD에 BLUF·역할표·근거표·YAML 링크 포함; fan-out 다중 보고서 → 역할별 표 N행.
- gen_agents: fan-out 에이전트 본문에 "멤버별 분리·원본 재적재 종합" 문구 포함, collapse는 미포함.
- 기존 24 테스트 회귀 없음.