212 lines
7.4 KiB
Markdown
212 lines
7.4 KiB
Markdown
# 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 -->
|