프로젝트 README
README는 매개변수 설명서도, 광고도 아닙니다. 그것은 새로운 독자가 프로젝트를 신뢰하고 첫 결과를 얻는 가장 짧은 경로입니다.
섹션을 채우기 위해 채우지 마세요. 독자는 세 가지 질문에 답할 수 있어야 합니다: 이게 뭐지? 나에게 적합한가? 첫 결과를 얻고 위험 경계를 이해할 수 있는가?
핵심 원칙
- 모든 주장에는 증거가 필요합니다. 저장소에서 확인할 수 없거나 사용자가 확인하지 않은 주장은 생략하고, 추측을 모호한 문장으로 완화하지 마세요.
- Quick Start는 필수입니다: 설치부터 유용한 결과까지 가장 짧은 실제 경로를 제공하세요. 그 명령을 확인할 수 없으면, 빈칸으로 두거나 발명하지 말고 물어보세요.
- README가 이미 존재하는 경우, 교체할지, 선택한 자료를 보존할지, 아니면 제자리에서 확장할지 물어보세요. 사용자가 작성한 내용을 추측하거나 덮어쓰지 마세요.
- 정체성과 진입점을 접는 선 위에 배치하세요. 공개 프로젝트의 경우 프로젝트 이름/로고, 한 줄 설명, 실제 배지, 탐색을 사용하고, 그 직후에 Quick Start를 배치하세요. GIF/스크린샷은 텍스트보다 더 많은 정보를 전달할 때만 사용하세요.
- 주장보다는 보여주세요: 터미널 출력, 스크린샷, 코드, 검증된 숫자가 형용사보다 강력합니다.
- 매개변수 기준이 아닌 작업 기준으로 구성하세요. "무엇을 하고 싶은가 → 어떤 명령이 그것을 하는가"를 설명하고, 전체 옵션 목록은
--help에 맡기세요. - 독자가 결정하고, 신뢰하고, 행동하는 데 도움이 되지 않는 모든 줄은 삭제하세요.
- 프로젝트가 로컬 파일, 데이터베이스, 자격 증명, 네트워크 또는 모델 호출을 다루는 경우, 그것이 읽고, 쓰고, 기기 외부로 보내는 것과 기본 읽기 전용/확인/백업/폐쇄 실패 자세를 설명하세요. 코드 증거 없이 보안 약속을 하지 마세요.
- README를 정문으로 유지하고, 깊은 세부 사항은
docs/또는CONTRIBUTING.md로 연결하세요. README를 매뉴얼로 만들지 마세요. - 프로젝트에 맞추세요. CLI, MCP, 라이브러리, 앱 및 연구 저장소에 하나의 템플릿을 강요하지 마세요.
- "업계 선도", "프로덕션 준비", "극한 성능"과 같은 검증되지 않은 과장을 피하세요.
content-writing의 가드레일을 참조하세요.
독자 선택
README의 독자를 분류하여 세부 수준을 설정하세요:
- Solo (개인 프로젝트, 내부 도구 또는 개인 스크립트): 독자는 주로 당신 자신이며, 미래의 당신을 포함합니다. 필수: 한 줄 설명, Quick Start 및 알려진 제한사항. 배지, 기여 가이드, 커뮤니티 채널, 스타 기록 및 로드맵은 선택 사항입니다. 기준은 3개월 후에도 여전히 실행할 수 있어야 한다는 것입니다.
- Public (오픈 소스, 배포된 소프트웨어 또는 팀 공유): 독자는 낯선 사람입니다. 설명, 가치, Quick Start, 사용법, 구성, 문서 색인, 기여 및 라이선스를 포함하세요. 배지와 커뮤니티 정보는 실제로 존재할 때만 추가하세요.
저장소가 공개되어 있거나, 패키지 관리자에 게시되었거나, 외부 사용자가 있는 경우 기본값은 공개입니다. 개인 프로젝트 및 일회성 작업의 경우 기본값은 솔로입니다. 혼합된 경우 공개 세부 수준을 사용하세요.
모드 선택
| 모드 | 사용 시기 | 첫 번째 단계 |
|---|---|---|
| create | README가 없거나 사용자가 명시적으로 재작성을 요청한 경우 | 저장소를 검사하고 사실을 수집합니다. |
| improve | README가 존재하며 작업이 필요한 경우 | 그것을 읽고, 기존 콘텐츠를 처리하는 방법을 물은 다음 진행합니다. |
| audit | 사용자가 진단만 요청한 경우 | 저장소에 대해 각 README 주장을 확인하고 결과를 보고합니다. |
게이트: README가 존재하는 경우 사용자의 선택을 위해 일시 중지합니다: (1) 완전히 교체, (2) 지정된 자료를 유지하면서 재작성, 또는 (3) 제자리에서 확장. "README 작성을 도와주세요"가 옵션 1을 의미하지는 않습니다.
접는 선 위 및 개발자 도구 스타일 (공개 프로젝트)
독자는 한 화면 후에 계속할지 결정합니다. 첫 화면은 프로젝트가 무엇을 하는지 보여주어야 합니다.
CLI, MCP 및 로컬 개발자 도구의 경우 절제되고 검증 가능한 개발자 문서를 선호하세요:
<div align="center">
선택 사항 로고
# 프로젝트 이름
**한 줄 설명**
실제 배지만
언어 전환기 (다른 README가 존재할 때만)
앵커 탐색 (문서가 100줄을 초과할 때)
</div>
---
기능 개요: 실제 명령/도구, 입력, 출력 및 기본 안전 자세
세 가지 규칙:
- 한 줄 설명: 기억에 남고 대략 한 줄로 유지하세요: 무엇인지, 누구를 위한 것인지, 가장 중요한 사실적 차별점. 원칙과 배경은 나중으로 미루세요.
- 기능 개요: 실제 명령/도구, 입력, 출력, 읽기/쓰기 개체 및 기본 안전 자세를 나열하세요. "빠르고, 안전하며, 지능적"과 같은 일반적인 주장은 피하세요.
- Quick Start를 다음에 배치: 1~3개의 가장 짧은 단계를 선호하세요. 마지막 단계는 설치 또는 서비스 검색을 확인해야 합니다. 복잡한 구성은 나중으로 미루세요.
시각 자료는 선택 사항입니다. GIF/asciinema, 스크린샷 및 실제 터미널 출력은 정보를 추가할 때만 선택하세요. 데모 에셋이 없으면 발명하지 말고, 실제 명령, 예상 출력 및 확인 단계를 제공하세요.
Solo 프로젝트는 로고, 배지 및 탐색을 생략할 수 있지만, 한 줄 설명과 표시 가능한 출력은 여전히 유용합니다.
증거 사다리
각 주장을 쓰기 전에 증거를 분류하세요:
| 수준 | 출처 | 사용 |
|---|---|---|
| 1 | 저장소 내: 소스, 테스트, 예제, 구성, CI, 태그, 스크린샷 | 직접 작성합니다. |
| 2 | 사용자가 확인: 포지셔닝, 차별화, 메트릭, 스크린샷, 사례 | 직접 작성합니다. |
| 3 | 외부에서 확인 가능: 패키지 페이지, 릴리스, 공개 벤치마크 | 링크와 함께 작성합니다. |
| 4 | 출처 없음 | 생략합니다. 중요하면 물어보고, 그렇지 않으면 삭제합니다. |
설치 명령, CLI 매개변수, API 시그니처, 구성 키, 환경 변수, 경로, 성능 숫자, 호환성 주장, 라이선스 조건 또는 커뮤니티 링크를 절대 발명하지 마세요.
저장소 스캔 및 증거 규칙은 references/evidence.md를 참조하세요.
워크플로우
- audience 및 mode 분류: solo/public 및 create/improve/audit. README가 있으면 변경하기 전에 어떻게 처리할지 물어보세요.
- 저장소 증거 수집: 패키지 메타데이터, 진입점, 구조, 구성, 문서, Git/CI, 에셋, 읽기/쓰기 경로, 자격 증명, 네트워크, 모델 호출 및 오류 코드를 검사하세요. 이 단계는 사실을 수집하고 결론을 내리는 것이 아닙니다.
references/evidence.md를 참조하세요. - 프로젝트 및 독자 분류: CLI, MCP, 라이브러리, 앱, 연구 프로젝트, 에이전트 스킬 또는 모노레포. 이를 사용하여 섹션을 선택하세요.
references/structure.md를 참조하세요. - Quick Start 확인: 설치 후 유용한 결과를 생성하는 첫 번째 명령을 찾아 확인하세요. 확인할 수 없으면 물어보고 이 게이트를 넘어 진행하지 마세요.
- 섹션 계획: 프로젝트 유형에 대한 섹션을 선택하고 각 섹션에 대한 증거를 식별하세요. 지원되지 않는 섹션은 생략하세요. 또한 접는 선 위 레이아웃, Quick Start 확인, 보안/데이터 흐름, 오류 코드 또는 문제 해결이 필요한지 결정하세요.
- 초안 작성: 정체성 및 기능 → Quick Start → 특징 → 설치/구성 → 작업 기반 사용법 → 근거/배경 → 보안/개인정보 경계 → 오류/문제 해결 → 알려진 제한사항 → 개발/심층 문서. 독자가 작동 경로를 가진 후에 근거를 설명하고, 그 전에 설명하지 마세요.
- 품질 게이트 실행:
references/checklist.md의 각 항목, 특히 사실적 정확성과 실행 가능한 단계를 확인하세요. - 전달: 기본적으로 대화에서 초안을 제공하고, 명시적으로 요청된 경우에만 디스크에 쓰세요. 쓰기 전에 체크리스트를 다시 실행하세요.
출력
간결하게 다음을 진술하세요: (1) audience 및 mode; (2) 프로젝트 유형 및 대상 독자; (3) 각 섹션에 대한 섹션 계획 및 증거 출처; (4) README 초안; (5) 증거가 없어 사용자 확인이 필요한 주장; (6) 알려진 누락. 추측을 확인된 것으로 레이블링하지 마세요. 지원되지 않는 주장을 모호한 언어로 위장하지 말고 명시적으로 나열하세요.
위험 신호
- Quick Start가 없거나 비어 있거나, 저장소 진입점이 없는 발명된 명령.
- 기존 README를 처리 방법을 묻지 않고 덮어쓰기.
- 확인되지 않은 성능, 호환성, 사용자 수 또는 별표 수 주장.
- 존재하지 않는 CI, 패키지 또는 라이선스를 가리키는 배지.
- 빈 제목 또는 "TODO/coming soon"으로 템플릿 섹션 채우기.
- 전체 API 매뉴얼을 연결하는 대신 포함시키기.
- 작업 기반 명령을 표시하는 대신 긴
--help테이블 재현하기. - 슬로건이나 원칙만 있고 실제 진입점이나 확인 가능한 결과가 없는 시작 화면.
- 로컬 데이터, 자격 증명, 네트워크 또는 모델 호출을 다루는 도구에 대한 보안/데이터 흐름 정보 누락.
- 코드/테스트 증거 없이 읽기 전용 작동, 데이터 유출 없음, 폐쇄 실패 동작 또는 제로 구성을 약속.
- 증상, 오류 코드, 원인 및 해결책 없이 "재시작"만 말하는 문제 해결.
- 문단인 한 줄 설명, 또는 첫 번째 실행 가능한 경로 앞에 나타나는 근거.
- "강력한", "우아한", "극한의" 또는 "즉시 사용 가능"과 같은 증거를 대체하는 형용사.
- 존재하지 않는 기여 가이드, 행동 강령 또는 커뮤니티 링크를 솔로 프로젝트에 강요.
- 존재하지 않는 구성 요소 또는 호출 관계를 포함하는 아키텍처 다이어그램.
- 사용자 승인 없이 파일 쓰기.
참조
필요한 것만 읽으세요:
references/structure.md: 읽기 흐름, 프로젝트 유형별 섹션 선택 및 섹션 작성 지침.references/evidence.md: 저장소 스캔, 증거 수준 및 발명해서는 안 되는 주장.references/checklist.md: 사실, 사용성, 프레젠테이션 및 언어에 대한 사전 작성 품질 게이트.