130 lines
18 KiB
Markdown
130 lines
18 KiB
Markdown
# 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](docs/superpowers/specs/2026-07-08-design-craft-upgrade-design.md).
|
||
- **코드 디자인 시스템 파이프라인(`/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](docs/superpowers/specs/2026-07-08-design-system-pipeline-design.md).
|
||
- **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](docs/superpowers/harness-efficiency-audit-2026-07-07.md).
|
||
- **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·태그 재사용.
|
||
|
||
## 검증(자주 쓰는 것)
|
||
```bash
|
||
# 전부 한 번에(#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·권한)을 지킨다.
|