README 평가하기
개요
README는 저장소의 첫인상입니다. 대부분의 README는 표면(API가 어떻게 생겼는지)만 문서화하고 멘탈 모델(시스템이 무엇인지, 어떻게 동작하는지, 어디서 깨지는지)은 문서화하지 않아 실패합니다. 이 스킬은 8가지 축으로 README를 평가하고 종합적인 판단을 위한 최상의 휴리스틱을 제시합니다.
이 루브릭을 사용하여 서면 리뷰를 작성하세요. 각 섹션에서 무엇이 잘 작동하는지, 무엇이 누락되었는지, 무엇을 수정해야 하는지 구체적으로 언급하세요. 줄을 인용하고, 제목을 가리키고, 버그의 이름을 명시하세요.
사용 방법
- README를 한 번 처음부터 끝까지 판단하지 않고 읽으세요. 첫인상이 중요합니다.
- 아래 8개 섹션을 순서대로 확인하세요. 각 섹션에는 질문이 있으며, README에서 증거를 들어 답하세요.
- 마지막에 단일 최상 휴리스틱을 적용하여 평가의 타당성을 확인하세요.
- 나열된 안티패턴을 확인하세요. 이는 자동 감점 항목입니다.
- 수정 목록(Punch List)을 우선순위에 따라 작성하세요.
루브릭
1. 첫 30초 테스트
처음 보는 사람이 README 첫 화면 위에서 방향을 잡을 수 있는지 여부입니다.
- 이게 뭔가요? 첫 화면 위에 낯선 사람도 이해할 수 있는 한 문장이 있어야 합니다.
- 누구를 위한 건가요? 독자가 첫 문단 안에서 자신이 대상인지 아닌지 판단할 수 있어야 합니다.
- 작동하나요? 생명의 증거 — CI 상태, 주간 다운로드 수, 최종 릴리스 날짜, 버전 배지, "X에서 테스트 완료". 실제 다운로드 수는 릴리스 날짜보다 강력한 신호이며, 녹색 CI 배지는 그보다 더 강력합니다. 아무도 버려진 저장소를 신뢰하지 않습니다.
2. 5분 안에 설치할 수 있나요?
모든 코드 블록을 순서대로 복사해서 붙여넣은 독자가 결국 작동하는 무언가를 얻게 되는지 여부입니다.
- 사전 요구사항이 명시적입니다. — 런타임 버전, 피어 의존성, 외부 서비스.
- 설치는 하나의 복사 가능한 블록입니다. "설치는 저희 문서 사이트를 참조하세요"가 아닙니다.
- 빠른 시작이 처음부터 끝까지 실행됩니다. 중간에 끊김이 없어야 하며, "X를 구성하세요"라고만 하고 방법을 보여주지 않으면 안 됩니다.
- 예제에서 일관된 이름을 사용합니다. 설정에서
mainKnowledgePool을 사용하고 검색에서'main'을 사용하는 것은 README 버그 중 1위입니다. 복사-붙여넣기 사용자를 조용히 실패하게 만듭니다.
3. 현실과 일치하나요?
README가 코드와 함께 유지보수되었는지 여부입니다.
- 모든 코드 샘플이 컴파일됩니다. 오래된 타입 시그니처와 이름이 변경된 내보내기는 예제가 없는 것보다 더 나쁩니다.
- 버전 차이가 인정됩니다. 비디오/블로그 게시물/섹션이 오래된 경우, 독자가 어렵게 발견하게 두지 말고 그 자리에서 언급하세요.
- 오류 응답과 엣지 케이스가 문서화되어 있습니다. 단순한 성공 경로뿐만 아니라 — 독자는 무엇이 깨지는지 인정하는 문서를 신뢰합니다.
4. 탐색하기 쉬운가요?
세 번째로 돌아온 사람이 필요한 것을 빠르게 찾을 수 있는지 여부입니다.
- 목차가 약 300줄 이상이면 필요합니다.
- 섹션 깊이가 의미 있습니다. h4 아래 h3 아래 h2는 실제 포함 관계를 반영해야 하며, 단순히
##가 부족해서가 아니어야 합니다. 고립된 하위 섹션은 문서가 재구성 없이 커졌다는 신호입니다. - 상호 참조는 링크여야 하며 산문이 아니어야 합니다. "위 참조"는 나빠지기 쉽습니다.
[메타데이터 필터링](#metadata-filtering-where)는 편집에도 살아남습니다. - 중복 정보는 위험합니다. 동일한 엔드포인트가 두 번 문서화되면 하나는 썩게 마련입니다. 정식 위치를 하나 선택하세요.
5. API뿐만 아니라 멘탈 모델을 가르치나요?
독자가 구문뿐만 아니라 직관을 얻고 떠나는지 여부입니다.
- 방법뿐만 아니라 이유도 설명합니다. "대량 실행은 자동 대기되지 않습니다. 수동으로 트리거해야 합니다"는 시그니처 덤프보다 더 많은 정보를 제공합니다.
- 생명주기와 불변 속성이 명시되어 있습니다. "풀당 한 번에 하나의 대량 실행만 가능", "삭제는 비활성화할 수 없음", "ID는 X를 Y와 연결합니다" — 문서화되지 않으면 사용자가 고통스럽게 발견하는 것들입니다.
- 실패 모드에 이름이 있습니다. 문제 해결 섹션은 "관리자가 실제로 이 제품을 프로덕션에서 지원해 본 적이 있다"는 대리 신호입니다.
문서 사이트 예외. 프로젝트에 첫 화면 위에 연결된 표준 참조 사이트(예:
zod.dev/api,nextjs.org/docs)가 있는 경우, 이 섹션을 "README가 독자가 문서 사이트에 들어갈지 여부와 들어가서 무엇을 찾을지 알 수 있을 만큼 충분히 가르치는가?"를 기준으로 평가하세요. "전체 멘탈 모델을 가르치는가?"가 아닙니다. README에 전체 참조를 복제하는 것은 섹션 4의 "중복 정보는 위험" 규칙을 위반합니다. 이 경우 README의 역할은 다리이지 백과사전이 아닙니다.
6. 점진적 공개
각 대상 독자가 필요한 섹션까지만 읽고 멈출 수 있는지 여부입니다.
- 빠른 시작으로 작동하게 됩니다. 참조로 막힌 부분을 해결합니다. 예제는 관용적인 사용법을 보여줍니다.
- 고급 기능이 초보자를 막지 않습니다. 대량 API, 제공자 콜백, 사용자 정의 어댑터 — 검색 작동까지의 최소 경로 뒤로 미뤄집니다.
- 필수/선택 열이 있는 구성 테이블로 사람들이 읽지 않고 훑어볼 수 있습니다.
7. 유지보수 신호
프로젝트가 살아 있고 회사 내에서 사용 가능해 보이는지 여부입니다.
- 변경 로그가 연결되어 있습니다. 변경 로그가 없으면 유지보수되고 있다는 신호가 없습니다.
- 라이선스가 명시되어 있습니다. 라이선스가 없으면 대부분의 회사에서 사용할 수 없습니다.
- 기여 경로가 보입니다. 한 줄이라도 ("먼저 이슈를 열어주세요") 아예 없는 것보다 낫습니다.
- 어조가 성숙도와 일치합니다. 알파 프로젝트가 v3처럼 읽혀서는 안 되며, 안정적인 프로젝트가 해커톤 피치처럼 읽혀서는 안 됩니다.
8. 한계에 대해 솔직한가?
관리자가 독자의 시간을 존중하는지 여부입니다.
- 어댑터 패리티, 플랫폼 지원, 알려진 격차가 표면에 드러나며, GitHub 이슈에 숨겨져 있지 않습니다.
- README에서 한계를 발견한 독자는 정보를 얻었다고 느끼지만; 2시간 디버깅 후에 같은 한계를 발견한 독자는 속았다고 느낍니다.
단일 최상 휴리스틱
README의 대상 독자에 맞춰 두 가지 휴리스틱을 적용하세요:
사용자 계약: 새 사용자가 README를 처음 보고 소스 코드를 읽지 않고도 작고 올바른 통합을 배포할 수 있는가? 모든 README에 필수입니다.
기여자 계약: 새 기여자가 README를 처음 보고 관리자와 대화하지 않고도 작고 올바른 PR을 배포할 수 있는가? README가 기여자 진입점인 경우 필수입니다. README에서
CONTRIBUTING.md가 연결된 경우 선택 사항 — 이 경우 해당 파일을 기준으로 기여자 경험을 평가하세요.
기여자 계약을 충족하려면 README(또는 CONTRIBUTING.md)가 표면뿐만 아니라 아키텍처를 설명해야 합니다. 대부분의 프로젝트가 이 테스트를 통과하지 못하며, 이것이 일반적으로 우연한 기여를 받는 프로젝트와 그렇지 않은 프로젝트의 차이입니다.
사용자 계약이 실패하면 섹션 1~7의 표면적 개선은 무시됩니다. 기여자 계약만 실패하고 그리고 연결된 CONTRIBUTING.md가 없는 경우에도 여전히 실제 결함입니다. 플래그를 지정하되 사용자 대상 강점을 무시하지 마세요.
안티패턴 (자동 감점)
발견 시 명시적으로 표시하세요. 더 큰 문제를 신호합니다.
| 안티패턴 | 이유 |
|---|---|
| 참조 문서가 있어야 할 곳에 마케팅 카피 | 독자는 사실이 필요하지, 홍보가 아닙니다 |
| 코드 블록 대신 코드 스크린샷 | 복사-붙여넣기 불가, 검색 불가, 접근성 불가 |
| "소스 참조"를 문서로 사용 | 관리자의 책임을 모든 독자에게 떠넘깁니다 |
| 섹션 제목에 매핑되지 않는 이모지 기반 기능 목록 | 탐색 가치 없는 장식 |
| 목적 없는 배지 — 약 6개 이상, 또는 고유 신호(CI, 라이선스, 다운로드 수, 버전, 커버리지, 지원 채널)에 매핑되지 않는 배지 | 품질의 맹목적 신호; 목적 있는 배지 5개는 괜찮지만, 장식용 배지 10개는 아닙니다 |
| 실제로는 우선순위나 일정에 대한 신호 없는 소원 목록인 "로드맵" | 프로젝트가 충족할 수 없는 기대를 설정합니다 |
| "vX 기준 기록됨" 면책 조항 없이 연결된 비디오/블로그 게시물 | 독자가 오래된 콘텐츠에 시간을 낭비합니다 |
독자에게 제공되는 플레이스홀더 텍스트 (your-repo, TODO, lorem ipsum, 깨진 앵커 링크) | 첫 화면 위에서 가장 큰 신뢰 킬러 — 게시 전에 아무도 교정하지 않았음을 신호합니다 |
역순 레이어링 — 필요한 헬퍼(예: embedQuery)가 이를 사용하는 빠른 시작 후에 정의됨 | "최소 경로"의 복사-붙여넣기가 ReferenceError를 발생시킵니다; 예제 블록이 실제로 자체 포함되지 않습니다 |
| "작동 확인" 스니펫 없이 구성에서 끝나는 빠른 시작 | 독자가 설치가 효과가 있었는지 확인할 방법이 없습니다; 문서가 수집을 다루지만 검색은 다루지 않습니다 |
출력 형식
README를 평가할 때 다음을 생성하세요:
- 평결 — 한 줄. (예: "설치는 강력하나 멘탈 모델이 약함. 새 사용자는 10분 안에 배포하지만 새 기여자는 불가능.")
- 섹션별 결과 — 8개 축 각각에 대해 무엇이 잘 작동하고 무엇이 누락되었는지, 줄/제목 참조와 함께.
- 적중된 안티패턴 — 위 표에서 해당하는 항목을 나열하세요.
- 최상 휴리스틱 답변 — 사용자 계약과 기여자 계약 모두에 대해 예/아니오와 근거를 제시하세요.
CONTRIBUTING.md가 연결된 경우 기여자 테스트가 해당 파일로 범위가 지정됨을 명시하세요. - 수정 목록 — 우선순위에 따른 수정 사항 (영향이 가장 큰 것부터).