# Org OS 하네스 — Claude Code용 에이전트 운영체계
Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다.
이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다.
## 무엇을 제공하나요?
일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다.
이 하네스가 연결하는 범위는 다음과 같습니다.
- 역할과 family를 이용한 작업 라우팅
- 단계별 입력·출력 artifact와 검토 권한
- 상태 전이 전 exit gate와 사람 승인
- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
- 프로젝트별 report·evidence·state 저장소
## 핵심 운영 모델
1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다.
2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다.
3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다.
4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다.
Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다.
## 시작하기
### 1. 필수 도구 확인
핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다.
저장소 루트에서 의존성을 설치합니다.
```bash
pip install -r requirements.txt
```
### 2. 워크스페이스 지정
산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다.
저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
```bash
export ORGOS_WORKSPACE=_sandbox
python3 .claude/hooks/doctor.py
```
`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다.
### 3. 첫 워크플로 시작
Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다.
## 작업에 맞는 워크플로 선택
| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|---|---|---|
| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` |
| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` |
| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` |
| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` |
`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다.
다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다.
```mermaid
flowchart LR
A["intake
/ceo-intake"] --> B["discovery
/ground"]
B --> C["decide
/decide"]
C --> D{"사람 방향 수용"}
D --> E["design
/design"]
E --> F["spec
/spec"]
F --> G["build
/build"]
G --> H["verification
/review-output"]
H --> I["acceptance
/release-check"]
I --> J{"사람 release 승인"}
J --> K["released"]
```
## 저장소 구조와 책임
실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다.
| 경로 | 책임 |
|---|---|
| `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/` | 설계·계획·감사 이력 |
현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다.
기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오.
## 워크스페이스와 산출물
`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다.
```text
/
├── completion-records// # 불변 .report.yaml과 사람용 .md
├── evidence/ # 실행·파일 receipt와 근거
├── reports/ # INDEX와 사람이 읽는 집계 뷰
├── state/ # workflow·artifact·acceptance event
├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
```
report는 `/completion-records//-.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다.
## 검증 방법과 증거 수준
다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|---|---|---|
| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 |
| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 |
| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 |
| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 |
`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다.
GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다.
벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다.
## 현재 상태와 한계
- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다.
- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다.
- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다.
- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다.
- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다.
## 정본 파일 지도
- 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는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.