README 작성 가이드

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

작성 규칙

핵심 원칙

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

섹션 선택 기준

프로젝트 유형 판단 기준:

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

섹션별 작성 지침

참조 데이터 우선순위

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) 파일을 참조하세요.