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