company-haness/CLAUDE.md

CLAUDE.md — Org OS 하네스

이 저장소는 **회사 전체를 AI 에이전트로 운영하는 파일 기반 운영체계(Org OS)**다. 개발과 비즈니스(GTM/수익)를 모두 다룬다. 실제 실행은 Claude Code 위에서 subagent·command·hook으로 이뤄진다.

구조

org-os/                         # 명세·상태의 단일 원천(SoT)
  00-role-registry/             # 역할·거버넌스 원천
    roles.yaml                  # 75 concrete 역할 taxonomy
    capability-families.yaml    # 28 family metadata 후보 집합(+triggers/exclusions/collaboration-default/lead-role-id)
    role-profiles.yaml          # 역할별 관점/시야/책임/근거(에이전트 알맹이의 원천)
    role-working-methods/       # 75직무 실제 일하는 방식의 도메인별 원천
    lens-registry.yaml          # 12 불가침 렌즈 = 다양성 바닥 (LENS-ADVISORY=외부·독립 자문: FAM-CONSULTING·FAM-DOC-CONSULT)
    drai-matrix.yaml            # 문서유형별 Decider/Recommender/Auditor/Informed
    state-transition-rules.yaml # 상태머신 + 상태어휘 정합 + tier-modifiers
    tool-permission-matrix.yaml # 최소권한(default-deny side-effects)
    role-selection-scorecard.yaml # 역할선택 점수화(candidate-family, rubric, tie-break)
    team-topology-map.yaml      # 팀 토폴로지·EA 계층·GTM 스택 라우팅
  01-company/                   # 회사·프로젝트 고유 사실(#5). company-context.yaml(status: template|provisional|operating
                                #   + projects[] 프로젝트별 manifest: stack·build/test/lint/run·users·제약·규약·민감도·최근결정).
                                #   미채움(template)이면 회사문맥 근거는 E2·Med 상한(validate_report 강제). 02~05·07은 stub.
  06-agent-work/                # 계약·정책 (SSOT only — 산출물/상태는 프로젝트 폴더로 나감)
    collaboration-modes.yaml    # divergent(발산)/converge(수렴) + report-header(BLUF)
    governance-tiers.yaml       # light/standard/heavy + 파생·limits·plan-signoff
    execution-policy.yaml       # pipeline·family-collapse·fan-out-collapse-policy·synthesis-rehydration·병렬감사
    collaboration-map.yaml      # 설계→구현 handoff + cascade(결정→설계→세부→구현) + 그룹 간 협업 엣지
    context-package-spec.yaml   # subagent 입력 계약(mode/tier/lens/delegation/collaboration/design-brief)
    report-templates.yaml       # 보고서 템플릿(BLUF-first) + human-md-rendering(YAML→MD 매핑)
    design-brief-spec.yaml      # 디자인·비주얼 산출물 제약층 계약
    agent-operating-kpi.yaml    # 에이전트 운영 KPI·토큰 예산
  packs/pack-index.yaml         # Decision/Design/Delivery/Assurance/Control plane별 Pack 소유권
  generated/                    # compiler 산출 role/family/method registry + architecture index
