README 작성 가이드

이 스킬은 프로젝트의 README.md 파일을 작성하거나 업데이트할 때 사용합니다. 아래의 작성 규칙과 템플릿을 엄격히 준수하십시오.

작성 규칙

핵심 원칙

1. 사실 기반 작성: 모든 {placeholder}는 실제 프로젝트 파일/폴더/코드/설정에서 추출한 정보로 채운다.
2. 허구 금지: 존재하지 않는 파일, 폴더, 환경변수, 기능을 생성하거나 언급하지 않는다.
3. 간결성: 불필요한 형용사 없이 명확하고 간결하게 작성한다.
4. 한국어 우선: 고유명사(기술명, 라이브러리명 등)를 제외한 모든 내용은 한국어로 작성한다.

섹션 선택 기준

섹션	필수	포함 조건
Overview	✅	항상 포함
Tech Stack	✅	항상 포함
Architecture	⚪	서비스 간 통신 또는 외부 의존성이 있는 경우
Directory Structure	✅	항상 포함
Configuration	⚪	.env.example 또는 config/ 폴더가 존재하는 경우
Quick Start	✅	항상 포함
Operations Guide	⚪	docker-compose.yml 또는 배포 스크립트가 존재하는 경우
Troubleshooting	⚪	알려진 이슈가 있는 경우
Contributing	⚪	오픈소스 또는 CONTRIBUTING.md가 존재하는 경우
License	⚪	LICENSE 파일이 존재하는 경우

프로젝트 유형 판단 기준:

• 오픈소스: LICENSE 파일 존재, public 저장소
• 내부 프로젝트: LICENSE 없음, private 저장소 → Contributing, License 섹션 생략

섹션별 작성 지침

섹션	참조 소스	작성 방법
Overview	pyproject.toml, package.json, 코드 주석	배경-문제-목표 구조로 3~6줄 작성
Tech Stack	pyproject.toml, package.json, Dockerfile	실제 사용 중인 기술만 배지로 표시
Architecture	코드 구조, Dockerfile, docker-compose.yml	Mermaid 다이어그램으로 작성
Directory	프로젝트 루트 기준 tree 명령	주요 폴더만 선별하여 역할 설명
Configuration	.env.example, config 폴더	실제 환경변수와 설정 파일만 기재
Quick Start	main.py, entrypoint, 빌드 스크립트	실제 테스트된 명령어만 기재
Operations	docker-compose.yml, 배포 스크립트	실제 운영 환경 기준 작성

참조 데이터 우선순위

AI는 다음 파일들을 순서대로 분석하여 README를 작성한다:

1. 의존성 정의: pyproject.toml, package.json, Cargo.toml, go.mod
2. 락 파일: uv.lock, package-lock.json, Cargo.lock
3. 인프라 설정: Dockerfile, docker-compose.yml, k8s/ 폴더
4. 환경 설정: .env.example, config/ 폴더
5. 진입점: main.py, app.py, index.ts, main.go
6. 프로젝트 구조: tree -a -I 'node_modules|__pycache__|.git|.venv'

---

README 표준 템플릿

# {Project Name}

{한 줄 프로젝트 설명}

