README가 왜 중요한가

GitHub 저장소에 들어왔을 때 가장 먼저 보이는 것이 README입니다. 잘 작성된 README는 프로젝트의 신뢰도를 높이고, 다른 개발자들이 기여하거나 사용하도록 유도합니다. 반대로 빈 README나 "Coming soon"만 적힌 저장소는 아무리 코드가 훌륭해도 아무도 쓰지 않습니다.

오픈소스 프로젝트뿐 아니라 개인 포트폴리오 저장소, 사내 라이브러리, 팀 프로젝트 모두 마찬가지입니다. README는 프로젝트의 첫 번째 문서입니다.

필수 구성 요소

1. 프로젝트 이름과 한 줄 설명

가장 먼저 나와야 할 것은 프로젝트 이름과 무엇을 하는 도구인지 한 문장으로 설명하는 부분입니다.

# ProjectName
> 마크다운 파일을 PDF로 변환해주는 CLI 도구

인용구(>)를 쓰면 시각적으로 한 줄 설명이 강조됩니다.

2. 뱃지 (Badges)

Shields.io를 이용하면 빌드 상태, 라이선스, 버전, 다운로드 수 등을 뱃지로 표시할 수 있습니다.

[![npm version](https://img.shields.io/npm/v/your-package)](https://npmjs.com/package/your-package)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

뱃지는 3~5개가 적당합니다. 너무 많으면 오히려 지저분해 보입니다.

3. 스크린샷 또는 데모 GIF

백 마디 설명보다 하나의 스크린샷이 낫습니다. 특히 UI가 있는 프로젝트라면 반드시 넣으세요.

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

*실행 화면 예시*

GIF 녹화는 macOS에서는 Kap, Windows에서는 ScreenToGif를 추천합니다.

4. 설치 방법 (Installation)

설치 방법은 복사 붙여넣기만 하면 바로 실행되도록 명확하게 써야 합니다.

## 설치

```bash
npm install your-package
```

또는 yarn을 사용한다면:

```bash
yarn add your-package
```

5. 사용 방법 (Usage)

가장 기본적인 사용 예제를 먼저 보여주세요. 복잡한 옵션은 그 다음입니다.

## 사용 방법

```javascript
const tool = require('your-package');

// 기본 사용
tool.convert('input.md', 'output.pdf');

// 옵션과 함께
tool.convert('input.md', 'output.pdf', {
  theme: 'github',
  fontSize: 14
});
```

6. API 문서 또는 옵션 목록

라이브러리라면 옵션을 표로 정리하면 깔끔합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| theme | string | 'default' | 테마 선택 |
| fontSize | number | 12 | 폰트 크기(px) |
| margin | number | 20 | 여백(px) |

7. 기여 방법 (Contributing)

오픈소스라면 기여 방법을 안내하세요. 간단한 몇 줄이라도 있으면 외부 기여자가 생길 가능성이 훨씬 높아집니다.

## 기여하기

버그 리포트와 기능 제안은 [Issues](../../issues)에 올려주세요.
PR은 언제나 환영입니다!

8. 라이선스

라이선스는 빠뜨리기 쉬운데, 기업이나 다른 개발자가 사용하려면 꼭 필요합니다.

## 라이선스

[MIT](LICENSE) © 2026 Your Name

잘 만든 README의 패턴

유명 오픈소스 프로젝트의 README를 살펴보면 공통적인 패턴이 보입니다.

  • Vue.js: 심플한 소개 + 링크 중심 구성
  • React: 공식 문서 링크로 바로 안내
  • tailwindcss: 한 줄 설명 + 빠른 시작 강조

공통점은 처음 30초 안에 무엇인지, 어떻게 시작하는지를 알 수 있다는 점입니다.

자주 하는 실수

  • 설치 명령어에 버전 정보 없음: Node.js, Python 등 런타임 버전 요구사항을 적어야 합니다.
  • 환경 변수 설명 누락: .env.example 파일과 함께 어떤 환경 변수가 필요한지 설명하세요.
  • 오래된 스크린샷: UI가 바뀌었는데 스크린샷이 구버전이면 신뢰도가 떨어집니다.
  • 영어/한국어 혼용 혼란: 타겟 사용자에 맞게 언어를 일관되게 유지하세요.

README 템플릿

처음부터 만들기 어렵다면 다음 구조를 복사해서 사용하세요.

# 프로젝트 이름
> 한 줄 설명

뱃지들...

## 소개
(2~3줄 설명)

## 스크린샷
(이미지)

## 설치
```bash
npm install ...
```

## 사용 방법
```js
...
```

## 기여하기
이슈 또는 PR 환영

## 라이선스
MIT

README는 한 번에 완성할 필요가 없습니다. 프로젝트가 성장하면서 함께 발전시켜 나가는 것이 자연스럽습니다. 일단 최소한의 내용으로 시작하는 것이 아무것도 없는 것보다 훨씬 낫습니다.

README를 다른 플랫폼에도 옮길 계획이라면 플랫폼마다 다르게 보이는 이유를 함께 보세요.