# 산출물·런타임은 프로젝트별 root 폴더로: <project>/{completion-records,evidence,reports,state,slack-*,design-system}
# 현재 워크스페이스 = env ORGOS_WORKSPACE 또는 .orgos-workspace 포인터(미설정 시 WorkspaceNotSetError로 중단 — 조용한 test 기본값 제거) · 훅은 .claude/hooks/_workspace.py로 경로 해석
<project>/                      # 예: _sandbox/(하네스 데모). 실제 프로젝트는 ORGOS_WORKSPACE 로 지정
.claude/
  agents/*.md                   # 75 concrete 실행 역할 card. family router/resolver 없음. gen_agents.py 생성 — 수기 편집 금지
  commands/*.md                 # ceo-intake, ground→decide(순서교정), design, spec, build, consult, plan-wave, run-wave, review-output, release-check
  hooks/consult_exhibits.py, render_consult.py  # 컨설팅 SVG 시그니처 차트 + storyline→문서/PPT 렌더러
  hooks/*.py                    # gen_agents, guard_tools(2차 defense; 1차=settings.json permissions), validate_report(보고+dissent+receipt+primary-artifacts강제), stop_validate(SubagentStop fail-closed·Stop advisory), subagent_register(SubagentStart 등록), evidence_ledger(PostToolUse receipt 원장), context_package(spawn 컴파일러+validator), state_engine(상태전이 강제·wave/cascade 통합원장·#7/#13), acceptance_log(불변 수용/supersede 이벤트·#14), render_report(YAML→MD·validator 게이트), new_report(불변경로), token_ledger(토큰예산·per-wave·#19), kpi_ledger(KPI 수집기 — 아티팩트에서 파생·정직 대시보드·#19), lens_cap(lens×sub-specialty 2축), lint_refs(참조 무결성), doctor(실행 무결성 preflight + SSOT 소비 감사·#13 + tool-versions 대조·#18), benchmark(골든태스크 plain-vs-harness 회귀·리뷰 3주차), notify_slack
  schemas/*.json                # report/acceptance-event JSON Schema(validator가 소비)
  execution-plans.yaml → org-os/06-agent-work  # cascade/wave/light = 같은 state graph 위 preset
  settings.json                 # LIVE hook 배선(Pre/PostToolUse·Subagent Start/Stop·Stop) + permissions(deny/ask 1차 경계). Claude Code가 실제 로드. `doctor.py`로 확인
  tests/test_enforcement.py + test_p1_*/test_state_engine/test_subagent_lifecycle  # 강제기 단위테스트(≈500 assert)
docs/superpowers/               # 설계 스펙·계획

핵심 개념

