donghyeon.kang/company-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
bac770dc4c5cc03e9efa62873c9c95eaed3fe9ce
company-haness/docs/superpowers/specs/2026-07-07-fanout-collaboration-two-tier-reporting-design.md
T

10 KiB
Raw Blame History

설계: 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 템플릿(가독성 우선): 
    # 🟢 [결정] <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 테스트 회귀 없음.
Reference in New Issue View Git Blame Copy Permalink