7.4 KiB
README Harness
저장소에서 확인한 사실과 사용자가 정한 요구를 바탕으로 README 초안을 만드는 도구입니다.
명령·링크·경로를 검사한 뒤, 사람이 검토하고 적용할 수 있는 패치를 생성합니다.
현재 지원하는 작성·검증 흐름은 Codex용입니다.
Claude와 Antigravity에서 같은 동작을 하는지는 아직 미검증 상태입니다.
무엇을 만드는가
README를 새로 만들거나 기존 문서를 안전하게 갱신하려는 개발자를 위한 도구입니다.
- 새 README 작성
- 기존 README 점검
- 사람 작성 내용을 보존한 갱신
- 특정 섹션만 다시 작성
- 검토한 패치만 직접 적용
실제 결과
아래 내용은 검토를 통과한 이전 실행의 패치 일부입니다.
-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
+이 하네스는 저장소의 실제 코드와 사용 목적을 바탕으로 문서 후보를 만들고,
+명령·경로·근거를 검사한 뒤 검토 가능한 패치로 제공합니다.
전체 패치와 출처에서 더 긴 변경 내용을 확인할 수 있습니다.
빠른 시작
현재 실행 경로는 Codex 작업 공간의 requirement-driven-readme 스킬입니다.
Codex에 다음과 같이 요청합니다.
이 저장소의 README를
bootstrap모드로 작성해 주세요. 주 독자는 백엔드 개발자이며, 설치와 첫 실행 방법을 우선해 주세요.
작업 뒤 확인할 파일은 README.generated.md와 README.patch입니다.
생성된 README의 명령과 링크를 읽고, 패치가 의도한 범위만 바꾸는지 검토합니다.
대상 README.md는 적용 명령을 실행하기 전까지 바뀌지 않습니다.
검토가 끝난 패치만 직접 적용합니다.
python3 .agents/skills/requirement-driven-readme/scripts/apply_patch.py --run-dir runs/<repo-id>/<run-id> --repo /path/to/repository
적용 직전에 생성 파일과 대상 README, 저장소 기준 정보가 바뀌지 않았는지 다시 확인합니다.
어떤 작업을 지원하는가
새 README 작성과 전면 재작성의 기본 선택은 bootstrap입니다.
현재 README의 문제만 찾는 작업은 audit입니다.
사람이 작성한 영역을 보존하는 갱신은 refresh입니다.
한 섹션과 영향을 받는 검사 결과의 갱신은 section-update입니다.
안전하게 다루는 방법
코드에서 확인한 사실과 사용자가 정한 문서 요구는 따로 둡니다.
명령, 경로, 버전처럼 오류 영향이 큰 정보는 근거 파일과 연결합니다.
갱신 작업은 보호 영역과 마커 밖의 사람이 작성한 문장을 보존합니다.
사람이 고친 영역과 새 초안이 충돌하면 자동 병합과 적용이 중단됩니다.
비밀 값이나 저장소 밖 경로가 발견되면 패치를 준비하지 않습니다.
검토 뒤 저장소나 생성 파일이 바뀌어도 적용을 중단합니다.
동작 방식
사용자 요청 → 저장소 사실 확인 → README 작성 → 명령·링크·문장 검사 → 독립 검토 → 패치 확인 → 직접 적용
검사에서 문제가 나오면 해당 내용을 맡은 단계부터 다시 작성합니다.
입력과 생성 파일
readme-request.yaml에는 독자, 목적, 언어, 보존 범위와 그림 정책을 적습니다.
사용자는 다음 두 결과를 주로 확인합니다.
README.generated.md: 생성된 READMEREADME.patch: 현재 README와의 차이
각 작업의 파일은 runs/<repo-id>/<run-id> 아래에 따로 저장됩니다.
개발
개발에는 Python 3.12 이상이 필요하며, 개발 의존성에는 pytest가 포함됩니다.
저장소 루트에서 개발 모드로 설치합니다.
python3 -m pip install -e ".[dev]"
전체 테스트는 다음 명령으로 실행합니다.
python3 -m pytest -q
상세 문서
주요 구현은 src/readme_harness, 규칙과 워크플로는 .agents, 테스트는 tests에 있습니다.
현재 한계
-
README 문장은 모델이 작성하고 검사 스크립트는 준비된 파일을 확인합니다.
-
실행 기록이 없는 명령은 정적으로만 확인합니다.
-
Claude와Antigravity에서Codex와 같은 동작을 하는지는 아직 검증하지 않았습니다. -
블라인드 품질 비교는 아직 실행하지 않았으며 더 좋은 결과를 낸다고 주장하지 않습니다.