schema-version: 1 sections: - id: overview title-guidance: 프로젝트 정체성과 대상 독자를 한 화면에서 판단시키는 제목 level: 2 purpose: 저장소가 무엇을 운영하는 물건인지, 어떤 독자를 위한 것인지, 어느 런타임에 묶여 있는지를 즉시 판단시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 파일 기반 에이전트 운영 하네스라는 구체적 정의와 org-os 디렉터리가 정본이라는 사실 - 개발과 비즈니스를 함께 다루는 적용 범위 - Claude Code 단일 어댑터에 묶여 있다는 전제 조건을 초반에 노출 - 1차·2차 독자 구분과 각자가 이 문서에서 얻을 결과 - 문서에 실린 검증 결과가 워킹 트리 기준이라는 범위 고지를 개요 단계에서 한 번 선언 visual-slot: decision: exclude reader-question: 프로젝트 정체성을 파악하는 데 그림이 필요한가? rationale: 정체성은 정의문과 범위 문장으로 전달되며, 그림을 두면 유일한 시각물 예산을 판단이 아니라 인상에 소모한다. - id: operating-model title-guidance: 이 하네스가 프롬프트 모음과 다른 이유를 설명하는 제목 level: 2 purpose: 계약·상태·증거·권한이 어떻게 결합되어 강제로 작동하는지를 원리 수준에서 설명한다. required: true content-strategy: inline target-doc: null content-requirements: - workflow-contracts가 단계·역할 권한·산출물 kind·exit gate를 한 그래프로 정의한다는 원칙 - 상태 런타임이 caller 제출값을 신뢰하지 않고 불변 바이트에서 파생한다는 신뢰 규칙 - fan-out과 collapse의 구분 기준, 그리고 오케스트레이터만 fan-out한다는 제약 - 증거 등급과 receipt 대조로 근거 없는 주장이 차단되는 경로 - 1차 경계는 네이티브 permission이고 guard 훅은 2차 방어선이라는 구분 visual-slot: decision: exclude reader-question: 계약·상태·증거의 결합을 이해하는 데 구조도가 필요한가? rationale: 네다섯 개의 독립 원칙을 나열하는 성격이라 항목별 목록이 더 정확하고, 흐름도로 그리면 실제보다 단일 파이프라인처럼 오해된다. - id: quick-start title-guidance: 최소 사용 절차를 처음부터 끝까지 잇는 제목 level: 2 purpose: 설치부터 workspace 지정, 배선 확인, 첫 명령 실행까지의 최단 경로를 끊김 없이 제공한다. required: true content-strategy: inline target-doc: null content-requirements: - 절차를 순서가 있는 단계로 제시하고 각 단계의 성공 신호를 함께 제시 - 각 명령의 검증 수준을 quick-start 안에서 과장 없이 표기 visual-slot: decision: exclude reader-question: 설치와 첫 실행 순서를 이해하는 데 그림이 필요한가? rationale: 복사 가능한 명령 블록과 기대 출력이 가장 직접적이며, 순서 자체는 번호 목록으로 충분하다. children: - id: prerequisites title-guidance: 필수 도구와 선택 도구를 구분하는 제목 level: 3 purpose: 어떤 도구가 없으면 동작하지 않고 어떤 도구가 없으면 기능만 줄어드는지를 구분시킨다. required: true content-strategy: inline target-doc: null content-requirements: - Python과 PyYAML의 최소·검증 버전 - 권장 도구와 각 도구가 필요한 기능 경로 - 선택 도구 부재 시의 대체 경로 - 버전 대조를 수행하는 진입점 - id: workspace-setup title-guidance: workspace 지정 규칙을 다루는 제목 level: 3 purpose: 산출물이 어디에 쓰일지를 결정하는 workspace 해석 규칙과 미설정 시 동작을 확정시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 환경변수와 포인터 파일의 우선순위, 상대·절대 경로 해석 규칙 - 미해석 시 fail-closed 훅과 advisory 훅의 동작 차이 - 테스트·CI에서 sandbox workspace를 명시하는 관례 - 현재 포인터가 채워져 있어 미설정이 곧바로 실패로 이어지지 않는다는 주의 - id: first-command title-guidance: 첫 실행과 확인을 다루는 제목 level: 3 purpose: 설치가 끝난 독자가 실제로 실행할 첫 명령과 그 판정 기준을 제시한다. required: true content-strategy: inline target-doc: null content-requirements: - 배선 점검 진입점과 성공 판정 문구 - 모든 workflow의 공통 진입 명령과 그 산출물 - 진입 게이트가 요구하는 선행 조건 - id: workflows title-guidance: 작업 성격에 맞는 workflow를 고르게 하는 제목 level: 2 purpose: 다섯 개 workflow plan을 진입점·단계·종단 상태·사람 승인 지점 기준으로 구분해 독자가 하나를 선택하게 한다. required: true content-strategy: inline target-doc: null content-requirements: - 공통 진입점과 plan 선언 방식 - plan별 선택 기준을 판단 가능한 조건으로 제시 - 명령 총수와 그중 workflow 진입점의 위치 관계 - 각 plan의 종단 상태와 사람 승인이 개입하는 지점 visual-slot: decision: include reader-question: 나는 어떤 workflow를 골라야 하고, 고른 경로는 어떤 단계를 거쳐 어디서 끝나며 사람이 승인하는 지점은 어디인가? rationale: 다섯 경로가 하나의 진입점을 공유하면서 단계 수·종단 상태·부모 종속 관계가 서로 다른 분기 구조라 산문이나 표로는 비교가 어렵다. 독자가 이 문서에서 실제로 내리는 유일한 선택이므로 하나뿐인 시각물 예산을 여기에 쓴다. purpose: 공통 진입점에서 갈라지는 plan 분기와 각 경로의 단계 진행·종단 상태·사람 승인 지점을 한 화면에서 비교시켜 독자가 자기 작업에 맞는 경로를 고르게 한다. children: - id: workflow-cascade title-guidance: 표준 전체 경로를 다루는 제목 level: 3 purpose: 가장 긴 표준 경로의 단계 순서와 각 단계 산출물, 재작업 전이를 정확히 전달한다. required: true content-strategy: inline target-doc: null content-requirements: - 단계 순서를 정본 그대로 제시하고 통념과 다른 순서를 명시 - 단계별 명령과 산출물의 대응 - 종단 단계의 exit gate 구성 - 품질 게이트 실패 시의 재작업 전이 visual-slot: decision: exclude reader-question: 여덟 단계 진행을 별도 그림으로 보여야 하는가? rationale: 상위 섹션의 유일한 시각물이 이미 단계 진행과 승인 지점을 담고, 단계별 명령과 산출물의 정확한 대응은 표가 더 정밀하다. - id: workflow-wave-light title-guidance: 축약 경로 두 가지를 비교하는 제목 level: 3 purpose: 표준 경로를 줄인 두 경로가 무엇을 생략하고 어떤 작업에 적합한지를 판단시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 두 경로의 단계 구성과 생략된 단계 - 반복 단계와 종단 단계의 차이 - 축약 경로를 적용해도 되는 작업 조건 - 기본 tier 차이 - id: workflow-venture title-guidance: 회사 수립 경로를 다루는 제목 level: 3 purpose: 사람 입력이 선행되어야 하는 경로임을 밝히고 입력·출력·현재 상태를 연결한다. required: true content-strategy: inline target-doc: null content-requirements: - 진입 명령과 후속 명령 순서 - 사람이 채워야 하는 입력 파일과 요구 상태 - 산출 파일과 상태 어휘 - 현재 산출물이 잠정 상태라는 사실과 그 결과 - id: workflow-design-direction title-guidance: 제품 경로에 종속된 디자인 방향 결정 경로를 다루는 제목 level: 3 purpose: 이 경로가 독립 워크플로가 아니라 부모 결정에 결속된 child workflow임을 이해시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 부모 워크플로와의 결속 키 - 발산에서 승인까지의 단계 흐름과 두 종류의 재작업 전이 - 최종 산출물과 승인 payload가 해시로 고정된다는 점 visual-slot: decision: exclude reader-question: 이 child workflow의 단계와 비평 루프를 별도 그림으로 보여야 하는가? rationale: 시각물 한도가 1이고 상위 선택 문제보다 우선순위가 낮다. 두 개의 재작업 전이는 조건과 함께 문장으로 적는 편이 오해가 적다. - id: workflow-specialized title-guidance: 상태 전이를 하지 않는 보조 진입점들을 묶는 제목 level: 3 purpose: workflow plan이 아닌 전문 명령들의 용도와 경계를 짧게 구분시킨다. required: true content-strategy: summary-link target-doc: .claude/commands/ content-requirements: - 명령별 한 줄 용도와 상태 전이 여부 - 검토 명령의 생산자·검토자 분리 강제 - 전체 경로 드라이버가 사람 게이트에서 정지한다는 제약 - 상세 사용법은 명령 정의 파일로 링크 - id: repo-map title-guidance: 규칙의 원본과 실행 코드가 어디에 나뉘는지 보여주는 제목 level: 2 purpose: 주요 디렉터리의 책임을 구분해 독자가 읽을 위치와 고칠 위치를 찾게 한다. required: true content-strategy: inline target-doc: null content-requirements: - 정본 규칙 계층과 런타임 어댑터 계층의 구분 - 생성물 디렉터리와 원본 디렉터리의 구분 - 벤치마크·문서·워크스페이스 디렉터리의 역할 - 채워지지 않은 stub 폴더를 구조 설명 안에서 표시 visual-slot: decision: exclude reader-question: 디렉터리 책임을 파악하는 데 구조도가 필요한가? rationale: 경로와 책임을 1대1로 짝짓는 탐색용 정보라 표가 그림보다 정확하고, 시각물 한도는 선택 문제에 이미 배정됐다. children: - id: repo-map-orgos title-guidance: 정본 규칙 계층을 다루는 제목 level: 3 purpose: 역할·계약·회사 문맥의 원본이 어디에 있는지 확정시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 역할 registry와 family·lens 구성의 규모 - workflow·artifact 계약 파일의 위치와 mirror 파일의 지위 - 회사 문맥 디렉터리와 그 현재 상태 - 컴파일된 artifact registry의 규모와 생성 경로 - id: repo-map-claude title-guidance: 런타임 어댑터 계층을 다루는 제목 level: 3 purpose: 명령·에이전트 카드·훅·스키마·테스트의 위치와 생성 관계를 구분시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 명령·카드·skill·훅·스키마·테스트의 개수와 책임 - 에이전트 카드가 생성물이며 수기 편집 금지 대상이라는 규칙 - 훅 배선 지점과 각 훅의 실패 정책 - 이 어댑터가 유일하며 다른 런타임 어댑터는 없다는 사실 - id: artifacts title-guidance: 실행 결과와 증거가 남는 위치를 다루는 제목 level: 2 purpose: 산출물·증거·상태의 저장 위치와 불변성 규칙을 확정시킨다. required: true content-strategy: inline target-doc: null content-requirements: - workspace 아래 표준 디렉터리 구성 - 보고서 경로 규칙과 덮어쓰기 금지 정책 - 실행 receipt에 기록되는 항목 - 사람이 읽는 렌더 산출물과 대시보드의 위치 visual-slot: decision: exclude reader-question: 산출물 위치를 찾는 데 그림이 필요한가? rationale: 경로 탐색 문제라 작은 디렉터리 트리와 설명이면 충분하고 그림은 정보를 늘리지 않는다. children: - id: workspace-resolution title-guidance: 산출물이 쓰일 위치가 결정되는 방식을 다루는 제목 level: 3 purpose: 같은 명령이 어디에 쓰는지를 결정하는 해석 규칙과 현재 트리의 실제 값을 연결한다. required: true content-strategy: inline target-doc: null content-requirements: - 해석 우선순위와 포인터 파싱 규칙 - 현재 트리에 존재하는 워크스페이스와 각각의 용도 - 테스트용과 제품용 워크스페이스의 분리 - id: output-locations title-guidance: 산출물 종류별 저장 위치를 다루는 제목 level: 3 purpose: 독자가 찾는 결과물의 종류에 따라 정확한 경로로 이동시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 완료 기록·증거·보고서·상태·인박스 경로의 대응 - append-only 이벤트 원장과 파생 뷰의 구분 - 재생성 가능한 파일과 원장의 구분 - 대시보드가 측정값과 수기값을 구분 표기한다는 규칙 - id: verification title-guidance: 검증 명령과 그 결과를 어디까지 믿을 수 있는지 다루는 제목 level: 2 purpose: 저장소가 제공하는 검증 수단을 목적별로 제시하고 각 결과의 검증 수준을 명시한다. required: true content-strategy: inline target-doc: null content-requirements: - 목적·명령·성공 신호·검증 수준을 짝지어 제시 - 실행되지 않은 명령과 실행된 명령을 표기상 구분 - 실행 결과가 워킹 트리 기준이라는 범위 고지 visual-slot: decision: exclude reader-question: 검증 명령을 고르는 데 그림이 필요한가? rationale: 목적·명령·성공 신호·수준의 네 축을 짝짓는 정보라 표가 유일하게 정확한 형식이다. children: - id: verify-commands title-guidance: 로컬 검증 진입점을 다루는 제목 level: 3 purpose: 배선 점검·참조 무결성·생성 계약·전체 스위트를 각각 언제 쓰는지 구분시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 전체 스위트 진입점과 preflight 구성, 실패 계약 - 배선 점검이 확인하는 영역과 판정 형식 - 생성 계약 점검의 범위와 그 점검이 확인하지 않는 것 - 참조 무결성 점검의 대상 수 - id: verify-ci title-guidance: 자동 검증 경로를 다루는 제목 level: 3 purpose: 어떤 검증이 자동으로 반복되는지와 그 실행 조건을 알린다. required: true content-strategy: inline target-doc: null content-requirements: - 트리거 조건과 실행 환경 설정 - 실행 단계 목록과 로컬 명령과의 대응 - 실패해도 넘어가는 선택 단계 - 이번 분석에서 실행 이력을 조회하지 않았다는 범위 고지 - id: verify-levels title-guidance: 검증 수준의 등급을 정의하는 제목 level: 3 purpose: 저장소가 선언한 명령, 분석자가 임시로 실행한 결과, 하네스 게이트를 통과한 결과를 서로 다른 신뢰 등급으로 구분시킨다. required: true content-strategy: inline target-doc: null content-requirements: - 세 등급의 정의와 각 등급에 해당하는 실제 사례 - 이번 문서의 실행 결과가 하네스 게이트를 통과한 것이 아니라는 사실 - 등급 표기를 다른 섹션의 명령에도 일관 적용한다는 약속 - id: evidence-status title-guidance: 품질 우위 주장의 근거가 지금 어디까지 있는지 밝히는 제목 level: 2 purpose: 벤치마크 인프라의 존재와 실증 결과의 부재를 분리해, 독자가 하네스의 우위를 입증된 것으로 오해하지 않게 한다. required: true content-strategy: inline target-doc: null content-requirements: - 측정 도구가 있다는 사실과 측정이 끝났다는 사실을 문장 단위로 분리 - 우위 주장이 아직 성립하지 않는다는 결론을 명시적으로 진술 - 비교 우위·생산성 향상 표현을 사용하지 않는다는 제약 준수 visual-slot: decision: exclude reader-question: 근거 상태를 이해하는 데 도표가 필요한가? rationale: 결과가 전부 동률이거나 부재라 시각화할 신호 자체가 없고, 차트는 없는 신호를 있는 것처럼 보이게 한다. children: - id: bench-golden title-guidance: 과제 단위 비교 벤치마크의 현재 표본을 다루는 제목 level: 3 purpose: 정의된 과제 수와 실제 실행 표본의 격차, 그리고 관측된 동률 결과를 정확히 전달한다. required: true content-strategy: inline target-doc: null content-requirements: - 정의된 과제 수와 실행된 표본 수의 대비 - 표본이 한 카테고리·저난도에 몰려 있다는 사실 - 측정된 지표 수와 미측정 지표 수 - 관측된 차이가 없다는 결과와 그로부터 도출되는 결론 - 비교 보고 파일이 재생성물이라는 점 - id: bench-cascade title-guidance: 워크플로 단위 비교 인프라의 구현 상태를 다루는 제목 level: 3 purpose: 측정 인프라가 만들어졌으나 파일럿이 실행되지 않았다는 상태를 오해 없이 전달한다. required: true content-strategy: inline target-doc: null content-requirements: - 비교 대상 arm 구성과 고정 방식 - 배선된 서브커맨드와 미구현 서브커맨드의 구분 및 종료 코드 - 실행 산출물이 저장소에 없다는 사실 - 공정성 통제 장치와 예산 게이트의 존재 - 파일럿이 통계적 우월성을 확정하지 않는다는 명시된 단서 - 설계에서 의도적으로 미룬 항목들 - id: limitations title-guidance: 도입 전에 받아들여야 할 현재 한계를 모으는 제목 level: 2 purpose: 강제 경계, 상태 불일치, 미완성 계층을 근거와 영향으로 연결해 과장 없이 밝힌다. required: true content-strategy: inline target-doc: null content-requirements: - 워킹 트리와 추적본의 차이가 독자에게 미치는 영향 - 강제가 특정 런타임 세션 조건에서만 성립한다는 경계 - 2차 방어선의 자기 선언된 취약성 - 회사 문맥의 잠정 상태와 미해결 입력이 결정에 주는 제약 - 비어 있는 문맥 폴더와 저장소 내부 문서 불일치 - 워크스페이스 포인터가 채워져 fail-closed가 약해진 현재 상태 - 자동 판정 범위 밖에 있는 품질 영역과 외부 도구 의존 - 각 한계를 근거 위치와 함께 한 줄씩 제시 visual-slot: decision: exclude reader-question: 한계를 전달하는 데 시각화가 필요한가? rationale: 한계는 근거와 영향을 짝지어 읽어야 하는 정보이고, 도식화는 개별 항목의 정확도를 떨어뜨린다. - id: contributing title-guidance: 기여자가 무엇을 고치고 무엇을 재생성하는지 안내하는 제목 level: 2 purpose: 원본과 생성물을 구분해 잘못된 위치를 수정하는 기여를 막는다. required: false content-strategy: inline target-doc: null content-requirements: - 생성물 디렉터리를 직접 수정하지 말라는 규칙과 올바른 수정 위치 - 규칙 변경 후 재생성·재검증에 사용할 명령 순서 - 변경이 통과해야 하는 자동 검증 항목 - 계약 활성화 기록에 남는 항목 visual-slot: decision: exclude reader-question: 기여 절차를 이해하는 데 그림이 필요한가? rationale: 원본에서 생성물로 이어지는 짧은 선형 절차라 번호 목록이면 충분하다. - id: reference title-guidance: 계약 원본과 상세 문서로 이동시키는 제목 level: 2 purpose: 세부 내용을 본문에 복제하지 않고 목적별로 정본 파일에 연결한다. required: false content-strategy: summary-link target-doc: null content-requirements: - 워크플로·역할·권한·실행 정책 정본 파일 링크 - 명령·훅·스키마·테스트 디렉터리 링크 - 벤치마크 정의와 정책 파일 링크 - 각 링크에 한 줄 용도만 붙이고 내용은 복제하지 않음 visual-slot: decision: exclude reader-question: 정본 파일을 찾는 데 그림이 필요한가? rationale: 목적별 링크 목록이 탐색과 유지보수에 가장 적합하다. children: - id: design-history title-guidance: 설계 이력 문서로만 연결하는 제목 level: 3 purpose: 설계 spec과 구현 plan의 존재만 알리고 본문 복제를 차단한다. required: false content-strategy: external-only target-doc: docs/superpowers/ content-requirements: - spec과 plan 디렉터리의 역할 구분만 제시 - 개별 문서 내용의 요약이나 인용은 하지 않음 - id: license title-guidance: 사용·재배포 조건의 현재 상태를 밝히는 제목 level: 2 purpose: 라이선스 파일의 부재라는 관측 사실만 전달하고 조건을 추정하지 않게 한다. required: false content-strategy: inline target-doc: null content-requirements: - 저장소 루트에 라이선스 파일이 없다는 관측 사실 - 허용 범위를 추정하거나 특정 라이선스를 암시하지 않음