• 75 concrete 역할 + 28 family metadata: family는 실행 actor가 아니라 후보 집합이다. role_selector.py가 coverage·독립성·token budget으로 minimum sufficient concrete role만 선택한다. 다양성은 headcount가 아니라 12 렌즈에서 나온다.
• 컨설팅 레이어(LENS-ADVISORY, 외부·독립 자문): 2 family. FAM-CONSULTING(비즈니스 자문 — EM 리드 + 전략/운영/조직·변화/디지털/재무·리스크)와 FAM-DOC-CONSULT(문서·콘텐츠 설계 자문 — DOC-LEAD 리드 + 테크니컬라이터/정보아키텍트/비주얼(다이어그램)/개발자교육; Diátaxis·IA·C4·인지부하). 둘 다 lead-role-id가 프레임(SCQA·아웃라인·Day-1)+종합(Pyramid), 나머지 fan-out. /consult → render_consult.py가 storyline에서 **문서(.md)+덱(.pptx/.pdf/.html)**을 한 소스로 생성. exhibit 2계열: 정량·개념 차트=손제작 SVG 아키타입 7종(consult_exhibits.py: waterfall/matrix2x2/harvey/valuechain/benchmark/issuetree/process), 소프트웨어 구조·흐름·의존성 그래프={type: d2} → d2 CLI로 실제 diagram-as-code 실물 렌더(중첩 컨테이너·레이아웃엔진 dagre/elk·테마, 1급). {type: mermaid}는 최후 폴백만(실무급 아님). 주제에 맞게: 구조/흐름=D2, 정량=아키타입.
• 디자인 craft(전문가급 산출 표준): 디자인·비주얼 직무(DES-PROD/PLATFORM/INTERNAL, DOC-VISUAL)는 프레임워크 서술이 아니라 제약층으로 일한다 — design-brief(brief→references(구체 신호, "modern/clean" 형용사 금지)→tokens(값+의도+경계)→decisions→donts; design-brief-spec.yaml) + skill(.claude/skills/design-craft·diagram-craft, gen_agents가 에이전트에 embed). 빈 추론층을 모델이 generic으로 채우는 걸 막는다(제약>묘사). 다이어그램은 D2 우선({type: d2} d2 CLI 실물 렌더), Mermaid는 폴백. 근거: 웹조사 design-craft-upgrade.
• 코드 디자인 시스템 파이프라인(/design-system): Figma가 아니라 코드로 실제 UI·디자인 시스템을 만든다(무료 Figma는 읽기 월 6회 제한이라 품질 반복 루프가 막힘). 층: design-brief(제약) → design-system/tokens.css(CSS 변수 SoT, DES-PLATFORM) → components/(재사용 React, 토큰만 소비) → screens/(조립, ENG-FE) → .claude/hooks/preview_ui.py(vite build→headless chrome 스크린샷, rate-limit 없이 실제 UI 확인). DESIGN.md·skill의 대체가 아니라 완성(제약·방법은 그대로, 재사용 실체+매체를 더함). 근거: design-system-pipeline.
• fan-out vs collapse(collaboration-default): 판단·설계·분석·수익 계열 family는 fan-out(멤버 role을 격리 subagent로 분리 → 각자 보고서 → 상위가 원본 전부 읽고 종합, context 오염 방지). 코드·실행 계열만 collapse(1에이전트 단일 보고서, 효율). tier/mode가 오버라이드(heavy→강제 fan-out, light+converge→단일 종합). 결정 지점은 synthesis-rehydration(요약 아닌 원본 재적재). cascade: 결정→설계→세부→구현.
• 2단 보고: .report.yaml=SoT(에이전트끼리, hook 검증) → render_report.py가 대표용 MD 자동 생성(BLUF 콜아웃+역할별 표+상세 embed+근거표, drift 없음). reports/INDEX.md가 목차.
• fan-out 비용·품질 컨트롤(5): ①토큰예산(token_ledger→wave 초과 시 collapse 강등, reports/TOKENS.md 대시보드) ②렌즈상한(lens_cap: light/standard는 같은 렌즈 1명) ③공유제약 pre-brief(context-package shared-constraints) ④dissent 보존검증(validate_report: 종합엔 conflicts+linked-reports 필수) ⑤compaction(결정 재적재는 압축 제외). 근거: 유사 하네스 웹조사 harness-efficiency-audit.
• Mode × Tier(직교 2축): Mode=divergent(아이디어 발산·병렬) / converge(결정·수렴). Tier=light/standard/heavy(위험도 파생). HEAVY == 기존 DRAI 전체 + 인간 게이트. 저위험은 경량 경로.
• DRAI: 문서유형마다 Decider/Recommender/Auditor/Informed. AI는 제안까지, 고위험 승인권은 사람(RACI).
• 증거등급 E0~E5: 모든 결론은 근거에 접지. 자기채점 금지 — hook이 아티팩트로 검증.

규칙(불변식)

