---
name: project-readme-gen
description: |
  트리거: "readme 만들어줘", "readme 생성", "README 작성", "프로젝트 문서화"
  프로젝트 구조와 코드를 분석하여 GitHub 표준 README.md를 자동 생성한다.
  뱃지, 설치법, 사용법, API 문서, 기여 가이드, 라이선스 섹션을 포함한다.
  출력: 완성된 README.md 마크다운 (복사 즉시 사용 가능)
---
# Project README Generator — GitHub README 자동 생성

## 목적
프로젝트의 `package.json`, 디렉터리 구조, 핵심 파일을 분석하여
GitHub에서 바로 사용할 수 있는 완성도 높은 README.md를 생성한다.

## 실행 절차

### 1단계: 프로젝트 정보 수집
```bash
cat package.json          # 이름, 버전, 의존성, 스크립트
ls -la                    # 루트 파일 구조
cat .env.example          # 환경 변수 목록
```
- 언어/프레임워크 자동 감지
- 주요 의존성 파악
- 빌드/테스트/실행 스크립트 확인

### 2단계: 핵심 기능 파악
- `src/` 디렉터리 구조 분석
- `README.md`가 이미 있으면 기존 내용 활용
- 엔트리포인트 파일 읽기 (index.ts, main.py, app.go 등)
- API 라우트 파일 확인

### 3단계: 뱃지 생성
프로젝트 특성에 맞는 shields.io 뱃지:
- 버전: `npm version`, `PyPI version`
- 빌드: `GitHub Actions`
- 커버리지: `codecov`
- 라이선스: `license`
- 언어: `TypeScript`, `Python` 등

### 4단계: README 섹션 작성
1. **헤더**: 프로젝트명 + 한 줄 설명 + 뱃지
2. **소개**: 무엇을 왜 만들었는지 (3-5줄)
3. **주요 기능**: 불릿 리스트
4. **빠른 시작**: 설치 → 설정 → 실행 (복사-붙여넣기 가능한 명령어)
5. **환경 변수**: 표로 정리 (이름, 설명, 기본값, 필수여부)
6. **프로젝트 구조**: 주요 디렉터리 설명
7. **API 문서**: 주요 엔드포인트 (있는 경우)
8. **개발 가이드**: 로컬 개발 환경 설정
9. **기여 가이드**: PR 프로세스
10. **라이선스**

### 5단계: 품질 체크
- 모든 명령어가 실제 작동하는지 검증
- 링크가 올바른지 확인
- 마크다운 렌더링 오류 없는지 확인

## 출력 형식

```
## README.md 생성 완료

아래 내용을 README.md로 저장하세요.

---

```markdown
<div align="center">

# ProjectName

> 한 줄로 설명하는 프로젝트 목적

[![npm version](https://badge.fury.io/js/project-name.svg)](https://badge.fury.io/js/project-name)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)

</div>

## 소개

ProjectName은 [문제]를 해결하기 위한 [기술 설명]입니다.
[핵심 가치 제안을 1-2문장으로 설명]

## 주요 기능

- **기능 1**: 간단한 설명
- **기능 2**: 간단한 설명
- **기능 3**: 간단한 설명

## 빠른 시작

### 요구사항
- Node.js 20+
- PostgreSQL 15+

### 설치

```bash
# 저장소 클론
git clone https://github.com/username/project-name.git
cd project-name

# 의존성 설치
npm install

# 환경 변수 설정
cp .env.example .env
```

### 환경 변수 설정

| 변수명 | 설명 | 기본값 | 필수 |
|--------|------|--------|------|
| `DATABASE_URL` | PostgreSQL 연결 문자열 | - | ✅ |
| `JWT_SECRET` | JWT 서명 키 | - | ✅ |
| `PORT` | 서버 포트 | `3000` | ❌ |

### 실행

```bash
# 개발 모드
npm run dev

# 프로덕션 빌드
npm run build
npm start
```

## 프로젝트 구조

```
src/
├── api/          # API 라우트 핸들러
├── services/     # 비즈니스 로직
├── models/       # 데이터베이스 모델
├── utils/        # 공통 유틸리티
└── index.ts      # 엔트리포인트
```

## 기여 가이드

1. Fork 후 feature 브랜치 생성 (`git checkout -b feat/your-feature`)
2. 변경 사항 커밋 (`git commit -m 'feat: Add your feature'`)
3. 브랜치 Push (`git push origin feat/your-feature`)
4. Pull Request 생성

## 라이선스

MIT License — 자세한 내용은 [LICENSE](LICENSE) 파일 참조
```
```

## 사용 예시

**입력:**
```
readme 만들어줘
```

**출력 예시 (축약):**
```
프로젝트 분석 결과:
- 언어: TypeScript (Node.js)
- 프레임워크: Express 4.x
- DB: PostgreSQL
- 테스트: Jest
- 스크립트: dev, build, test, lint

README.md 생성됨 (10개 섹션)
```

## 주의사항
- 민감한 정보(실제 API 키, 비밀번호)는 README에 절대 포함하지 않는다.
- 환경 변수는 `.env.example`의 키만 노출하고 값은 `your_value_here`로 마스킹한다.
- 실제 작동하지 않는 명령어는 포함하지 않는다.
- 이미 README.md가 있으면 덮어쓰지 않고 개선 제안으로 제시한다.