README Harness는 GitHub README를 만드는 검증 중심 Python 도구입니다. Codex 및 claude가 저장소에서 확인한 사실과 사용자가 지시한 목적을 근거로 삼습니다. 명령, 경로, 링크, Markdown 구조와 비밀 값 노출을 검사하고 별도 품질 검토를 거친 패치를 제공합니다. 사용자가 적용하기 전에는 원본 README.md를 바꾸지 않습니다.

대상 저장소를 처음 문서화하려는 개발자를 위한 도구입니다. 기존 README의 정확성과 읽기 흐름을 함께 점검할 때도 씁니다. 현재는 Codex와 claude만 지원합니다.

빠른 시작

Python 3.12 이상이 설치된 환경에서 이 저장소를 전용 가상환경에 설치합니다.
```
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```
Codex 및 claude에 대상 저장소, 주 독자, README의 목적을 알려 줍니다. /work/acme-api는 설명을 위한 예시 경로이므로 실제 대상의 절대 경로로 바꿉니다.

requirement-driven-readme 스킬로 /work/acme-api의 README를 작성해 주세요. 처음 API를 연동하는 백엔드 개발자가 5분 안에 로컬 실행과 테스트를 마치는 것이 목표입니다.
작업이 끝나면 대상 저장소의 .readme-harness/README.generated.md를 먼저 읽고 README.patch에서 기존 문서와의 차이를 확인합니다. validation.json의 status가 READY이고 review.json의 verdict가 PASS여야 적용할 수 있습니다.

생성본에 동의할 때만 적용합니다.

.venv/bin/readme-harness apply /work/acme-api

검토 이후에 생성본, 검토 결과, 대상 README 또는 저장소가 바뀌었으면 적용 명령은 중단됩니다.

작업 선택

목적	시작 방법	결과
새 README 작성 또는 전면 재작성	Codex에`requirement-driven-readme` 스킬로 요청	검증·검토된 후보와 전체 패치
기존 README의 사실과 형식 점검	`audit` 하위 명령 실행	사실 목록과 검증 결과
승인한 후보 적용	`apply` 하위 명령 실행	대상`README.md` 교체

기존 README만 점검하려면 다음 명령을 실행합니다. 감사 작업은 문장이나 패치를 생성하지 않습니다.

.venv/bin/readme-harness audit /work/acme-api

생성 흐름

작성자는 사용자 요구와 저장소를 읽고 일반 Markdown 초안과 근거가 있는 사실 목록을 만듭니다.
하네스는 초안을 검사하고 README.generated.md와 README.patch를 준비합니다. 첫 검증을 통과하면 결과는 REVIEW_REQUIRED이며 원본 README는 그대로 남습니다.
읽기 전용 검토자가 GitHub 방문자에게 보일 생성본을 평가합니다. NEEDS_FIX이면 작성자가 한 번만 수정하고 전체 검증과 검토를 다시 실행합니다.
검토까지 통과한 실행은 READY가 됩니다. 이후 사용자가 apply를 실행해야 대상 README가 바뀝니다.

이 절차는 작성과 품질 판단을 Codex가 맡고 반복 가능한 형식·경로·명령 검사를 코드가 맡도록 경계를 나눕니다.

결과 파일

모든 결과는 기본적으로 대상 저장소의 .readme-harness/에 기록됩니다.

파일	확인할 내용
`README.generated.md`	GitHub에 표시될 최종 후보
`README.patch`	현재 README와 후보 전체 차이
`validation.json`	검사별 오류·경고와 현재 적용 가능 상태
`facts.json`	프로젝트 정보, 명령, 근거 파일
`review.json`	생성본에 결합된 별도 품질 검토 결과

첫 생성 단계에는 앞의 네 파일만 존재합니다. 품질 검토를 실행한 뒤 review.json이 추가됩니다. 검증에 실패하면 이유는 validation.json에 남고 적용할 수 있는 패치는 제공되지 않습니다.

검사와 적용 보호

사실 근거와 README 대상, 상대 링크가 저장소 안에 있는지 확인하며 저장소 밖을 가리키는 심볼릭 링크를 따라가지 않습니다.
코드 블록 닫힘, 제목 단계와 중복 앵커, 이미지 대체 텍스트, 이식할 수 없는 로컬 링크를 검사합니다.
README에 적힌 명령을 프로젝트 메타데이터와 저장소 파일을 기준으로 정적으로 확인합니다.
README와 사실 파일에서 할당된 비밀 값, 자격 증명이 든 연결 문자열, 개인 키, AWS 액세스 키 형식을 검사합니다.
적용 직전에는 생성본, 검토 파일, 대상 README와 저장소의 해시를 다시 비교합니다.
파일 교체는 임시 파일을 완성한 뒤 원자적으로 수행합니다.

Python API

명령줄 대신 readme_harness.build_readme(...)를 호출할 수 있습니다. 이 함수는 초안과 사실 목록을 검증하지만 대상 README를 직접 수정하지 않습니다.

from readme_harness import build_readme

result = build_readme(
    "/work/acme-api",
    "/tmp/acme-readme.md",
    facts="/tmp/acme-facts.json",
)
print(result.status)

함수의 입력과 산출물 경계, 외부 사실을 결합하는 방식은 아키텍처 문서에 정리되어 있습니다.

개발

개발 의존성을 설치한 뒤 전체 테스트를 실행합니다.

.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q

테스트는 tests/에 있으며 GitHub Actions도 Python 3.12에서 같은 테스트 명령을 실행합니다. CLI 진입점은 readme_harness.cli:main이고 공개 Python 진입점은 readme_harness.build_readme(...)입니다.

현재 한계

문장과 정보 구조는 Codex 및 claude가 작성합니다. CLI 자체는 저장소만 보고 새 README 문장을 생성하지 않습니다.
명령 검증은 프로젝트 선언과 파일을 이용한 정적 검사입니다. 외부 서비스, 자격 증명, 배포 환경에서 실행에 성공하는 것까지 보장하지 않습니다.
생성 후보는 README 전체 문서입니다. 기존 문서의 일부 구역만 자동 병합하지 않으므로 적용 전에 전체 패치를 확인해야 합니다.
자동으로 수정할 기회는 한 번입니다. 두 번째 품질 검토도 통과하지 못하면 남은 문제를 사용자에게 돌려줍니다.