• 모든 산출물은 report-header(BLUF)로 시작: bottom-line → decision-needed(+approver) → confidence(증거 파생) → risks → evidence. (SubagentStop hook이 fail-closed 강제; 메인 세션 Stop은 advisory 경고 — 스테일 보고서로 세션을 막지 않음)
• evidence 없는 confidence:High 금지, source-uri는 실존해야, E4/E5는 실행/실존 아티팩트 필요 — validator가 PostToolUse evidence-ledger의 실제 receipt(command·exit-code·artifact-hash)와 대조한다(자기신고 E5 차단, evidence_ledger.py).
• 회사 문맥 상한(#5): org-os/01-company/company-context.yaml이 공식 파일로서 status: operating(또는 구 demo/populated 읽기호환)에 도달할 때까지, 회사/제품 문맥 폴더(01-company·03-products·04-architecture·05-operations 등)의 항목별 provenance 정책을 따른다 — status != operating이면 company 인용 항목은 E2/Med 상한; hypothesis 항목은 status 무관 Med 상한. hypothesis 이외 항목이 E3+ 근거로 인용되려면 실제 아티팩트·receipt이 필요(validate_report 강제). 실제 회사 사실은 사용자가 채운다.
• 운영 실행은 workspace 필수(#5): .orgos-workspace 활성 기본값을 제거했다 — 운영/실작업은 ORGOS_WORKSPACE=<project> 명시(미설정 시 _workspace.py가 WorkspaceNotSetError로 중단). 테스트는 ORGOS_WORKSPACE=_sandbox 명시.
• 보고서는 불변(immutable): .report.yaml은 덮어쓰기/수정 금지(guard_tools 강제). 재작업도 new_report.py로 새 버전 파일 생성 → 감사 추적 보존, INDEX는 워크플로별 append-only.
• 에이전트는 '일하는 방식'을 근거로 실행: 각 에이전트에 웹조사 기반 실무 절차/프레임워크/근거/출처(role-working-methods.yaml)가 embed됨.
• external side-effect(slack/PR/deploy/secret/db-write)는 기본 금지(guard_tools 강제).
• worker는 context-package 없이 시작 금지 — 모든 spawn은 context_package.py 컴파일러+validator를 거친다(workspace·target-repo·acceptance-tests·non-goals·evidence-plan 필수, 미충족 시 spawn 금지). parent는 completion-record 없이 Accepted 금지. tier=heavy는 plan-signoff 전 실행 금지.
• 서로 다른 lens는 병합 금지(다양성 보존). .claude/agents/*.md는 생성물 — 바꾸려면 role-profiles/capability-families 고치고 gen_agents.py 재실행.
• hook 강제는 설정(.claude/settings.json) 활성 시에만 동작한다 — 설치 안 되면 형식·근거·권한·불변성 강제가 꺼진다(문서상 "강제"를 실물로 만드는 전제). python3 .claude/hooks/doctor.py(orgos doctor)로 설정·배선·의존성·workspace·참조 무결성을 확인한다.

Slack 브리핑·알림

• 전역 규약: ~/.claude/CLAUDE.md에 Slack 브리핑 템플릿(작업/리뷰)·기본 채널 #clean-architecture-전체(C0BCN9H9ABH)·MCP mcp__slack__slack_post_message가 정의돼 있다. 사용자가 "슬랙 브리핑해"라고 하면 그 규약(공통 헤더 repo/branch/시각 + 템플릿)으로 전송한다.
• org-os 정책: Slack은 알림 채널이며 상태 원천이 아니다(SoT는 org-os 파일). 알림 대상 이벤트 = blocker, human-review-needed, daily digest, Critical 위험(drai-matrix require-slack, work-queue.slack-notification-policy).
• 자동 알림 배선(구현됨): .claude/hooks/notify_slack.py — 이벤트(blocker/human-review/critical/digest/task/review) → redact(이메일/키/토큰/비번 마스킹) → 전역 템플릿 포맷(BLUF) → 전송. 전송 경로 2가지: $SLACK_WEBHOOK_URL 있으면 hook이 자율 직접 POST(헤드리스 안전), 없으면 slack-outbox/에 적재 → 세션이 mcp__slack__slack_post_message로 flush. (Claude Code hook은 MCP 직접 호출 불가라 이 2경로 구조.)
• 범위 정책: 자동 알림은 blocker/human-review-needed/Critical/daily-digest로 한정(drai-matrix require-slack, work-queue.slack-notification-policy). 일반 완료물은 completion-records 파일로만 남겨 Slack 스팸 방지. raw slack 전송은 여전히 guard_tools 차단 — 승인 채널·경로만 허용.

실행 흐름

시작점: README.md — "어떤 커맨드부터?"(항상 /ceo-intake) + 상황별 진입(전체 cascade / 중간부터 / 경량)을 안내.

/ceo-intake   → 결정적 intake가 light/substantial/strategic을 분류(전략 작업만 executive 호출)
/plan-wave    → Orchestrator가 최소 충분 concrete role 계획(plan.md + workflow.yaml progress) 작성
/run-wave     → 선택된 concrete role subagent 실행, completion-record 산출
/review-output→ Parent가 검토(Accepted/Changes-Requested/Blocked)
/release-check→ Release Acceptance(DRAI + 인간 게이트)

Venture Bootstrap(회사 수립 — 제품 cascade의 선행, 1회성)

/ceo-intake --plan venture-bootstrap → /venture-validate → /company-bootstrap

• 순환 해소: founder-context(사람 입력) → 기회탐색·9-gate 검증 → C-Level 수렴 + 사람 승인 → company-context.yaml(provisional) 원자 commit. 이후 제품 cascade가 이를 입력으로 소비.
• 공식 company-context status: template|provisional|operating(3-상태). 모든 전이는 OPS-ORCH 집행.

Cascade 커맨드(계층 순차) — collaboration-map GROUND→DECIDE→…→BUILD (state_engine이 전이 강제)

/ground  → discovery: 문제·시장·사용자·경쟁·재무 근거 접지 + option-set(≥2) 발산 — 결정 아님(근거 먼저)
/decide  → converge: C-Level이 근거·옵션을 읽고 하나로 수렴 → ExecutiveDecisionPacket(방향·go/no-go)
/design  → 설계 직무(아키텍트/데이터/디자인/보안) fan-out → 큰 설계문서
/spec    → PM/아키텍트 → 기능명세(PRD·api-contract·수용기준)
/build   → 구현 family(collapse) + QA/보안 감사 → completion-record

• 순서 교정(#7): ground(discovery)→decide(converge). 근거·옵션을 먼저 세우고 수렴 결정 — decide 후 ground의 anchoring 제거.
• 상태 강제(#7/#13): 각 커맨드는 진입 시 state_engine.py guard로 stage 선행조건을 확인하고(미충족=BlockedReport), 종료 시 transition으로 전진한다. 예: /build는 design-to-build-contract must-read-designs가 Accepted 아니면 엔진이 거부(프롬프트 문구가 아니라 실제 강제). wave·cascade·light는 execution-plans.yaml의 preset으로 하나의 state graph를 공유(<workspace>/state/<wf>/workflow.yaml 통합 원장).
• 각 커맨드는 이전 산출물을 must-read로 읽고 다음으로 handoff. 중간 시작: 새 워크플로는 /ceo-intake, 기존 wf-id는 선행 gating 산출물이 있으면 중간 stage에서 재개(엔진이 검증). 전부 불변보고서·토큰게이트·dissent게이트·스레드Slack·태그 재사용.

검증(자주 쓰는 것)

# 전부 한 번에(#18): doctor + lint_refs + 모든 test_*.py (CI와 동일 진입점). 하나라도 실패면 exit 1.
CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/run_all.py
# 개별: 실행 무결성 preflight(설정·hook 배선·의존성(tool-versions.yaml)·workspace·커맨드→agent 참조)
python3 .claude/hooks/doctor.py ; python3 .claude/hooks/lint_refs.py
# 개별 강제기 단위테스트(receipt 기반 evidence + subagent lifecycle 포함) — workspace 명시 필요
CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/test_enforcement.py
CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/test_subagent_lifecycle.py
# 의존성 설치(pinned): pip install -r requirements.txt · CI: .github/workflows/ci.yml
# 에이전트 재생성(role-profiles/capability-families 변경 후)
CLAUDE_PROJECT_DIR="$PWD" python3 .claude/hooks/gen_agents.py
# KPI 수집(#19): 아티팩트에서 파생 → 정직 대시보드(reports/KPI.md)
ORGOS_WORKSPACE=_sandbox python3 .claude/hooks/kpi_ledger.py derive && python3 .claude/hooks/kpi_ledger.py dashboard
# 품질 회귀 벤치마크(리뷰 3주차): plain vs 하네스. record로 두 arm 점수 적재 → compare
python3 .claude/hooks/benchmark.py list ; python3 .claude/hooks/benchmark.py compare  # -> benchmark/BENCHMARK.md

작업 원칙(이 저장소에서)

• org-os가 SoT다. 규칙을 바꾸면 명세(yaml)를 먼저 고치고, 에이전트는 재생성한다.
• 큰 변경은 docs/superpowers/specs에 설계를 남기고 진행한다.
• 강제기(hook/validator)를 우회하지 말고, 계약(report-header·evidence·권한)을 지킨다.