핵심 내용
- 첫 화면에 프로젝트가 무엇이고 누구를 위한 것인지 한두 문장으로 설명합니다.
- 지원 환경, 설치 명령과 가장 짧은 실행 예시를 제공합니다.
- 필수 환경 변수는 예시값과 비밀값 취급 방법을 함께 설명합니다.
- 주요 기능, 흔한 실패 상황과 해결 경로를 적습니다.
- 테스트·린트·빌드 명령, 기여 방식, 라이선스와 문의 경로를 확인합니다.
형식 점검
- 제목 단계가 건너뛰지 않고 문서 내 링크가 실제 섹션을 가리키는지 확인합니다.
- 이미지에 대체 설명을 넣고 코드 블록에 가능한 경우 언어를 표시합니다.
- 새 환경에서 명령을 복사해 실행하고 오래된 배지·링크를 정리합니다.
깨끗한 환경에서 복사해 실행하기
이미 설정된 개발 PC에서는 누락된 단계가 드러나지 않습니다. 새 폴더나 CI 환경에서 README의 설치 명령부터 순서대로 실행하고, 명시하지 않은 전역 도구·환경 변수·로그인 세션에 의존하지 않는지 확인합니다.
README에 모든 것을 넣지 않습니다
배포 이력, 긴 장애 분석, 세부 API 계약은 별도 문서로 옮기고 README에는 언제 그 문서를 읽어야 하는지 링크합니다. 첫 방문자가 실행에 필요한 정보와 운영자가 참고할 기록을 한 파일에 섞지 않는 것이 오래 유지되는 README의 핵심입니다.
템플릿과 점검 도구
README 템플릿을 편집기에 불러온 뒤 문서 점검으로 제목, 링크, 이미지와 코드 블록을 확인할 수 있습니다.