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 섹션 생략

섹션별 작성 지침

참조 데이터 우선순위

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 표준 템플릿

````markdown

{Project Name}

{한 줄 프로젝트 설명}

[]() []()

[시작하기](#-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

기술 선택 근거

🏗 Architecture

System Overview

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

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

주요 컴포넌트

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

📁 Directory Structure

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

폴더별 상세 설명

⚙ Configuration

환경 변수

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

설정 파일

환경별 설정

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

⚡ Quick Start

요구사항

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

설치

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

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

# 3. 의존성 설치
{install_command}

실행

# 로컬 개발
{run_command}

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

동작 확인

{health_check_command}

테스트

{test_command}

🛠 Operations Guide

배포

서비스 관리

# 서비스 상태 확인
{status_command}

# 서비스 재시작
{restart_command}

로그 확인

{log_command}

모니터링

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

🧩 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를 생성합니다

커밋 컨벤션

📚 Documentation

📄 License

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