깃허브 README 작성법: 3분 안에 파악되게

저장소에 들어온 사람이 가장 먼저, 그리고 대부분은 유일하게 읽는 문서가 README.md입니다. 코드가 아무리 좋아도 README가 비어 있으면 그 프로젝트는 남에게 존재하지 않는 것과 같습니다. 잘 쓴 README들이 공통으로 지키는 구성과 순서, 그리고 복사해서 바로 시작할 수 있는 템플릿을 정리했습니다.

최종 업데이트: 2026년 7월

1. README가 하는 일

깃허브는 저장소 루트에 README.md 파일이 있으면 저장소 첫 화면에 자동으로 렌더링해 보여줍니다. 방문자 입장에서 README는 세 가지 질문에 답해 주는 문서입니다.

이게 뭔가? 무엇을 하는 프로젝트인지
나한테 필요한가? 어떤 문제를 풀어 주는지
어떻게 쓰나? 설치하고 실행하는 방법

이 세 가지에 위에서부터 순서대로 답하는 것이 README 구성의 전부입니다. 방문자의 대다수는 첫 화면에서 스크롤 한두 번으로 판단을 끝내므로, 중요한 내용일수록 위에 있어야 합니다.

2. 기본 구성: 이 순서면 됩니다

순서	섹션	담을 내용
1	제목 + 한 줄 소개	프로젝트 이름과, 무엇을 하는지 한 문장. 이 한 문장이 README에서 가장 중요합니다
2	스크린샷·데모	화면이 있는 프로젝트라면 이미지나 GIF 하나. 백 마디 설명보다 빠릅니다
3	설치	복사해서 그대로 실행되는 명령어. 요구 버전(Node 20 이상 등)도 여기에
4	사용법	가장 기본적인 사용 예시 코드 한두 개. 전체 옵션 나열은 별도 문서로
5	라이선스	한 줄이면 충분. 오픈소스라면 필수

기여 방법, 상세 설정, 아키텍처 설명 같은 내용은 프로젝트가 커진 뒤 CONTRIBUTING.md나 docs/ 폴더로 분리하면 됩니다. 처음부터 모든 섹션을 채우려고 하지 않아도 됩니다. 위 다섯 개면 README로서 충분히 제 역할을 합니다.

3. 복사해서 쓰는 템플릿

아래를 복사해 프로젝트에 맞게 채우면 됩니다. 꺾쇠 부분만 바꾸세요.

# 프로젝트 이름

<무엇을 하는 도구인지 한 문장으로.>

![스크린샷](docs/screenshot.png)

## 설치

```bash
npm install <패키지명>
```

Node.js 20 이상이 필요합니다.

## 사용법

```js
import { example } from '<패키지명>';

example('hello');  // => 'HELLO'
```

## 라이선스

MIT

템플릿을 채우면서 렌더링이 의도대로 되는지는 마크다운 미리보기에 붙여넣어 확인할 수 있습니다. 특히 코드 블록 안에 백틱이 겹치는 부분이 깨지기 쉽습니다.

4. 한 단계 올리는 요소들

뱃지: 빌드 상태, 버전, 라이선스를 제목 아래 이미지 뱃지로 표시합니다. shields.io 형식(![라벨](https://img.shields.io/...))이 사실상 표준입니다. 서너 개면 충분하고, 열 개씩 늘어놓으면 오히려 소음입니다.
목차: README가 길어지면 상단에 섹션 링크 목차를 답니다. 깃허브는 제목에 자동으로 앵커를 만들어 주므로 [설치](#설치)처럼 연결하면 됩니다.
GIF 데모: CLI 도구나 인터랙션이 있는 프로젝트는 정지 화면보다 10초짜리 GIF가 효과적입니다.
"왜 만들었나": 비슷한 도구가 이미 있는 분야라면, 기존 도구와 무엇이 다른지 두세 줄로 적어 주는 것이 별점을 가릅니다.

5. 흔한 실수

설치 명령이 실제로 안 돌아감: README의 명령어를 새 환경에서 그대로 실행해 보지 않고 올리는 경우입니다. README 신뢰도를 가장 크게 깎는 요인입니다.
첫 문장이 배경 설명: "요즘 ~가 중요해지면서..."로 시작하면 늦습니다. 첫 문장은 프로젝트가 무엇인지여야 합니다.
이미지 경로가 로컬 절대경로: C:\Users\...나 /home/... 경로는 내 컴퓨터에서만 보입니다. 저장소 안의 상대경로로 넣어야 합니다.
업데이트 없이 방치: 코드는 바뀌었는데 README의 예시가 옛 API인 경우, 없느니만 못한 문서가 됩니다. 인터페이스가 바뀌면 README도 같은 커밋에서 고치는 습관이 좋습니다.

README를 쓰면서 렌더링 결과를 실시간으로 확인해 보세요. 표·체크박스·코드 블록까지 지원합니다.

마크다운 미리보기 열기

6. 자주 묻는 질문

파일 이름은 꼭 대문자 README.md여야 하나요?

깃허브는 readme.md, Readme.md도 인식합니다. 다만 대문자 README.md가 오랜 관례이고, 대소문자를 구분하는 시스템에서 헷갈릴 일이 없도록 관례를 따르는 것을 권합니다.

한글로 써도 되나요?

대상 사용자가 누구냐의 문제입니다. 한국어 사용자를 위한 프로젝트라면 한글 README가 당연히 낫고, 국제적으로 쓰이길 원하면 영어가 기본입니다. 둘 다 필요하면 README.md(영어)와 README.ko.md(한글)로 나누고 서로 링크하는 방식이 흔합니다.

프로필 README는 뭔가요?

깃허브 계정명과 같은 이름의 저장소를 만들고 그 안에 README.md를 넣으면 프로필 페이지 상단에 표시됩니다. 자기소개, 주력 기술, 대표 프로젝트 링크를 담는 용도로 쓰이고, 문법은 일반 README와 같습니다.

README에 쓸 마크다운 문법을 잘 모르겠어요.

제목, 목록, 코드 블록, 링크, 표 정도면 README에 필요한 문법은 전부입니다. 마크다운 문법 총정리에서 10분이면 훑을 수 있습니다.