웹 개발

개인 프로젝트 README를 쓸 때 내가 꼭 넣는 것들

몇 달 뒤 자신이 다시 봤을 때 바로 이해할 수 있는 README가 좋은 README다. 매번 비슷한 내용을 쓰면서 정리된 기준을 공유한다.

2026년 6월 22일·1분 읽기

개인 프로젝트 README를 작성하다 보면 처음엔 열심히 쓰다가 나중엔 대충 넘기게 된다. 그런데 6개월 뒤에 다시 프로젝트를 열면 '이게 뭐 하는 코드였지'를 되새기는 데 시간을 쓰게 된다. 지금은 짧아도 아래 항목만은 꼭 남긴다.

이 프로젝트가 뭔지 한두 문장으로

기술 스택 나열보다 먼저 온다. "무엇을 해결하는 도구인지"를 한 줄로 쓴다.

## 이게 뭔가요
내 Hetzner 서버의 RAID, 디스크, 도커 상태를 한 화면에서 보는 개인 대시보드.

설치 안내보다 먼저 어떤 환경이 필요한지 적는다.

## 요구사항
- Node.js 20+
- pnpm 9+
- Docker (로컬 실행 시 선택)

이 부분이 핵심이다. 클론하고 처음 실행하는 과정을 빠뜨리지 않고 쓴다.

git clone https://github.com/example/project
cd project
pnpm install
cp .env.example .env     # 환경변수 채우기
pnpm db:migrate
pnpm dev

"환경변수 채우기" 같은 주석 한 줄이 있어도 없어도 차이가 크다. 처음 실행할 때 .env.example이 없으면 뭘 넣어야 할지 모른다.

.env.example이 있다면 링크만 해도 되지만, 주요 환경변수는 README에 직접 설명해두는 게 낫다.

| 변수 | 설명 | 예시 |
|------|------|------|
| DATABASE_URL | SQLite 파일 경로 | file:./dev.db |
| SECRET_KEY | 세션 서명에 쓰는 임의 문자열 | 랜덤 32자 |

텍스트 설명보다 스크린샷 하나가 더 빠르다. 특히 UI가 있는 프로젝트라면 첫 화면 스크린샷 하나만 넣어도 README 퀄리티가 확 올라간다.

파일이 많아져서 어디가 어딘지 헷갈리는 시점이 오면 그때 추가한다. 작은 프로젝트에서 미리 적어두면 코드 바뀔 때마다 README도 같이 고쳐야 해서 오히려 짐이 된다.

README를 완성본으로 만들려고 하면 결국 안 쓰게 된다. 프로젝트를 처음 공개할 때는 위 항목만 채우고, 나중에 기억 안 나는 부분이 생기면 그때 추가하는 방식이 오래 간다.