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,211 @@
+# README Harness
+
+<!-- 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를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
+
+- 새 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]"
+```
+
+전체 테스트는 다음 명령으로 실행합니다.
+
+```bash
+python3 -m pytest -q
+```
+
+<!-- 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/superpowers/specs/2026-07-16-readme-harness-design.md)
+
+주요 구현은 `src/readme_harness`, 규칙과 워크플로는 `.agents`, 테스트는 `tests`에 있습니다.
+<!-- claim-id: C-LAYOUT-001 -->
+
+<!-- readme-harness:end documentation -->
+
+<!-- readme-harness:start limitations -->
+<!-- section-id: limitations -->
+## 현재 한계
+
+- 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 -->
@@ -0,0 +1,147 @@
+schema-version: 1
+claims:
+  - id: C-PROJECT-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-PROJECT-001}]
+    status: supported
+  - id: C-OUTPUT-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-VERIFY-001}, {fact-id: F-OUTPUT-001}]
+    status: supported
+  - id: C-CODEX-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-XTOOL-001
+    type: factual
+    section: document
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-PROOF-001
+    type: factual
+    section: proof
+    sources: [{fact-id: F-PROOF-001}]
+    status: supported
+  - id: C-INVOCATION-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-RESULTS-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-OUTPUT-001}]
+    status: supported
+  - id: C-NO-AUTO-APPLY-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-APPLY-CHECK-001
+    type: factual
+    section: quick-start
+    sources: [{fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-MODE-BOOTSTRAP-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-OUTPUT-001}]
+    status: supported
+  - id: C-MODE-AUDIT-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-AUDIT-001}]
+    status: supported
+  - id: C-MODE-REFRESH-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-REFRESH-001}]
+    status: supported
+  - id: C-MODE-SECTION-001
+    type: factual
+    section: usage
+    sources: [{fact-id: F-MODES-001}, {fact-id: F-SECTION-001}]
+    status: supported
+  - id: C-SOURCE-SPLIT-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-AUTHORITY-001}]
+    status: supported
+  - id: C-FACT-TRACE-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-CLAIM-001}, {fact-id: F-VERIFY-001}]
+    status: supported
+  - id: C-PRESERVE-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-REFRESH-001}]
+    status: supported
+  - id: C-CONFLICT-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-REFRESH-001}]
+    status: supported
+  - id: C-SECRET-PATH-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-SAFETY-001}]
+    status: supported
+  - id: C-STALE-001
+    type: factual
+    section: safeguards
+    sources: [{fact-id: F-SAFETY-001}, {fact-id: F-APPLY-001}]
+    status: supported
+  - id: C-WORKFLOW-001
+    type: factual
+    section: workflow
+    sources: [{fact-id: F-WORKFLOW-001}]
+    status: supported
+  - id: C-REWORK-001
+    type: factual
+    section: workflow
+    sources: [{fact-id: F-WORKFLOW-001}]
+    status: supported
+  - id: C-REQUEST-001
+    type: factual
+    section: inputs
+    sources: [{fact-id: F-AUTHORITY-001}, {fact-id: F-REPO-LAYOUT-001}]
+    status: supported
+  - id: C-RUN-DIR-001
+    type: factual
+    section: inputs
+    sources: [{fact-id: F-RUN-LAYOUT-001}]
+    status: supported
+  - id: C-DEV-PREREQ-001
+    type: factual
+    section: development
+    sources: [{fact-id: F-RUNTIME-001}]
+    status: supported
+  - id: C-LAYOUT-001
+    type: factual
+    section: documentation
+    sources: [{fact-id: F-REPO-LAYOUT-001}]
+    status: supported
+  - id: C-WRITING-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-VERIFY-001}]
+    status: supported
+  - id: C-VERIFY-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-VERIFY-001}]
+    status: supported
+  - id: C-XTOOL-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-CODEX-001}]
+    status: supported
+  - id: C-BENCH-LIMIT-001
+    type: factual
+    section: limitations
+    sources: [{fact-id: F-BENCH-001}]
+    status: supported
@@ -0,0 +1,16 @@
+{
+  "schema-version": 1,
+  "policy-id": "korean-reader-prose-v1",
+  "language": "ko-KR",
+  "applicable": true,
+  "scope": "candidate",
+  "state": "PASS",
+  "summary": {
+    "errors": 0,
+    "warnings": 0,
+    "sentences": 52,
+    "prose-characters": 1196,
+    "hangul-characters": 1007
+  },
+  "findings": []
+}
@@ -0,0 +1,123 @@
+schema-version: 1
+verdict: NEEDS_FIX
+score: 90
+scores:
+  project-specificity:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: quick-start
+        line-start: 56
+        line-end: 83
+        content-hash: sha256:1f849db919339542195b10e26c2db6028e2acfdc0c057fcddc8cc535932c829d
+        observation: Codex 스킬 식별자, 생성 파일, 명시적 적용 명령과 적용 전 재확인을 프로젝트 고유 경로로 연결한다.
+  reader-journey:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 16
+        line-end: 85
+        content-hash: sha256:588e0fa1ad93f95c3f945ad2a8c7dcceeb414c77dd6395048955568c783a0540
+        observation: 사용자 결과, 대표 패치, Codex 요청, 생성 파일 확인, 성공 점검, 직접 적용 순서로 이어진다.
+  technical-explanation:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 105
+        line-end: 125
+        content-hash: sha256:a4bd099a77602b1510fad18ef3023498c8c6c3efb700a2d4ebdf67a1182c0f0e
+        observation: 근거 분리, 추적, 보존, 충돌·비밀·변경 차단 책임을 결과 중심으로 구분한다.
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 129
+        line-end: 137
+        content-hash: sha256:47be1e061b740eb6e3acd12179b0420cb0a3c5a6df4f599df30adbb3662dd04e
+        observation: 처리 흐름과 재작성 동작을 짧게 설명하고 상세 책임은 별도 문서로 보낸다.
+  task-usability:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: quick-start
+        line-start: 56
+        line-end: 83
+        content-hash: sha256:1f849db919339542195b10e26c2db6028e2acfdc0c057fcddc8cc535932c829d
+        observation: 요청 예시부터 결과 파일 확인과 적용까지 한 절에서 수행할 수 있다.
+  prose-clarity:
+    score: 4
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 5
+        line-end: 14
+        content-hash: sha256:c0843d3bcaf94929872e5e7ab675f77b9bbbaf66d50e8c61b6ce7d478e11c617
+        observation: 첫 문장부터 결과와 근거를 직접 밝히고 지원 범위와 미검증 범위를 분리한다.
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 195
+        line-end: 209
+        content-hash: sha256:93ace992f3430bfc7395d56e231a9c9892f959b7311d1da91f7296a8aefc29cd
+        observation: 모델 작성, 정적 확인, 도구 간 동작, 품질 비교의 한계를 짧은 항목으로 분리한다.
+  visual-judgment:
+    score: 5
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 30
+        line-end: 48
+        content-hash: sha256:ad44797cc7abc92964f888bccafdc54cc71358f07057234f9975d728d91e4927
+        observation: 대표 패치를 내부 구조보다 먼저 보여 주고 전체 패치 경로를 연결한다.
+hard-gates:
+  passed: false
+  failures: [unsupported-high-risk-claim]
+reader-simulations:
+  30-seconds:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 1
+        line-end: 14
+        content-hash: sha256:5b23dc0b21cf361bff806f69c8ed0e527528daefd523cca4ffe17ff9d3674196
+        observation: README 초안과 패치를 만드는 도구라는 점과 현재 Codex 범위를 첫 화면에서 확인한다.
+  5-minutes:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 52
+        line-end: 139
+        content-hash: sha256:002ddd5d129170e198da9c5f2b202b0b1c35e01bcefcbfe6bd3df070c04cec7e
+        observation: 최소 사용자 경로, 네 가지 모드, 안전장치와 전체 처리 흐름을 찾을 수 있다.
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 195
+        line-end: 209
+        content-hash: sha256:93ace992f3430bfc7395d56e231a9c9892f959b7311d1da91f7296a8aefc29cd
+        observation: 검증 수준, 도구 간 동일 동작과 품질 우월성의 한계를 확인할 수 있다.
+  contributor:
+    outcome: PASS
+    evidence:
+      - artifact: README.candidate.md
+        section-id: document
+        line-start: 158
+        line-end: 191
+        content-hash: sha256:5dd4d4f75a0efbc470683bc6c995acdf3084d7416dccd012ff6bd7fe47b0b4f7
+        observation: Python 전제조건, 개발 설치와 테스트 명령, 구현·규칙·테스트 위치를 찾을 수 있다.
+findings:
+  - id: R-001
+    severity: major
+    category: technical-correctness
+    subject: C-PROOF-001
+    section: proof
+    message: 대표 패치의 적용 완료 주장은 연결된 저장소 사실의 범위를 넘으므로 검토 통과 사실로 좁혀야 한다.
+    evidence:
+      - artifact: README.candidate.md
+        section-id: proof
+        line-start: 34
+        line-end: 35
+        content-hash: sha256:00e36e843e3370132b9c62718c3da3778bb251c1def0374182edf1723ca26df2
+        observation: C-PROOF-001은 검토와 적용 완료를 함께 말하지만 F-PROOF-001에는 PASS 출처 상태만 있다.
+    route-to: README_DRAFTED
+    status: open
@@ -0,0 +1,34 @@
+{
+  "schema-version": 1,
+  "state": "PASS_WITH_MANUAL",
+  "verification-level": "static",
+  "execution-verified": false,
+  "checks": {
+    "commands": {
+      "total": 3,
+      "verified": 1,
+      "manual-required": 2,
+      "failed": 0
+    },
+    "paths": {
+      "total": 7,
+      "verified": 7,
+      "failed": 0
+    },
+    "anchors": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    },
+    "readme-contracts": {
+      "total": 0,
+      "verified": 0,
+      "failed": 0
+    }
+  },
+  "failures": [],
+  "limitations": [
+    "manual verification required: python3 -m pip install -e \".[dev]\" (unsupported-static-verifier)",
+    "manual verification required: python3 -m pytest -q (unsupported-static-verifier)"
+  ]
+}
@@ -0,0 +1,31 @@
+schema-version: 1
+visuals:
+  - id: reviewed-patch-preview
+    section: proof
+    type: artifact-showcase
+    purpose: 검토와 적용을 마친 실제 README 패치의 핵심 변경을 보여 줍니다.
+    placeholder-text: 영문 중심 소개가 한국어 사용자 중심 소개로 바뀐 실제 diff 일부
+    must-show:
+      - 변경 전 영문 소개
+      - 변경 후 한국어 소개
+    relationships: []
+    emphasize:
+      - 입력 문서와 생성 문서의 차이
+    avoid:
+      - 저장소 근거가 없는 품질 우월성 표현
+    require-provenance: true
+    placement:
+      after-section-id: proof
+    accessibility:
+      alt-text: 영문 소개를 한국어 사용자 중심 소개로 바꾼 README 패치 미리보기
+    production:
+      format: diff
+      status: source-created
+      source-path: examples/readme-showcase/README.patch
+      source-hash: sha256:3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
+    asset:
+      path: examples/readme-showcase/README.patch
+      provenance: examples/readme-showcase/provenance.yaml
+      source-run: runs/readme-harness/20260720-review-remediation
+      sha256: sha256:3f930c70600d6530afa4a6b486be7f467f8650d28f4f2b057b889ef97f545e19
+      caption: 검토와 적용을 마친 이전 README 실행의 실제 패치 일부입니다.