init: readme 작성 하네스 설계

2026-07-24 13:26:18 +09:00
parent 7fb4217f7c
commit c708cbcf9a
317 changed files with 24223 additions and 1 deletions
@@ -0,0 +1,413 @@
+--- README.md (current)
+++ README.md (candidate)
+@@ -1,224 +1,211 @@
+ # README Harness
+ 
+-이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+-명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다. <!-- claim-id: C-PROJECT-001 -->
+-
+-- 새 README 작성
+-- 기존 문서 점검
+-- 사람 작성 영역을 보존한 갱신
+-- 특정 섹션과 관련 검증 산출물의 재생성
+-- 검토 후 별도로 실행하는 적용
+-
+<!-- readme-harness:metadata owner=readme-harness -->
+
+저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.
+<!-- claim-id: C-PROJECT-001 -->
+
+명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.
+<!-- claim-id: C-OUTPUT-001 -->
+
+현재 지원하는 작성·검증 흐름은 Codex용입니다. <!-- claim-id: C-CODEX-001 -->
+
+Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.
+<!-- claim-id: C-XTOOL-001 -->
+
+<!-- readme-harness:start overview -->
+ <!-- section-id: overview -->
+ ## 무엇을 만드는가
+ 
+ README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+ 
+-`bootstrap`, `audit`, `refresh`, `section-update` 네 모드를 구현했습니다. <!-- claim-id: C-MODE-001 -->
+-
+-저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을
+-넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인
+-근거를 사용합니다. 패치 준비가 끝나도 대상 `README.md`는 자동으로 바뀌지 않습니다.
+-<!-- claim-id: C-SAFETY-SUMMARY-001 -->
+-
+-결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며,
+-다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.
+-<!-- claim-id: C-LIMIT-001 -->
+-
+-<!-- section-id: installation -->
+-## 설치
+-
+-`Python` 3.12 이상이 필요합니다.
+-런타임 의존성은 `jsonschema`와 `PyYAML`입니다.
+-개발 의존성은 `pytest`입니다. <!-- claim-id: C-RUNTIME-001 -->
+-
+-저장소 루트에서 개발 의존성을 포함한 편집 가능 설치를 실행합니다.
+- 새 README 작성
+- 기존 README 점검
+- 사람 작성 내용을 보존한 갱신
+- 특정 섹션만 다시 작성
+- 검토한 패치만 직접 적용
+
+<!-- readme-harness:end overview -->
+
+<!-- readme-harness:start proof -->
+<!-- section-id: proof -->
+## 실제 결과
+
+아래 내용은 검토를 통과한 이전 실행의 패치 일부입니다.
+<!-- claim-id: C-PROOF-001 -->
+
+```diff
+-A GitHub-README-specialized harness built around a shared core with entrypoints
+-for **Codex**, **Antigravity**, and **Claude**. It does not "prettify" READMEs —
+-it analyzes the facts that exist in a repository, judges project type and
+-audience, then iteratively produces and maintains a README with a readable
++이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
++명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
+```
+
+<!-- visual-id: reviewed-patch-preview -->
+
+[전체 패치와 출처](examples/readme-showcase/README.patch)에서 더 긴 변경 내용을 확인할 수 있습니다.
+
+<!-- readme-harness:end proof -->
+
+<!-- readme-harness:start quick-start -->
+<!-- section-id: quick-start -->
+## 빠른 시작
+
+현재 실행 경로는 Codex 작업 공간의 `requirement-driven-readme` 스킬입니다.
+<!-- claim-id: C-INVOCATION-001 -->
+
+<!-- quick-start-step: invocation -->
+Codex에 다음과 같이 요청합니다.
+
+> 이 저장소의 README를 `bootstrap` 모드로 작성해 주세요.
+> 주 독자는 백엔드 개발자이며, 설치와 첫 실행 방법을 우선해 주세요.
+
+<!-- quick-start-step: expected-result -->
+작업 뒤 확인할 파일은 `README.generated.md`와 `README.patch`입니다.
+<!-- claim-id: C-RESULTS-001 -->
+
+<!-- quick-start-step: success-check -->
+생성된 README의 명령과 링크를 읽고, 패치가 의도한 범위만 바꾸는지 검토합니다.
+
+대상 `README.md`는 적용 명령을 실행하기 전까지 바뀌지 않습니다.
+<!-- claim-id: C-NO-AUTO-APPLY-001 -->
+
+<!-- quick-start-step: apply -->
+검토가 끝난 패치만 직접 적용합니다.
+
+```bash
+python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
+```
+
+적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.
+<!-- claim-id: C-APPLY-CHECK-001 -->
+
+<!-- readme-harness:end quick-start -->
+
+<!-- readme-harness:start usage -->
+<!-- section-id: usage -->
+## 어떤 작업을 지원하는가
+
+새 README 작성과 전면 재작성의 기본 선택은 `bootstrap`입니다.
+<!-- claim-id: C-MODE-BOOTSTRAP-001 -->
+
+현재 README의 문제만 찾는 작업은 `audit`입니다.
+<!-- claim-id: C-MODE-AUDIT-001 -->
+
+사람이 작성한 영역을 보존하는 갱신은 `refresh`입니다.
+<!-- claim-id: C-MODE-REFRESH-001 -->
+
+한 섹션과 영향을 받는 검사 결과의 갱신은 `section-update`입니다.
+<!-- claim-id: C-MODE-SECTION-001 -->
+
+<!-- readme-harness:end usage -->
+
+<!-- readme-harness:start safeguards -->
+<!-- section-id: safeguards -->
+## 안전하게 다루는 방법
+
+코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.
+<!-- claim-id: C-SOURCE-SPLIT-001 -->
+
+명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.
+<!-- claim-id: C-FACT-TRACE-001 -->
+
+갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.
+<!-- claim-id: C-PRESERVE-001 -->
+
+사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.
+<!-- claim-id: C-CONFLICT-001 -->
+
+비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.
+<!-- claim-id: C-SECRET-PATH-001 -->
+
+검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.
+<!-- claim-id: C-STALE-001 -->
+
+<!-- readme-harness:end safeguards -->
+
+<!-- readme-harness:start workflow -->
+<!-- section-id: workflow -->
+## 동작 방식
+
+사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용
+<!-- claim-id: C-WORKFLOW-001 -->
+
+검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.
+<!-- claim-id: C-REWORK-001 -->
+
+<!-- readme-harness:end workflow -->
+
+<!-- readme-harness:start inputs -->
+<!-- section-id: inputs -->
+## 입력과 생성 파일
+
+`readme-request.yaml`에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.
+<!-- claim-id: C-REQUEST-001 -->
+
+사용자는 다음 두 결과를 주로 확인합니다.
+
+- `README.generated.md`: 생성된 README
+- `README.patch`: 현재 README와의 차이
+
+각 작업의 파일은 `runs/<repo-id>/<run-id>` 아래에 따로 저장됩니다.
+<!-- claim-id: C-RUN-DIR-001 -->
+
+<!-- readme-harness:end inputs -->
+
+<!-- readme-harness:start development -->
+<!-- section-id: development -->
+## 개발
+
+개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 `pytest`가 포함됩니다.
+<!-- claim-id: C-DEV-PREREQ-001 -->
+
+저장소 루트에서 개발 모드로 설치합니다.
+ 
+ ```bash
+ python3 -m pip install -e ".[dev]"
+ ```
+ 
+-이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지
+-실행해 증명하지 않았습니다. <!-- claim-id: C-INSTALL-001 -->
+-
+-<!-- section-id: quick-start -->
+-## 빠른 시작
+-
+-먼저 전체 테스트를 실행합니다.
+전체 테스트는 다음 명령으로 실행합니다.
+ 
+ ```bash
+ python3 -m pytest -q
+ ```
+ 
+-종료 코드 0과 실패 항목 없는 통과 요약이 성공 기준입니다. 이 후보는 아직 현재
+-README를 바꾸지 않았으므로 최종 전체 결과는 명시적 적용 뒤 다시 확인합니다.
+-
+-자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새
+-가상환경의 동일한 결과까지 보장하는 계약은 아닙니다. <!-- claim-id: C-TEST-COMMAND-001 -->
+-
+-이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서
+-`requirement-driven-readme` 스킬로 대상 저장소의 `bootstrap` 실행을 요청하면 작성
+-역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사
+-산출물을 준비합니다. <!-- claim-id: C-AUTHORING-001 -->
+-
+-대상 저장소용 실행 디렉터리를 만듭니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/init_run.py --repo-id demo --run-id first --mode bootstrap --target-repository /path/to/repository --tool-adapter codex
+-```
+-
+-이 명령은 `runs/demo/first`에 상태와 실행 매니페스트를 초기화합니다.
+-<!-- claim-id: C-INIT-001 -->
+-
+-실행 디렉터리에 `readme-request.yaml`, `repository-facts.yaml`, `readme-brief.yaml`,
+-`readme-outline.yaml`, `README.candidate.md`, `claim-map.yaml`, `visual-plan.yaml`,
+-`review-findings.yaml`이 준비되면 모든 결정론적 게이트를 재생합니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py --run-dir runs/demo/first --repo /path/to/repository
+-```
+-
+-드라이버는 후보를 새로 쓰지 않고 준비된 산출물을 `QUALITY_REVIEWED`까지
+-검증합니다. <!-- claim-id: C-BOOTSTRAP-001 -->
+-
+-<!-- section-id: usage -->
+-## 사용 모드
+-
+-| 작업 | 모드 | 결과 |
+-|---|---|---|
+-| README가 없거나 전면 재작성 | `bootstrap` | 검증된 후보와 적용 준비용 패치 |
+-| 기존 문서의 결함만 점검 | `audit` | 감사 결과와 검증 보고서, 후보·패치 없음 |
+-| 사람 작성 영역을 보존한 갱신 | `refresh` | 3방향 병합과 병합본 전체 재검증 |
+-| 한 섹션과 파급 산출물 갱신 | `section-update` | 관련 산출물 무효화 후 갱신 검증 재실행 |
+-
+-네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어
+-있습니다. <!-- claim-id: C-USAGE-001 -->
+-
+-<!-- section-id: api -->
+-## 요청 API, 설정과 산출물
+-
+-`readme-request.yaml`은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을
+-정합니다. 기술 사실은 `repository-facts.yaml`에 저장하고, 각 실행은
+-`runs/<repo-id>/<run-id>` 아래에서 격리합니다. <!-- claim-id: C-INPUT-001 -->
+-
+-어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지
+-않은 값은 0으로 추정하지 않습니다. <!-- claim-id: C-USAGE-METRICS-001 -->
+-
+-대표 산출물은 다음 순서로 이어집니다.
+-
+-```text
+-readme-brief.yaml + readme-outline.yaml
+-README.candidate.md + claim-map.yaml + visual-plan.yaml
+-prose-report.json + verification.json + review-findings.yaml
+-quality-manifest.yaml
+-README.generated.md + README.patch + apply-manifest.yaml
+-```
+-
+-품질 검토를 통과한 뒤 다음 명령으로 패치를 준비합니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/generate_patch.py --run-dir runs/demo/first --repo /path/to/repository
+-```
+-
+-이 단계는 `README.generated.md`, `README.patch`, `apply-manifest.yaml`을 만들고
+-상태를 `READY_FOR_APPLY`로 전진시킵니다. <!-- claim-id: C-PREPARE-001 -->
+-
+-검토가 끝난 패치만 별도 명령으로 적용합니다.
+-
+-```bash
+-python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository
+-```
+-
+-적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.
+-<!-- claim-id: C-APPLY-001 -->
+-
+-<!-- section-id: architecture -->
+-## 동작 방식
+-
+-사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는
+-근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적
+-게이트와 독립 품질 심사를 통과해야 패치가 됩니다. <!-- claim-id: C-FLOW-001 -->
+-
+-```mermaid
+-flowchart LR
+-    T[Codex / Claude / Antigravity] --> O[실행 조정]
+-    U[사용자 요구] --> P[독자 흐름·용어·그림 결정]
+-    R[대상 저장소] --> E[근거 수집·프로젝트 분류]
+-    O --> E
+-    O --> P
+-    E --> P
+-    P --> W[README 작성]
+-    P --> V[그림 소스·자산 생성]
+-    W --> G[근거·명령·경로·문체 검사]
+-    V --> G
+-    G --> Q[독립 품질 심사]
+-    Q -->|수정 필요| P
+-    Q -->|통과| A[패치 준비·명시적 적용]
+-    H[(해시 기반 실행 산출물)] --- E
+-    H --- P
+-    H --- G
+-    H --- A
+-```
+-
+-<!-- visual-id: harness-flow -->
+-
+-구성요소 책임과 컨텍스트 경계는 [아키텍처 문서](docs/architecture.md)에,
+-모드별 전이는 [상태기계 문서](docs/state-machine.md)에 정리했습니다.
+-
+-<!-- section-id: safeguards -->
+-## 안전장치
+-
+-- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.
+-- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을
+-  차단합니다. <!-- claim-id: C-TERM-001 -->
+-- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이
+-  일치해야 시각 자료 게이트를 통과합니다. <!-- claim-id: C-VISUAL-001 -->
+-- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,
+-  `review.md`는 검증된 YAML에서 렌더링합니다. <!-- claim-id: C-REVIEW-001 -->
+-- 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로
+-  전진합니다. <!-- claim-id: C-AUDIT-001 -->
+-- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새
+-  후보가 충돌하면 자동 적용을 막습니다. <!-- claim-id: C-MERGE-001 -->
+-- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나
+-  적용을 차단합니다. <!-- claim-id: C-APPLY-SAFETY-001 -->
+-
+-시각 자료의 소스·자산·대체 텍스트·신선도 규칙은
+-[시각 자료 정책](docs/visuals.md)에서 확인할 수 있습니다.
+-
+-<!-- section-id: tests -->
+-## 테스트
+-
+-전체 회귀 테스트는 다음 명령으로 실행합니다.
+-
+-```bash
+-python3 -m pytest -q
+-```
+-
+-GitHub Actions는 의존성을 설치한 뒤 전체 테스트를 실행합니다. 실행 환경은
+-Python 3.12입니다. 자체 README 테스트는 라이브러리 프로파일, 30초 독자 흐름, 최소 실행
+-경로, Mermaid 그림 결정을 확인합니다. <!-- claim-id: C-CI-001 -->
+-
+<!-- readme-harness:end development -->
+
+<!-- readme-harness:start documentation -->
+ <!-- section-id: documentation -->
+ ## 상세 문서
+ 
+-- [구성요소와 컨텍스트 경계](docs/architecture.md)
+-- [그림 결정과 소스·자산 계약](docs/visuals.md)
+-- [모드별 상태와 차단 조건](docs/state-machine.md)
+-- [모델 사용량 계측](docs/usage-metrics.md)
+-- [블라인드 README 품질 벤치마크](docs/quality-benchmark.md)
+- [구성요소와 책임](docs/architecture.md)
+- [시각 자료와 실제 결과 증명](docs/visuals.md)
+- [모드별 처리 단계와 차단 조건](docs/state-machine.md)
+- [모델 사용량 기록](docs/usage-metrics.md)
+- [블라인드 README 품질 비교](docs/quality-benchmark.md)
+ - [전체 설계 명세](docs/superpowers/specs/2026-07-16-readme-harness-design.md)
+ 
+-주요 구현은 `src/readme_harness`, 스키마·규칙·워크플로는 `.agents`, 테스트는
+-`tests`에 있습니다. <!-- claim-id: C-LAYOUT-001 -->
+-
+주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.
+<!-- claim-id: C-LAYOUT-001 -->
+
+<!-- readme-harness:end documentation -->
+
+<!-- readme-harness:start limitations -->
+ <!-- section-id: limitations -->
+ ## 현재 한계
+ 
+-- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된
+-  산출물을 검증하고 상태를 전진시킵니다.
+-- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증
+-  목표입니다. <!-- claim-id: C-LIMIT-002 -->
+-- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은
+-  명령은 실제 실행 성공을 뜻하지 않습니다. <!-- claim-id: C-VERIFY-LIMIT-001 -->
+-- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직 `not-run`입니다.
+-  `PASS` 결과 전에는 품질 우월성을 주장하지 않습니다. <!-- claim-id: C-BENCH-LIMIT-001 -->
+- README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.
+  <!-- claim-id: C-WRITING-LIMIT-001 -->
+
+- 실행 기록이 없는 명령은 정적으로만 확인합니다.
+  <!-- claim-id: C-VERIFY-LIMIT-001 -->
+
+- `Claude`와 `Antigravity`에서 `Codex`와 같은 동작을 하는지는 아직 검증하지 않았습니다.
+  <!-- claim-id: C-XTOOL-LIMIT-001 -->
+
+- 블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다.
+  <!-- claim-id: C-BENCH-LIMIT-001 -->
+
+<!-- readme-harness:end limitations -->