10 KiB
README Harness
이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고, 명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
- 새 README 작성
- 기존 문서 점검
- 사람 작성 영역을 보존한 갱신
- 특정 섹션과 관련 검증 산출물의 재생성
- 검토 후 별도로 실행하는 적용
무엇을 만드는가
README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
bootstrap, audit, refresh, section-update 네 모드를 구현했습니다.
저장소 근거와 사용자 요구를 분리해 읽고, 고위험 사실을 근거에 연결합니다. 그림을
넣기로 했다면 실제 소스나 자산까지 확인하고, 품질 심사는 원문의 줄과 해시에 묶인
근거를 사용합니다. 패치 준비가 끝나도 대상 README.md는 자동으로 바뀌지 않습니다.
결정론적 Codex 경로는 구현됐습니다. 후보 문장 작성은 모델 파이프라인이 담당하며, 다른 도구와의 런타임 동등성은 Phase 4 검증 전까지 보장하지 않습니다.
설치
Python 3.12 이상이 필요합니다.
런타임 의존성은 jsonschema와 PyYAML입니다.
개발 의존성은 pytest입니다.
저장소 루트에서 개발 의존성을 포함한 편집 가능 설치를 실행합니다.
python3 -m pip install -e ".[dev]"
이 설치 명령은 프로젝트 선언에서 확인했지만, 현재 작업에서는 새 가상환경 설치까지 실행해 증명하지 않았습니다.
빠른 시작
먼저 전체 테스트를 실행합니다.
python3 -m pytest -q
종료 코드 0과 실패 항목 없는 통과 요약이 성공 기준입니다. 이 후보는 아직 현재 README를 바꾸지 않았으므로 최종 전체 결과는 명시적 적용 뒤 다시 확인합니다.
자체 README 테스트는 이 명령을 최소 실행 경로로 요구합니다. 다른 운영체제와 새 가상환경의 동일한 결과까지 보장하는 계약은 아닙니다.
이 프로젝트는 명령 하나로 문서를 완성하는 독립 실행 도구가 아닙니다. Codex 작업 공간에서
requirement-driven-readme 스킬로 대상 저장소의 bootstrap 실행을 요청하면 작성
역할이 사용자 요구, 저장소 근거, 개요, 후보, 주장 지도, 그림 계획과 품질 심사
산출물을 준비합니다.
대상 저장소용 실행 디렉터리를 만듭니다.
python3 .agents/skills/requirement-driven-readme/scripts/init_run.py --repo-id demo --run-id first --mode bootstrap --target-repository /path/to/repository --tool-adapter codex
이 명령은 runs/demo/first에 상태와 실행 매니페스트를 초기화합니다.
실행 디렉터리에 readme-request.yaml, repository-facts.yaml, readme-brief.yaml,
readme-outline.yaml, README.candidate.md, claim-map.yaml, visual-plan.yaml,
review-findings.yaml이 준비되면 모든 결정론적 게이트를 재생합니다.
python3 .agents/skills/requirement-driven-readme/scripts/run_bootstrap.py --run-dir runs/demo/first --repo /path/to/repository
드라이버는 후보를 새로 쓰지 않고 준비된 산출물을 QUALITY_REVIEWED까지
검증합니다.
사용 모드
| 작업 | 모드 | 결과 |
|---|---|---|
| README가 없거나 전면 재작성 | bootstrap |
검증된 후보와 적용 준비용 패치 |
| 기존 문서의 결함만 점검 | audit |
감사 결과와 검증 보고서, 후보·패치 없음 |
| 사람 작성 영역을 보존한 갱신 | refresh |
3방향 병합과 병합본 전체 재검증 |
| 한 섹션과 파급 산출물 갱신 | section-update |
관련 산출물 무효화 후 갱신 검증 재실행 |
네 모드는 요청 스키마에 선언되어 있고 각 흐름의 상태·게이트 계약이 구현되어 있습니다.
요청 API, 설정과 산출물
readme-request.yaml은 독자, 언어, 길이, 보존 범위, 공개 용어, 그림 정책을
정합니다. 기술 사실은 repository-facts.yaml에 저장하고, 각 실행은
runs/<repo-id>/<run-id> 아래에서 격리합니다.
어댑터가 제공하는 단계별 모델 사용량은 실행 매니페스트에 누적합니다. 제공되지 않은 값은 0으로 추정하지 않습니다.
대표 산출물은 다음 순서로 이어집니다.
readme-brief.yaml + readme-outline.yaml
README.candidate.md + claim-map.yaml + visual-plan.yaml
prose-report.json + verification.json + review-findings.yaml
quality-manifest.yaml
README.generated.md + README.patch + apply-manifest.yaml
품질 검토를 통과한 뒤 다음 명령으로 패치를 준비합니다.
python3 .agents/skills/requirement-driven-readme/scripts/generate_patch.py --run-dir runs/demo/first --repo /path/to/repository
이 단계는 README.generated.md, README.patch, apply-manifest.yaml을 만들고
상태를 READY_FOR_APPLY로 전진시킵니다.
검토가 끝난 패치만 별도 명령으로 적용합니다.
python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/demo/first --repo /path/to/repository
적용 직전에 후보·저장소·대상 README 해시와 경로 경계를 다시 검사합니다.
동작 방식
사용자 요구는 독자 흐름과 공개 용어, 그림 결정을 만듭니다. 대상 저장소에서는 근거와 프로젝트 유형을 수집합니다. 두 입력이 합쳐진 후보와 시각 자료는 결정론적 게이트와 독립 품질 심사를 통과해야 패치가 됩니다.
flowchart LR
T[Codex / Claude / Antigravity] --> O[실행 조정]
U[사용자 요구] --> P[독자 흐름·용어·그림 결정]
R[대상 저장소] --> E[근거 수집·프로젝트 분류]
O --> E
O --> P
E --> P
P --> W[README 작성]
P --> V[그림 소스·자산 생성]
W --> G[근거·명령·경로·문체 검사]
V --> G
G --> Q[독립 품질 심사]
Q -->|수정 필요| P
Q -->|통과| A[패치 준비·명시적 적용]
H[(해시 기반 실행 산출물)] --- E
H --- P
H --- G
H --- A
구성요소 책임과 컨텍스트 경계는 아키텍처 문서에, 모드별 전이는 상태기계 문서에 정리했습니다.
안전장치
- 명령·버전·전제조건·모듈·경로·보장·한계 주장은 저장소 근거에 연결합니다.
- 인라인 코드의 영문 표현이 실제 식별자인지 확인하고 내부 전용 용어의 공개 노출을 차단합니다.
- 그림을 포함하기로 한 개요 결정, 계획 항목, README 마커, 생성 소스나 자산이 일치해야 시각 자료 게이트를 통과합니다.
- 품질 점수와 독자 과업 근거의 줄 범위와 해시를 실제 후보에 대조하고,
review.md는 검증된 YAML에서 렌더링합니다. - 감사 모드는 결과 스키마를 확인하고 산출물을 원자적으로 기록한 다음 완료 상태로 전진합니다.
- 갱신 모드는 보호 영역과 마커 밖 문장을 보존하며, 사람이 고친 관리 영역과 새 후보가 충돌하면 자동 적용을 막습니다.
- 비밀 값, 저장소 밖 경로, 오래된 스냅숏, 검토 뒤 바뀐 산출물은 패치 준비나 적용을 차단합니다.
시각 자료의 소스·자산·대체 텍스트·신선도 규칙은 시각 자료 정책에서 확인할 수 있습니다.
테스트
전체 회귀 테스트는 다음 명령으로 실행합니다.
python3 -m pytest -q
GitHub Actions는 의존성을 설치한 뒤 전체 테스트를 실행합니다. 실행 환경은 Python 3.12입니다. 자체 README 테스트는 라이브러리 프로파일, 30초 독자 흐름, 최소 실행 경로, Mermaid 그림 결정을 확인합니다.
상세 문서
주요 구현은 src/readme_harness, 스키마·규칙·워크플로는 .agents, 테스트는
tests에 있습니다.
현재 한계
- 후보 작성은 LLM 파이프라인의 판단에 의존합니다. 결정론적 드라이버는 준비된 산출물을 검증하고 상태를 전진시킵니다.
- 네 모드의 결정론적 경로는 구현됐지만 도구 간 런타임 동등성은 Phase 4 검증 목표입니다.
- 명령 검증 보고서의 기본 수준은 정적 검사입니다. 실행을 별도로 기록하지 않은 명령은 실제 실행 성공을 뜻하지 않습니다.
- 여덟 저장소 유형의 블라인드 비교 계약은 마련했지만 결과 상태는 아직
not-run입니다.PASS결과 전에는 품질 우월성을 주장하지 않습니다.