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