donghyeon.kang/readme-haness

Fork 0

Files

T

DongHyeonka c708cbcf9a init: readme 작성 하네스 설계

2026-07-24 13:26:18 +09:00

14 KiB

Raw Blame History

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 저장소

핵심 운영 모델

계약이 실행보다 먼저입니다. workflow-contracts.yaml이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 state_engine.py가 그 그래프를 읽습니다.
판단과 구현의 협업 방식이 다릅니다. 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다.
중요 결정은 자동 완주하지 않습니다. 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다.
결과보다 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을 고정합니다.

저장소 루트에서 의존성을 설치합니다.

pip install -r requirements.txt

2. 워크스페이스 지정

산출물 경로는 ORGOS_WORKSPACE 환경변수를 먼저 사용하고, 없으면 .orgos-workspace의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다.

저장소 자체를 점검할 때는 테스트용 _sandbox를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.

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와 사람 결정 경계를 요약합니다.

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"]

저장소 구조와 책임

실행 그래프의 정본은 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 아래에는 실행 결과와 상태가 다음처럼 분리됩니다.

<workspace>/
├── completion-records/<workflow>/  # 불변 .report.yaml과 사람용 .md
├── evidence/                       # 실행·파일 receipt와 근거
├── reports/                        # INDEX와 사람이 읽는 집계 뷰
├── state/                          # workflow·artifact·acceptance event
├── slack-inbox/ · slack-outbox/    # 승인 정책을 따르는 알림 큐
└── design-system/                  # 해당 프로젝트에 UI 산출물이 있을 때

report는 <workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.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 · artifact vocabulary
역할과 라우팅: roles.yaml · capability-families.yaml
권한과 실행: tool-permission-matrix.yaml · execution-policy.yaml
런타임 요구사항: tool-versions.yaml · requirements.txt
Claude Code 어댑터: commands · hooks · schemas · tests
실증 자료: golden tasks · benchmark report
설계와 변경 이력: docs

README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.

14 KiB Raw Blame History