README 작성기
README의 임무는 단 하나입니다: 방문자를 "이게 뭐지?"에서 첫 번째 명령어 실행까지 1분 안에 안내하고, 그 후 어떻게 더 나아가고 도울 수 있는지 보여주는 것입니다.
사용 시기
- 새 프로젝트의 README를 작성하거나, 내용이 부족하거나 산만한 README를 다시 작성할 때
- 런칭 또는 1.0 릴리스 전에 README를 검토할 때
- 사용자가 프로젝트에 방문은 많지만 스타, 설치 또는 기여자가 없다고 말할 때
사용하지 말아야 할 때
- API 레퍼런스 문서: 코드에서 생성하고 README에서 링크하세요.
- 긴 튜토리얼이나 아키텍처 문서:
docs/디렉토리에 넣고 링크하세요.
작업 흐름
-
작성 전에 사실을 수집하세요. 매니페스트 파일(
pyproject.toml,package.json,composer.json,Cargo.toml...), CLI의--help또는 주요 진입점, 기존 문서, 라이선스 파일을 읽으세요. 실제 설치 명령어와 실제 예제를 찾으세요. 플래그, 출력, 벤치마크 또는 기능을 절대 지어내지 마세요. -
코드가 알려주지 않는 것만 사용자에게 물어보세요: 프로젝트의 대상 사용자, 해결하는 하나의 문제, 명백한 대안보다 나은 이유. 사용자가 응답할 수 없으면 코드에서 중립적인 피치를 작성하고 검토 표시를 남기세요.
-
기존 README를 린트하세요 (있는 경우).
scripts/는 이 스킬 기준 상대 경로입니다:python3 scripts/readme_lint.py README.md python3 scripts/readme_lint.py README.md --json --strict -
structure.md의 구조를 사용하여 작성하세요. 템플릿에서 시작하세요. 순서가 중요합니다: 제목 + 배지, 피치, (데모 이미지), 퀵 스타트, 기능, 사용법/예제, 설정, FAQ, 로드맵, 기여 방법, 라이선스.
-
작성 규칙을 적용하세요:
- 피치: 한 문장, 200자 미만, 과장된 표현 없음. 패턴: "
<이름>은<카테고리>로,<대상>을 위해<X 기능>을 제공하며,<핵심 차별점>입니다." - 첫 번째 코드 블록은 60줄 이내에 배치하세요. 모든 명령어는 복사-붙여넣기가 가능하고 실제여야 합니다.
- 명령어 뒤에 도움이 되는 출력을 보여주세요 (
# => ...또는 별도 블록). - 옵션과 비교는 표를 사용하고, 기능은 리스트(이점 먼저)를 사용하세요.
- 링크로 연결하세요: 긴 문서, 변경 로그, API 레퍼런스는 다른 곳에 있습니다.
- 모든 이미지에는 대체 텍스트를 제공하세요. 주요 흐름은 SVG나 짧은 GIF를 선호합니다.
- 피치: 한 문장, 200자 미만, 과장된 표현 없음. 패턴: "
-
배지. 실제로 참이고 유지 관리되는 배지만 사용하세요. 순서: CI 상태, 최신 버전 (PyPI/npm/Packagist/릴리스), 다운로드 수 (선택 사항), 라이선스. 예제는 structure.md에 있습니다.
-
오류가 없을 때까지 다시 린트하세요. 경고는 해결하거나 사용자에게 이유를 알리세요.
-
린터가 확인하지 못하는 링크를 검사하세요: 절대 URL과 앵커. 클릭 테스트를 하거나 검증하지 않은 링크를 설명하세요.
출력
- 새로 작성되거나 업데이트된 README.md (재작성의 경우 diff 요약을 보여주세요).
- 최종 린트 결과.
- 확인할 수 없었던 사실과 사용자가 채워야 할 플레이스홀더 목록 (데모 GIF, 스크린샷, 벤치마크 숫자).
린트 규칙
| 규칙 | 수준 | 의미 |
|---|---|---|
| title | 오류/경고 | 정확히 하나의 H1 |
| pitch | 오류/경고 | 제목 아래 짧은 첫 번째 문단 |
| badges | 경고 | 배지 없음 |
| install | 오류/경고 | 설치(또는 퀵 스타트) 섹션, 코드 블록 포함 |
| quickstart | 오류/경고 | 사용법, 퀵 스타트 또는 예제 섹션, 코드 포함 |
| code | 오류 | 코드 블록이 전혀 없음 |
| scroll | 경고 | --max-scroll 줄(기본 60) 이후 첫 번째 코드 블록 |
| contributing, license | 경고 | 섹션 누락 |
| faq, toc | 정보 | 권장 |
| alt-text | 경고 | 대체 텍스트 없는 이미지 |
| broken-link | 오류 | 누락된 파일 또는 빈 링크에 대한 상대 링크 |
| broken-anchor | 오류 | GitHub의 슬러그 규칙을 사용하여 제목이나 HTML id/name과 일치하지 않는 #anchor 링크 (목차) |
| placeholder | 경고 | 남아 있는 TODO, TBD 또는 로렘 입숨 |
오류 발생 시 (그리고 --strict 모드에서는 경고 발생 시) 종료 코드 1을 반환합니다.