# README Harness

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

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

## 빠른 시작

1. Python 3.12 이상이 설치된 환경에서 이 저장소를 전용 가상환경에 설치합니다.

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

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

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

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

## 작업 선택

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

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

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

## 생성 흐름

1. 작성자는 사용자 요구와 저장소를 읽고 일반 Markdown 초안과 근거가 있는 사실 목록을 만듭니다.
2. 하네스는 초안을 검사하고 `README.generated.md`와 `README.patch`를 준비합니다. 첫 검증 통과 결과는 `REVIEW_REQUIRED`이며 원본 README는 그대로 남습니다.
3. 읽기 전용 검토자가 GitHub 방문자에게 보일 생성본을 평가합니다. `NEEDS_FIX`이면 작성자가 한 번만 수정하고 전체 검증과 검토를 다시 실행합니다.
4. 검토까지 통과한 실행은 `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를 직접 수정하지 않습니다.

```python
from readme_harness import build_readme

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

함수의 입력과 산출물 경계, 외부 사실 결합 방식은 [아키텍처 문서](docs/architecture.md)에 정리되어 있습니다.

## 개발

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

```bash
.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 전체 문서입니다. 기존 문서의 일부 구역만 자동 병합하지 않으므로 적용 전에 전체 패치를 확인해야 합니다.
- 자동 수정 기회는 한 번입니다. 두 번째 품질 검토도 통과하지 못하면 남은 문제를 사용자에게 돌려줍니다.