272 lines
25 KiB
Diff
272 lines
25 KiB
Diff
--- README.md (current)
|
|
+++ README.md (candidate)
|
|
@@ -1,120 +1,171 @@
|
|
-# Org OS 하네스 — 실행 안내
|
|
+# Org OS 하네스 — Claude Code용 에이전트 운영체계
|
|
|
|
-회사를 AI 에이전트로 운영하는 파일 기반 운영체계. 개발 + 비즈니스(수익)를 함께 다룬다.
|
|
-규칙·구조는 [CLAUDE.md](CLAUDE.md), 상태/기록 구분은 [org-os/06-agent-work/README.md](org-os/06-agent-work/README.md).
|
|
+Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다. <!-- claim-id: C-IDENTITY -->
|
|
|
|
-## 🚀 어떤 커맨드부터? — 항상 `/ceo-intake`
|
|
+이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다. <!-- claim-id: C-VALUE -->
|
|
|
|
-**새 워크플로**는 **`/ceo-intake`**로 시작한다 — 사용자 요청을 Decision Brief(mode·tier·후보 직무)로 정리한다. (모순 아님: **기존 wf-id**는 선행 gating 산출물이 있으면 중간 stage에서 재개 가능 — B. 참조. `state_engine`이 전이 선행조건을 검증한다.)
|
|
-그다음은 **상황(tier·명확도)에 따라** 갈린다:
|
|
+<!-- section-id: overview -->
|
|
+## 무엇을 제공하나요?
|
|
|
|
-### 새 회사/제품을 처음 세울 때(venture-bootstrap)
|
|
+일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다. <!-- claim-id: C-ENTRY-MODEL -->
|
|
|
|
-company-context가 아직 `template`이면 제품 cascade 전에 회사부터 세운다:
|
|
+이 하네스가 연결하는 범위는 다음과 같습니다.
|
|
|
|
-1. `org-os/01-company/founder-context.yaml`을 채운다(status: filled).
|
|
-2. `/ceo-intake --plan venture-bootstrap` → `/venture-validate`(기회탐색+9-gate 검증) → `/company-bootstrap`(C-Level 수렴 + 사람 승인 + company-context 원자 commit).
|
|
-3. 완료되면 공식 company-context.status = `provisional`. 이제 `/ground`부터 제품 cascade를 탄다.
|
|
+- 역할과 family를 이용한 작업 라우팅
|
|
+- 단계별 입력·출력 artifact와 검토 권한
|
|
+- 상태 전이 전 exit gate와 사람 승인
|
|
+- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
|
|
+- 프로젝트별 report·evidence·state 저장소
|
|
|
|
-기존 회사(status ∈ {provisional, operating})면 곧장 `/ceo-intake` → `/ground`.
|
|
+<!-- section-id: operating-model -->
|
|
+## 핵심 운영 모델
|
|
|
|
-### A. 새 전략 결정 (신규 제품·수익·방향, 아이디어 불명확) — 전체 cascade
|
|
+1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다. <!-- claim-id: C-CONTRACT-MODEL -->
|
|
+2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다. <!-- claim-id: C-COLLAB-MODEL -->
|
|
+3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다. <!-- claim-id: C-HUMAN-BOUNDARY -->
|
|
+4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다. <!-- claim-id: C-PROVENANCE-MODEL -->
|
|
+
|
|
+Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다. <!-- claim-id: C-HOOK-MODEL -->
|
|
+
|
|
+<!-- section-id: quick-start -->
|
|
+## 시작하기
|
|
+
|
|
+### 1. 필수 도구 확인
|
|
+
|
|
+핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다. <!-- claim-id: C-PREREQUISITES -->
|
|
+
|
|
+저장소 루트에서 의존성을 설치합니다.
|
|
+
|
|
+```bash
|
|
+pip install -r requirements.txt
|
|
```
|
|
-/ceo-intake 의도 → Decision Brief(tier=heavy, divergent→converge)
|
|
- ↓
|
|
-/ground discovery: 시장·사용자·경쟁·재무 근거 접지 + option-set(≥2) 발산 (결정 전, anchoring 방지)
|
|
- ↓
|
|
-/decide converge: C-Level(CPO·CFO·CTO·COO)이 근거·옵션을 하나로 수렴 → CEO ExecutiveDecisionPacket
|
|
- ↓ ← 사용자(HUMAN-001) 승인 게이트 (go/no-go)
|
|
-/design 아키텍트·데이터·디자인·보안 설계 fan-out → 큰 설계문서
|
|
- ↓ (UI-bearing이면 design-system 서브파이프라인 포함 → 실제 preview_ui 렌더 게이트가 프론트 BUILD 선행조건)
|
|
-/spec PM·아키텍트 → 기능명세(PRD·api-contract·수용기준)
|
|
- ↓
|
|
-/build 구현 family(collapse) + QA/보안 감사 → completion-record
|
|
- ↓
|
|
-/review-output Parent 수용 검토(Accepted/Changes-Requested/Blocked)
|
|
- ↓
|
|
-/release-check Release Acceptance(DRAI + 인간 게이트)
|
|
+<!-- claim-id: C-INSTALL-COMMAND -->
|
|
+
|
|
+### 2. 워크스페이스 지정
|
|
+
|
|
+산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다. <!-- claim-id: C-WORKSPACE-RESOLUTION -->
|
|
+
|
|
+저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
|
|
+
|
|
+```bash
|
|
+export ORGOS_WORKSPACE=_sandbox
|
|
+python3 .claude/hooks/doctor.py
|
|
+```
|
|
+<!-- claim-id: C-DOCTOR-COMMAND -->
|
|
+
|
|
+`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
|
+
|
|
+### 3. 첫 워크플로 시작
|
|
+
|
|
+Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다. <!-- claim-id: C-FIRST-COMMAND -->
|
|
+
|
|
+<!-- section-id: workflows -->
|
|
+## 작업에 맞는 워크플로 선택
|
|
+
|
|
+| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|
|
+|---|---|---|
|
|
+| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-CASCADE --> |
|
|
+| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-WAVE --> |
|
|
+| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` <!-- claim-id: C-WORKFLOW-LIGHT --> |
|
|
+| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` <!-- claim-id: C-WORKFLOW-VENTURE --> |
|
|
+
|
|
+`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다. <!-- claim-id: C-SPECIALIZED-WORKFLOWS -->
|
|
+
|
|
+다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다. <!-- claim-id: C-CASCADE-VISUAL -->
|
|
+
|
|
+```mermaid
|
|
+flowchart LR
|
|
+ A["intake<br/>/ceo-intake"] --> B["discovery<br/>/ground"]
|
|
+ B --> C["decide<br/>/decide"]
|
|
+ C --> D{"사람 방향 수용"}
|
|
+ D --> E["design<br/>/design"]
|
|
+ E --> F["spec<br/>/spec"]
|
|
+ F --> G["build<br/>/build"]
|
|
+ G --> H["verification<br/>/review-output"]
|
|
+ H --> I["acceptance<br/>/release-check"]
|
|
+ I --> J{"사람 release 승인"}
|
|
+ J --> K["released"]
|
|
```
|
|
|
|
-> **한 번에 걷고 싶으면 — `/run-cascade`** (상위 오케스트레이터). 위 A를 개별 커맨드로 일일이 부르는 대신, `/run-cascade`가 `state_engine`을 재사용해 현재 stage를 확인 → 필요한 stage만 실행 → 산출물 검증 → **사람 결정 지점(DECIDE go/no-go·RELEASE 수용)에서 정지**한다. 사용자는 처음에 문제·목표만 주고 중요한 결정에서만 개입한다. 자동 승인·자동 완주는 하지 않으며(사람 게이트가 존재 이유), 각 stage의 강제(spawn 게이트·validator·전이)는 그대로 작동한다. 사람이 승인하면 `/run-cascade --workflow <wf>`로 재개.
|
|
+<!-- visual-id: cascade-flow -->
|
|
|
|
-### B. 방향이 이미 명확하면 — **중간부터 시작**
|
|
-- 결정은 섰고 설계부터 → `/design` → `/spec` → `/build`
|
|
-- 설계도 섰고 명세부터 → `/spec` → `/build`
|
|
-- 명세·디자인도 있고 바로 개발 → `/build`
|
|
+<!-- section-id: architecture -->
|
|
+## 저장소 구조와 책임
|
|
|
|
-### C. 단순·저위험 작업 — 경량 경로 (cascade 생략)
|
|
-```
|
|
-/ceo-intake (tier=light) → /run-wave (family collapse 실행) → /review-output
|
|
+실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다. <!-- claim-id: C-ARCH-SOURCE -->
|
|
+
|
|
+| 경로 | 책임 |
|
|
+|---|---|
|
|
+| `org-os/00-role-registry/` | 역할, capability family, lens, 권한과 라우팅 정책 |
|
|
+| `org-os/06-agent-work/` | workflow graph, artifact vocabulary, 협업·실행 정책 |
|
|
+| `.claude/commands/` | 사용자가 호출하는 slash command 정의 |
|
|
+| `.claude/agents/` | registry에서 생성되는 worker·lead·router·resolver 카드 |
|
|
+| `.claude/skills/` | concrete role별 작업 방법과 자기검증 절차 |
|
|
+| `.claude/hooks/` | 상태 엔진, 도구 경계, report·evidence 검증, 생성기와 렌더러 |
|
|
+| `.claude/schemas/` | workflow artifact와 report의 typed schema |
|
|
+| `.claude/tests/` | hook 강제기와 workflow 계약 테스트 |
|
|
+| `benchmark/` | golden task, 실행 ledger, plain 대 harness 비교 |
|
|
+| `docs/` | 설계·계획·감사 이력 |
|
|
+
|
|
+<!-- claim-id: C-DIRECTORY-MAP -->
|
|
+
|
|
+현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다. <!-- claim-id: C-ROLE-MODEL -->
|
|
+
|
|
+기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오. <!-- claim-id: C-GENERATED-AGENTS -->
|
|
+
|
|
+<!-- section-id: artifacts -->
|
|
+## 워크스페이스와 산출물
|
|
+
|
|
+`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다. <!-- claim-id: C-WORKSPACE-LAYOUT -->
|
|
+
|
|
+```text
|
|
+<workspace>/
|
|
+├── completion-records/<workflow>/ # 불변 .report.yaml과 사람용 .md
|
|
+├── evidence/ # 실행·파일 receipt와 근거
|
|
+├── reports/ # INDEX와 사람이 읽는 집계 뷰
|
|
+├── state/ # workflow·artifact·acceptance event
|
|
+├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
|
|
+└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
|
|
```
|
|
|
|
-### D. 외부·독립 컨설팅 문서·덱이 필요하면 — `/consult`
|
|
-```
|
|
-/consult 주제 · 자료=<문서> · 대상=<repo>
|
|
- → 엔게이지먼트 유형으로 family 선택:
|
|
- • 비즈니스 자문 → FAM-CONSULTING (EM + 전략/운영/조직·변화/디지털/재무·리스크)
|
|
- • 문서·콘텐츠 설계 → FAM-DOC-CONSULT (DOC-LEAD + 라이터/정보아키텍트/비주얼/개발자교육)
|
|
- → 진단→권고 storyline → 문서(.md) + 덱(.pptx/.pdf/.html, 시그니처 도해 SVG)
|
|
-```
|
|
-컨설팅은 LENS-ADVISORY(외부·제3자 관점) — 사내 결정(`/decide`)·전략분석(`FAM-STRATEGY`)과 별개의 독립 자문 산출물. 제안까지(최종 결정은 사람).
|
|
+report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다. <!-- claim-id: C-REPORT-RECEIPTS -->
|
|
|
|
-### E. 실제 UI·디자인 시스템을 코드로 만들고 보고 싶으면 — `/design-system`
|
|
-```
|
|
-/design-system 주제 · dir=<프로젝트>/design-system
|
|
- ① design-brief(제약층: brief→references→tokens→decisions→donts, skill=design-craft)
|
|
- ② DES-PLATFORM → tokens.css(CSS변수 SoT) + components/*.jsx (var(--*)만 소비)
|
|
- ③ ENG-FE → screens/*.jsx (컴포넌트 조립만) + preview.jsx
|
|
- ④ preview_ui.py → 패키지매니저 자동감지(pnpm/yarn/npm)→build→headless chrome 렌더검증+반응형 스크린샷+정적 CSS 품질(대비·포커스)
|
|
- ⑤ 스크린샷 육안검증 → 고치고 preview 재실행(무제한 반복 루프). 스크린샷 존재 ≠ 품질(빈 #root·대비 실패면 게이트 실패)
|
|
-```
|
|
-Figma 없이 **코드로** 실제 UI를 만들고 headless chrome으로 확인한다(무료 Figma의 read rate-limit 회피). 산출: `<프로젝트>/design-system/`(tokens·components·screens·preview.png).
|
|
+<!-- section-id: verification -->
|
|
+## 검증 방법과 증거 수준
|
|
|
|
-> **`/design` ⊃ `/design-system`(UI-bearing이면 통합)** — `/design`은 cascade의 **설계 판단** 단계(아키텍트·데이터·디자인·보안이 *무엇을 만들지* fan-out으로 결정). 이 워크플로가 **사용자 대면 UI를 만들면**(BUILD에 `FAM-ENG-FRONTEND` 포함) `/design`의 fam-design 분기가 **`/design-system` 서브파이프라인을 그대로 돈다** — 산출 `design-type: design-system`은 **실제 `preview_ui` 렌더 게이트(receipt)를 통과해야** 프론트 BUILD가 열린다(`state_engine`이 강제; 산문만으론 안 됨). non-UI 워크플로(백엔드·인프라·의사결정)는 design-system을 요구하지 않는다. `/design-system`은 **독립 실행**(디자인만 반복)도 가능. 디자인·비주얼 직무는 *프레임워크 서술*이 아니라 **제약층(design-brief) + skill**(`design-craft`·`diagram-craft`)로 일한다 — 다이어그램은 **D2 우선**(Mermaid는 폴백).
|
|
+다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
|
|
|
|
-## 커맨드 = 계층, 이전 산출물을 읽는다
|
|
+| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|
|
+|---|---|---|
|
|
+| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-DOCTOR --> |
|
|
+| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-AGENTS --> |
|
|
+| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-TESTS --> |
|
|
+| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-BENCHMARK --> |
|
|
|
|
-| 커맨드 | phase | 호출 계층 | 입력(must-read) | 산출/handoff |
|
|
-|---|---|---|---|---|
|
|
-| `/run-cascade` | **전 cascade 오케스트레이터** | Orchestrator(`state_engine`) | 아이디어/문제 또는 `--workflow <wf>` | GROUND→…→BUILD 순차 진행, **사람 게이트서 정지**(자동 완주 X) |
|
|
-| `/ceo-intake` | intake | CEO | 사용자 요청 | Decision Brief → /ground 또는 /run-wave |
|
|
-| `/ground` | GROUND/discovery | strategy·PM·UX·CI·pricing | Decision Brief | 근거+option-set(≥2) → /decide |
|
|
-| `/decide` | DECIDE/converge | C-Level → CEO | discovery 근거+옵션 | ExecutiveDecisionPacket → /design (사람 go/no-go) |
|
|
-| `/design` | DESIGN | 아키텍트·데이터·디자인·보안 | 승인 결정+verdict | 큰 설계문서(+UI면 design-system·preview 렌더 게이트) → /spec |
|
|
-| `/spec` | DETAIL | PM·아키텍트 | 설계문서 | 기능명세 → /build |
|
|
-| `/build` | BUILD | ENG(collapse)+QA | 설계+명세(+UI면 렌더된 design-system) | completion-record → /review-output |
|
|
-| `/review-output` | review | Parent | completion-record | 수용/반려 |
|
|
-| `/release-check` | release | DRAI+HUMAN | 수용 결과 | 릴리스 승인(인간 게이트) |
|
|
-| `/consult` | CONSULT | FAM-CONSULTING(EM+5분과) | 주제+자료+대상repo | 컨설팅 문서(.md)+덱(.pptx/.pdf/.html) |
|
|
-| `/design-system` | DESIGN-SYSTEM | DES-PLATFORM+ENG-FE | design-brief(제약) | 코드 디자인시스템(tokens·components·screens)+preview.png |
|
|
+`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다. <!-- claim-id: C-TEST-RUNNER -->
|
|
|
|
-- **fan-out**(판단·설계·수익): 역할별 격리 subagent → 각자 보고서 → 상위가 원본 읽고 종합.
|
|
-- **collapse**(코드·실행): family 1에이전트 단일 보고서(효율).
|
|
-- 전 단계 공통: 불변보고서(`new_report.py`)·토큰게이트(`token_ledger.py`)·dissent게이트(`validate_report.py`)·태그(`report_tags.py`)·작업전 Slack(`slack_inbox.py`).
|
|
+GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다. <!-- claim-id: C-CI -->
|
|
|
|
-## 결과는 어디에
|
|
-산출물·상태는 **프로젝트별 root 폴더**로 나간다(`<project>/`, 현재 워크스페이스=`.orgos-workspace` 또는 env `ORGOS_WORKSPACE`, 미설정 시 중단 — 조용한 test 기본값 없음(WorkspaceNotSetError)). org-os는 SSOT(정의·계약)만 남긴다 — 훅은 [.claude/hooks/_workspace.py](.claude/hooks/_workspace.py)로 경로를 해석한다.
|
|
-- **불변 보고서(SoT, 에이전트끼리)**: `<project>/completion-records/<workflow>/*.report.yaml`
|
|
-- **대표용 MD**: 같은 이름 `.md` + 목차 `<project>/reports/INDEX.md` + 토큰 `<project>/reports/TOKENS.md`
|
|
-- **디자인 시스템**: `<project>/design-system/`(tokens·components·screens·preview.png)
|
|
-- **워크스페이스**: 산출물은 `ORGOS_WORKSPACE`가 가리키는 프로젝트 폴더로 나간다. 하네스 자기검증용 `_sandbox/`가 기본 데모 워크스페이스.
|
|
-- **Slack 보고**: 부모=종합 결정 + 스레드 답글=역할별 개별 판정(`#clean-architecture-전체`)
|
|
+벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다. <!-- claim-id: C-BENCHMARK-STATUS -->
|
|
|
|
-## 검증
|
|
-```bash
|
|
-ORGOS_WORKSPACE=<프로젝트> python3 .claude/hooks/doctor.py # 실행 무결성 preflight(설정·hook·의존성·workspace·참조). workspace 미설정이면 FAIL(P0-1 fail-closed 설계)
|
|
-CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/run_all.py # 전체(doctor+lint_refs+모든 test_*) — CI 진입점
|
|
-CLAUDE_PROJECT_DIR="$PWD" python3 .claude/hooks/gen_agents.py --check # 101 에이전트 정합
|
|
-```
|
|
+<!-- section-id: limitations -->
|
|
+## 현재 상태와 한계
|
|
|
|
-## 품질 검증 상태 (정직 — 과대주장 금지)
|
|
-이 하네스는 **절차·신뢰경계는 강제되지만, "plain Claude보다 결과가 낫다"는 아직 증명되지 않았다.**
|
|
-- **측정 인프라는 실재**: `benchmark.py run --execute`가 골든태스크를 plain vs 하네스로 실제 실행(nested claude CLI)하고 pytest·git diff로 객관 채점한다(위조 점수 없음).
|
|
-- **지금까지 실증**: 단순 버그픽스(GT-01·GT-R2)는 **plain==harness**(둘 다 만점). 하네스가 과차단·과설계를 하지 않음(해 없음)은 확인됐으나 **lift(우위)는 없음** — 단순 과제는 하네스를 exercise하지 않기 때문.
|
|
-- **미증명**: 하네스의 가치가설(다관점 fan-out·근거접지·사람게이트)이 발휘되는 **모호·설계·의사결정 과제(GT-09~12)는 자동채점 fixture가 없어 아직 측정 못 함**. head-to-head rubric 채점을 붙여야 "품질이 높다"를 말할 수 있다.
|
|
-```bash
|
|
-python3 .claude/hooks/benchmark.py list # 골든태스크 목록
|
|
-python3 .claude/hooks/benchmark.py run --task GT-01 --arm plain --execute # 실제 실행·객관채점(예산 소비)
|
|
-python3 .claude/hooks/benchmark.py compare # → benchmark/BENCHMARK.md (plain vs 하네스 delta)
|
|
-```
|
|
-> 판정 규칙: 어떤 role/fan-out/framework가 이 비교에서 delta≤0이면 비용만 늘리는 것 → 제거/경량화 후보. **증명 안 된 것을 증명된 척하지 않는다.**
|
|
+- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다. <!-- claim-id: C-LIMIT-CONTEXT -->
|
|
+- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다. <!-- claim-id: C-LIMIT-HOOKS -->
|
|
+- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다. <!-- claim-id: C-LIMIT-UI -->
|
|
+- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다. <!-- claim-id: C-LIMIT-TOOLS -->
|
|
+- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다. <!-- claim-id: C-LIMIT-EVIDENCE -->
|
|
+
|
|
+<!-- section-id: reference -->
|
|
+## 정본 파일 지도
|
|
+
|
|
+- Workflow와 artifact: [workflow-contracts.yaml](org-os/06-agent-work/workflow-contracts.yaml) · [artifact vocabulary](org-os/06-agent-work/artifact-type-vocabulary.yaml)
|
|
+- 역할과 라우팅: [roles.yaml](org-os/00-role-registry/roles.yaml) · [capability-families.yaml](org-os/00-role-registry/capability-families.yaml)
|
|
+- 권한과 실행: [tool-permission-matrix.yaml](org-os/00-role-registry/tool-permission-matrix.yaml) · [execution-policy.yaml](org-os/06-agent-work/execution-policy.yaml)
|
|
+- 런타임 요구사항: [tool-versions.yaml](.claude/tool-versions.yaml) · [requirements.txt](requirements.txt)
|
|
+- Claude Code 어댑터: [commands](.claude/commands/) · [hooks](.claude/hooks/) · [schemas](.claude/schemas/) · [tests](.claude/tests/)
|
|
+- 실증 자료: [golden tasks](benchmark/golden-tasks.yaml) · [benchmark report](benchmark/BENCHMARK.md)
|
|
+- 설계와 변경 이력: [docs](docs/)
|
|
+
|
|
+README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.
|