README에 무엇을 써야 하는가 — 읽는 사람은 세 종류다

세 종류의 방문자

README를 쓸 때 대상을 하나로 잡으면 길이가 애매해진다. 실제로는 세 유형이 온다.

| 유형 | 목적 | 필요한 것 | 체류 시간 |

|---|---|---|---|

| 훑는 사람 | 이게 뭔지만 확인 | 한 줄 설명, 화면 | 10초 |

| 써보려는 사람 | 실행해보기 | 설치·실행 명령 | 2분 |

| 검토하는 사람 | 구현 수준 판단 | 구조, 설계 판단 | 10분 |

순서가 이 순위를 따라야 한다. 아래로 갈수록 상세해지는 구조다.

첫 화면에 들어가야 할 것

스크롤 없이 보이는 영역에서 "이게 뭔가"가 끝나야 한다.

```markdown

프로젝트명

한 줄 설명 — 무엇을 하는 도구인지, 누구를 위한 것인지.

![스크린샷 또는 데모 GIF]

• 데모: (있다면 링크)
• 문서: (있다면 링크)

```

한 줄 설명은 기술 나열이 아니라 용도를 써야 한다. "React와 Node로 만든 프로젝트"는 무엇을 하는지 알려주지 않는다.

실행까지 가는 최단 경로

두 번째 유형(써보려는 사람)을 위한 부분이다. 기준은 하나다 — 복사·붙여넣기로 실행까지 도달 가능한가.

```markdown

실행

git clone <주소>

cd <폴더>

npm install

npm run dev

필요 환경: Node 20 이상

환경 변수: .env.example 참고

```

자주 빠지는 것:

• 필요한 런타임 버전 (없으면 사용자 환경에서 실패)
• 환경 변수 목록과 예시 파일
• 실행 후 접속할 주소

이 셋이 없으면 대부분의 사람이 여기서 이탈한다.

검토하는 사람을 위한 부분

포트폴리오 용도라면 이 부분이 실질적 차별점이 된다. 기능 목록이 아니라 판단의 흔적을 보여준다.

```markdown

구조

src/

features/ 기능 단위 모듈

shared/ 공통 유틸·컴포넌트

app/ 진입점·라우팅

설계 판단

• 상태 관리를 도입하지 않은 이유: 화면 간 공유 상태가 두 개뿐이라 Context로 충분
• 서버 캐시를 직접 구현한 이유: 요청 패턴이 단순해 라이브러리 도입 비용이 더 큼

```

기술 스택 나열보다 왜 그것을 골랐는지 한 줄이 훨씬 많은 것을 보여준다. 반대로 유행하는 것을 전부 넣었다는 인상은 감점 요인이 되기 쉽다.

길이 관리

README가 길어지면 첫 화면의 효율이 떨어진다. 분리 기준:

• README — 위 세 유형이 필요한 것까지
• docs/ — 상세 API, 아키텍처, 기여 가이드
• CHANGELOG — 버전별 변경

한 파일에 다 넣으면 훑는 사람이 첫 화면에서 이탈한다.

자주 보이는 문제

• 미완성 상태 방치 — "개발 중"만 적힌 README는 검토 대상에서 빠진다
• 실행 안 되는 명령어 — 리팩터링 후 README를 안 고친 경우가 많다. 새 환경에서 한 번 따라 해보면 바로 드러난다
• 스크린샷 없음 — 화면이 있는 프로젝트인데 이미지가 없으면 이해 비용이 크게 오른다
• 템플릿 잔여물 — 생성기가 만든 기본 문구가 남아 있으면 관리되지 않는 저장소로 보인다

최종 수정 2026-08-28