[![{Language}](https://img.shields.io/badge/{Language}-{Version}-blue?logo={logo})]()
[![License](https://img.shields.io/badge/License-{License}-green.svg)]()

[시작하기](#-quick-start) · [문서](#-documentation)

## 📋 Table of Contents

- [Overview](#-overview)
- [Tech Stack](#-tech-stack)
- [Architecture](#-architecture)
- [Directory Structure](#-directory-structure)
- [Configuration](#-configuration)
- [Quick Start](#-quick-start)
- [Operations Guide](#-operations-guide)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [Documentation](#-documentation)
- [License](#-license)

## 📘 Overview

### 배경

{프로젝트가 시작된 배경과 맥락}

### 해결하려는 문제

- {핵심 문제 1}
- {핵심 문제 2}
- {핵심 문제 3}

### 목표

{이 프로젝트가 달성하려는 구체적인 목표}

### 주요 기능

- **{기능명 1}**: {설명}
- **{기능명 2}**: {설명}
- **{기능명 3}**: {설명}

> 🔗 상세 기획: [{문서명}]({Notion URL})

## 🛠 Tech Stack

| Category       | Technology     | Version |
| -------------- | -------------- | ------- |
| Language       | {언어명}       | {버전}  |
| Framework      | {프레임워크명} | {버전}  |
| Database       | {DB명}         | {버전}  |
| Infrastructure | {인프라}       | {버전}  |

### 기술 선택 근거

| 기술     | 선택 이유   | 검토했던 대안       |
| -------- | ----------- | ------------------- |
| {기술명} | {선택 이유} | {대안 및 제외 이유} |

## 🏗 Architecture

### System Overview

```mermaid
flowchart TB
    subgraph Client
        A[{클라이언트 유형}]
    end

    subgraph Service
        B[{서비스/API}]
        C[{처리 로직}]
    end

    subgraph Data
        D[(Database)]
        E[{외부 서비스}]
    end

    A --> B
    B --> C
    C --> D
    C --> E
```

### Data Flow

```mermaid
flowchart LR
    A[{입력}] --> B[{처리 1}]
    B --> C[{처리 2}]
    C --> D[{출력}]
    B --> E[(저장소)]
```

### 주요 컴포넌트

| 컴포넌트     | 역할        | 기술        |
| ------------ | ----------- | ----------- |
| {컴포넌트명} | {역할 설명} | {사용 기술} |

> 🔗 아키텍처 상세: [{문서명}]({링크})

## 📁 Directory Structure

```text
{project-root}/
├── src/               # 소스 코드
│   ├── {folder}/     # {역할}
│   └── {folder}/     # {역할}
├── tests/            # 테스트 코드
├── config/           # 설정 파일
├── {file}            # {역할}
└── README.md
```

### 폴더별 상세 설명

| 폴더       | 역할   | 주요 파일     |
| ---------- | ------ | ------------- |
| `{폴더명}` | {역할} | {주요 파일들} |

## ⚙ Configuration

### 환경 변수

| 변수명      | 필수 | 설명   | 기본값   | 예시   |
| ----------- | :--: | ------ | -------- | ------ |
| `{ENV_VAR}` |  ✅  | {설명} | {기본값} | {예시} |
| `{ENV_VAR}` |  ⚪  | {설명} | {기본값} | {예시} |

### 설정 파일

| 파일       | 용도   |
| ---------- | ------ |
| `{파일명}` | {용도} |

### 환경별 설정

| 환경       | 설정 파일 | 특이사항   |
| ---------- | --------- | ---------- |
| Local      | {파일명}  | {특이사항} |
| Production | {파일명}  | {특이사항} |

> 🔗 환경 설정 가이드: [{문서명}]({링크})

## ⚡ Quick Start

### 요구사항

- {Runtime}: {버전}
- {Package Manager}: {버전}
- {기타 의존성}

### 설치

```bash
# 1. 저장소 클론
git clone {repository_url}
cd {project_name}

# 2. 환경 설정
cp .env.example .env

# 3. 의존성 설치
{install_command}
```

### 실행

```bash
# 로컬 개발
{run_command}

# Docker 실행 (선택)
docker-compose up -d
```

### 동작 확인

```bash
{health_check_command}
```

### 테스트

```bash
{test_command}
```

## 🛠 Operations Guide

### 배포

| 환경   | 방법   | 명령어     |
| ------ | ------ | ---------- |
| {환경} | {방법} | `{명령어}` |

### 서비스 관리

```bash
# 서비스 상태 확인
{status_command}

# 서비스 재시작
{restart_command}
```

### 로그 확인

```bash
{log_command}
```

### 모니터링

| 항목   | 도구     | 접근 방법       |
| ------ | -------- | --------------- |
| {항목} | {도구명} | {URL 또는 명령} |

> 🔗 운영 매뉴얼: [{문서명}]({링크})

## 🧩 Troubleshooting

### 자주 발생하는 문제

#### {에러 메시지 또는 증상}

- **원인**: {원인 설명}
- **해결**: {해결 방법}

### 알려진 제약사항

| 제약사항 | 영향   | 대응 방안 |
| -------- | ------ | --------- |
| {제약}   | {영향} | {대응}    |

## 🤝 Contributing

프로젝트 기여를 환영합니다.

1. 이 저장소를 Fork합니다
2. Feature 브랜치를 생성합니다 (`git checkout -b feature/{feature-name}`)
3. 변경사항을 커밋합니다 (`git commit -m 'feat: {description}'`)
4. 브랜치에 Push합니다 (`git push origin feature/{feature-name}`)
5. Pull Request를 생성합니다

### 커밋 컨벤션

| Type       | 설명             |
| ---------- | ---------------- |
| `feat`     | 새로운 기능 추가 |
| `fix`      | 버그 수정        |
| `docs`     | 문서 수정        |
| `refactor` | 리팩토링         |
| `test`     | 테스트 추가/수정 |
| `chore`    | 빌드, 설정 변경  |

## 📚 Documentation

| 문서     | 설명   | 링크               |
| -------- | ------ | ------------------ |
| {문서명} | {설명} | [{문서명}]({링크}) |

## 📄 License

이 프로젝트는 [{라이선스명}] 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.