1. README.md — 왜 쓰고, 어떻게 쓰는가

README

# 🌟 프로젝트 이름
> 저희 프로젝트를 소개합니다! 간단한 설명을 여기에 적어주세요 🙏
> 라이브 데모는 [_여기_](https://www.example.com)에서 만나보실 수 있어요 ✨

## 📋 목차
* [프로젝트 소개](#프로젝트-소개)
* [사용 기술](#사용-기술)
* [주요 기능](#주요-기능)
* [스크린샷](#스크린샷)
* [설치 방법](#설치-방법)
* [사용법](#사용법)
* [프로젝트 현황](#프로젝트-현황)
* [개선 예정 사항](#개선-예정-사항)
* [감사의 말씀](#감사의-말씀)
* [연락처](#연락처)

## 💡 프로젝트 소개
- 이 프로젝트에 대해 소개해 드릴게요!
- 어떤 불편함을 해결하고자 했나요?
- 이 프로젝트를 만든 이유가 궁금하시죠? 😊
- 어떤 목표를 가지고 시작하게 되었는지 적어주세요.

## 🛠 사용 기술
- 기술 1 - 버전 1.0
- 기술 2 - 버전 2.0
- 기술 3 - 버전 3.0

## 📁 포함된 항목

```text
folder1/
└── folder2/
    ├── folder3/
    │   ├── file1
    │   └── file2
    └── folder4/
        ├── file3
        └── file4

✅ 주요 기능

알차게 준비한 기능들이에요 🎉

• 기능 1
• 기능 2
• 기능 3

📸 스크린샷

프로젝트 스크린샷을 여기에 추가한다.

⚙️ 설치 방법

필요한 의존성은 requirements.txt 또는 Pipfile.lock에서 확인하실 수 있어요.

로컬 환경에서 실행하는 방법을 단계별로 친절하게 안내해 드릴게요 😄

🚀 사용법

이렇게 사용하시면 돼요! 다양한 예시와 함께 설명드릴게요.

여기에-코드를-작성해-주세요

📌 프로젝트 현황

현재 상태: 진행 중 / 완료 / 잠시 멈춤 🚧

🔧 개선 예정 사항

더 좋은 서비스를 위해 열심히 준비 중이에요 💪

개선할 부분:

• 개선 항목 1
• 개선 항목 2

앞으로 추가할 기능:

• 추가 기능 1
• 추가 기능 2

🙌 감사의 말씀

• 이 프로젝트는 ...에서 큰 영감을 받았어요.
• 이 튜토리얼 덕분에 완성할 수 있었습니다.
• 도움 주신 모든 분들께 진심으로 감사드려요 🥰

📬 연락처

@flynerdpl 이 만들었습니다. 언제든지 편하게 연락 주세요! 😊

## 1.1. README.md란

프로젝트 루트에 위치하는 **첫 번째 문서**다. GitHub, GitLab 등 코드 호스팅 플랫폼은 저장소에 접속하면 이 파일을 자동으로 렌더링해서 보여준다. 방문자가 가장 먼저 읽는 글이므로, 프로젝트의 **현관문** 역할을 한다.

파일 확장자 `.md`는 Markdown 문법으로 작성한다는 뜻이다. 파일명이 전부 대문자인 이유는 유닉스(Unix) 관례에서 비롯된다. 디렉터리 목록에서 소문자 파일보다 대문자 파일이 먼저 정렬되기 때문에, 가장 먼저 눈에 띄도록 `README`라는 이름을 쓴다.

---

## 1.2. 왜 작성하는가

### 1.2.1. 프로젝트를 설명한다

코드만 올려둔 저장소는 본인조차 3개월 뒤에 목적을 잊는다. README가 있으면 "이 프로젝트가 무엇이고, 왜 만들었고, 어떻게 쓰는지"를 즉시 파악할 수 있다.

### 1.2.2. 협업의 진입 장벽을 낮춘다

팀원이 합류하거나 오픈소스에 기여자가 참여할 때, README가 없으면 "어떻게 설치해요?", "어떤 명령어로 실행해요?" 같은 질문이 반복된다. README 하나로 이런 질문의 80%를 해결한다.

### 1.2.3. 포트폴리오가 된다

취업·이직 시 면접관은 GitHub 저장소를 본다. README가 잘 정리된 프로젝트는 코드 품질과 무관하게 **신뢰감**을 준다. 반대로 README가 없으면 아무리 좋은 코드라도 들여다볼 동기가 생기지 않는다.

### 1.2.4. 미래의 나를 위한 메모다

"이 프로젝트는 Node 18 이상에서만 동작한다", "환경변수 `.env`에 API 키를 넣어야 한다" 같은 정보는 시간이 지나면 잊힌다. README에 기록해두면 나 자신이 가장 큰 수혜자가 된다.

---

## 1.3. 어떻게 작성하는가

### 1.3.1. 기본 구조

README에 정해진 규격은 없지만, 대부분의 프로젝트가 따르는 공통 구조가 있다. 아래 순서대로 작성하면 된다.

1. 프로젝트 제목
2. 한 줄 소개
3. 기술 스택
4. 설치 방법
5. 실행 방법
6. 폴더 구조
7. 주요 기능
8. 환경변수
9. 팀원 / 기여 방법
10. 라이선스

### 1.3.2. 섹션별 작성법

#### 1.3.2.1. 프로젝트 제목 + 한 줄 소개

```markdown
# ROOKIZ

키즈 전용 OTT 미디어 서비스 — 아이에게 안전한 콘텐츠만 큐레이션한다.

제목은 h1으로 한 번만 쓴다. 바로 아래에 한 줄로 프로젝트의 정체를 밝힌다. 이 한 줄만 읽어도 "아, 이런 프로젝트구나"를 알 수 있어야 한다.

1.3.2.2. 기술 스택

프로젝트에 사용한 핵심 기술을 나열한다. 뱃지(badge) 이미지를 쓰는 경우도 많지만, 텍스트만으로도 충분하다.

## 기술 스택

- **프론트엔드** — React 19, Vite, Tailwind CSS v4, React Router v7
- **백엔드** — FastAPI, Python 3.12
- **외부 API** — TMDB API, HuggingFace Inference API
- **배포** — Render (백엔드), Vercel (프론트엔드)

1.3.2.3. 설치 방법

클론(clone)부터 의존성 설치까지, 처음 받는 사람이 따라 할 수 있도록 명령어를 순서대로 적는다.

## 설치

git clone https://github.com/team/rookiz.git
cd rookiz
npm install

핵심 원칙: 명령어를 복사·붙여넣기만 하면 설치가 끝나야 한다. 중간에 "알아서 설정하세요" 같은 문장이 들어가면 실패한 README다.

1.3.2.4. 실행 방법

개발 서버를 띄우는 명령어와 접속 주소를 적는다.

## 실행

npm run dev
# → http://localhost:5173

백엔드가 별도로 있다면 프론트/백엔드 실행 명령어를 구분해서 적는다.

## 실행

### 프론트엔드
npm run dev

### 백엔드
cd server
uvicorn main:app --reload

1.3.2.5. 폴더 구조

프로젝트의 디렉터리 구조를 트리 형태로 보여준다. 전체를 다 나열할 필요는 없고, 핵심 폴더만 표시하면 된다.

## 폴더 구조

rookiz/
├── public/
├── src/
│   ├── components/    # 재사용 컴포넌트
│   ├── pages/         # 라우트별 페이지
│   ├── hooks/         # 커스텀 훅
│   ├── api/           # API 호출 함수
│   └── App.jsx
├── server/            # FastAPI 백엔드
├── .env.example
└── package.json

1.3.2.6. 주요 기능

프로젝트가 제공하는 핵심 기능을 간결하게 정리한다.

## 주요 기능

- TMDB 기반 키즈 콘텐츠 검색 및 필터링
- AI 기반 맞춤 콘텐츠 추천
- 시청 기록 관리 및 보호자 모드
- 반응형 UI (모바일 / 태블릿 / 데스크톱)

1.3.2.7. 환경변수

.env 파일에 어떤 값을 넣어야 하는지 안내한다. 실제 키 값은 절대 넣지 않는다. 대신 .env.example 파일을 함께 커밋하고, README에서 그 파일을 참조하도록 안내한다.

## 환경변수

`.env.example`을 복사하여 `.env`를 만든 뒤 값을 채운다.

cp .env.example .env

| 변수명          | 설명        | 예시                    |
| --------------- | ----------- | ----------------------- |
| `VITE_TMDB_KEY` | TMDB API 키 | `abc123...`             |
| `VITE_API_URL`  | 백엔드 주소 | `http://localhost:8000` |

1.3.2.8. 팀원 / 기여 방법

팀 프로젝트라면 팀원과 담당 영역을 명시한다.

## 팀원

| 이름 | 역할              | GitHub                           |
| ---- | ----------------- | -------------------------------- |
| 김OO | 프론트엔드 (메인) | [@kim](https://github.com/kim)   |
| 이OO | 백엔드 / API      | [@lee](https://github.com/lee)   |
| 박OO | UI/UX 디자인      | [@park](https://github.com/park) |
| 최OO | 프론트엔드 (서브) | [@choi](https://github.com/choi) |

1.3.2.9. 라이선스

오픈소스 프로젝트라면 라이선스를 명시한다. 팀 프로젝트·과제용이라면 생략해도 무방하다.

## 라이선스

MIT License

---

1.4. 자주 하는 실수

1.4.1. ❌ README를 아예 안 쓴다

가장 흔한 실수다. "나중에 쓰지" 하다가 프로젝트가 끝난다. 첫 커밋에 README를 함께 만드는 습관을 들여야 한다.

1.4.2. ❌ 설치·실행 명령어가 빠져있다

README의 존재 이유 중 절반은 "이걸 어떻게 돌리는가"를 알려주는 것이다. 기술적 설명이 아무리 훌륭해도, 실행 방법이 없으면 무용지물이다.

1.4.3. ❌ 오래된 정보가 방치된다

프로젝트가 진행되면서 구조가 바뀌는데, README는 초기 버전 그대로인 경우가 많다. 코드를 바꿀 때 README도 함께 업데이트해야 한다.

1.4.4. ❌ 너무 장황하게 쓴다

README는 매뉴얼이 아니다. 핵심만 간결하게 쓰고, 상세한 문서가 필요하면 docs/ 폴더에 별도 파일로 분리한다.

1.4.5. ❌ .env 파일에 실제 키를 커밋한다

README가 아니라 .gitignore 영역의 문제이지만, README에 환경변수 섹션을 만들면서 실수로 실제 API 키를 적는 경우가 있다. 한 번 커밋된 키는 히스토리에 남으므로, .env.example에 빈 값만 넣는 패턴을 반드시 따른다.

---

1.5. 실전 템플릿

아래는 최소한의 README 템플릿이다. 복사해서 프로젝트에 맞게 수정하면 된다.

# 프로젝트 이름

한 줄 소개를 여기에 적는다.

## 기술 스택

- 프론트엔드 — React, Vite, Tailwind CSS
- 백엔드 — FastAPI
- 배포 — Render, Vercel

## 설치

git clone https://github.com/username/project.git
cd project
npm install

## 실행

npm run dev

## 환경변수

cp .env.example .env

| 변수명         | 설명   |
| -------------- | ------ |
| `VITE_API_KEY` | API 키 |

## 팀원

| 이름 | 역할       |
| ---- | ---------- |
| OOO  | 프론트엔드 |
| OOO  | 백엔드     |

---

1.6. AI로 README 생성하기

프로젝트 정보를 직접 정리하기 번거롭다면, AI에게 맡길 수 있다. 아래 프롬프트를 복사한 뒤 [ ] 안의 내용만 자기 프로젝트에 맞게 채워서 사용한다.

1.6.1. 기본 프롬프트

아래 정보를 바탕으로 GitHub README.md를 작성해줘.
마크다운 형식으로, 한국어로 작성한다.

- 프로젝트명: [ROOKIZ]
- 한 줄 소개: [키즈 전용 OTT 미디어 서비스]
- 기술 스택: [React 19, Vite, Tailwind CSS v4, React Router v7, FastAPI, TMDB API]
- 설치 명령어: [npm install]
- 실행 명령어: [npm run dev]
- 환경변수: [VITE_TMDB_KEY, VITE_API_URL]
- 팀원: [김OO(프론트), 이OO(백엔드), 박OO(디자인), 최OO(프론트)]
- 주요 기능: [콘텐츠 검색, AI 추천, 시청 기록, 보호자 모드]

포함할 섹션: 프로젝트 소개, 기술 스택, 설치, 실행, 폴더 구조, 주요 기능, 환경변수, 팀원

1.6.2. 기존 코드베이스 기반 프롬프트

이미 코드가 있는 상태라면, package.json이나 폴더 구조를 함께 넘기는 것이 훨씬 정확하다.

아래 package.json과 폴더 구조를 분석해서 README.md를 작성해줘.

[package.json 내용 붙여넣기]

[폴더 구조 붙여넣기 — tree -L 2 명령어 결과]

조건:
- 한국어, 마크다운 형식
- 설치/실행 방법은 명령어만 간결하게
- 환경변수는 .env.example 기준으로 테이블 형태로
- 팀원 섹션은 빈 테이블로 남겨둬

1.6.3. Claude Code 사용 시

Claude Code 환경에서는 프로젝트 루트에서 바로 생성할 수 있다.

이 프로젝트의 package.json, 폴더 구조, .env.example을 읽고
README.md를 생성해줘.

조건:
- 기존 README.md가 있으면 덮어쓰지 말고 내용을 보여줘
- 설치/실행 명령어는 package.json의 scripts 기준으로
- 환경변수는 .env.example에서 추출
- 폴더 구조는 src/ 하위 2단계까지만

1.6.4. 프롬프트 작성 팁

구체적인 정보를 넣을수록 결과가 좋다. "README 만들어줘"라고만 하면 AI가 추측으로 채워 넣는다. 프로젝트명, 기술 스택, 명령어처럼 확정된 사실을 넘겨야 정확한 결과가 나온다.

조건을 명시하면 원하는 포맷이 나온다. "한국어로", "테이블 형태로", "코드 블록으로" 같은 조건을 붙이면 후속 수정이 줄어든다.

생성 결과는 반드시 검토한다. AI가 만든 README에는 실제와 다른 폴더명, 존재하지 않는 스크립트, 틀린 포트 번호가 섞일 수 있다. 복사·붙여넣기 전에 한 번 읽어보는 과정이 필수다.

---

1.7. 정리

README.md는 프로젝트의 첫인상이다. 잘 쓰면 협업이 쉬워지고, 포트폴리오 가치가 올라가고, 미래의 나 자신도 감사하게 된다. 거창할 필요 없다. 제목, 한 줄 소개, 설치, 실행 — 이 네 가지만 있어도 README가 없는 프로젝트보다 100배 낫다.