---
name: create-readme
version: 1.1.0
description: README 작성, README 생성, 프로젝트 설명 문서 작성 요청에 대해 사람이 읽기 쉽고 AI가 다음 작업에 바로 활용할 수 있는 표준형 README.md를 생성하는 공통 스킬
---

# README 생성

## 목적

프로젝트 루트의 `README.md`를 표준형으로 작성한다.
README는 사람에게 프로젝트의 목적과 사용법을 설명하면서, AI 에이전트가 다음 작업에서 빠르게 맥락을 파악하고 실행할 수 있는 작업 안내 문서가 되도록 구성한다.

## 언제 호출할지

- 사용자가 "README 작성해줘", "README 만들어줘", "프로젝트 설명 문서 만들어줘"라고 요청할 때
- 프로젝트 루트에 `README.md`가 없거나 내용이 비어 있을 때
- 기존 README가 제품 설명, 실행 방법, 구조, 검증 명령을 충분히 담지 못해 초기 정리가 필요할 때
- AI 에이전트가 프로젝트를 이어서 작업할 수 있도록 핵심 맥락을 한 문서에 모아야 할 때

## 입력

- `project-name`: README에 사용할 프로젝트 이름 (선택, 없으면 repo 이름 또는 package metadata에서 추론)
- `audience`: 주요 독자 또는 사용자 (선택)
- `purpose`: 프로젝트 목적 한 줄 요약 (선택)
- `scope`: README에 포함할 범위 또는 제외할 범위 (선택)
- `overwrite`: 기존 README 덮어쓰기 허용 여부 (선택, 명시 없으면 덮어쓰지 않음)

## README 표준 구성

README는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본 순서는 아래를 따른다.

```markdown
# <project-name>

<프로젝트 목적 1~3문장>

## 현재 상태

<개발 단계, 사용 가능 범위, 중요한 제약>

## 빠른 시작

<설치, 실행, 테스트의 최소 명령>

## 주요 명령

| 목적 | 명령 | 비고 |
|------|------|------|

## 구조

| 경로 | 역할 |
|------|------|

## 작업 맥락

<AI가 다음 작업에서 먼저 알아야 할 규칙, 문서, 로드맵, 주요 경계>

## 개발 흐름

<브랜치, 테스트, 검증, 리뷰 또는 배포 흐름>

## 환경 변수

| 이름 | 설명 | 필수 |
|------|------|------|

## 참고 문서

- <관련 문서 경로>
```

## AI-first 작성 기준

- README 상단에는 프로젝트가 무엇을 해결하는지와 현재 사용할 수 있는 범위를 먼저 쓴다.
- AI가 작업을 이어받을 때 필요한 경로, 명령, 검증 방법, 주요 문서를 명확한 제목과 표로 정리한다.
- `agent-ops/`가 있으면 규칙, 로드맵, 스킬 문서를 참고 문서나 작업 맥락에 연결한다.
- 로컬 `agent-roadmap/current.md`가 있으면 README에 현재 작업 위치를 복사하지 말고, 로드맵을 확인할 문서 경로만 적는다.
- README는 제품 소개 문서이면서 작업 진입점이다. 마케팅 문구보다 실행 가능한 정보와 프로젝트 경계를 우선한다.
- README의 자연어 설명은 한국어 중심으로 작성한다.
- 단, README, API, CLI, SDK, runtime, build, test, lint, deploy, workflow, migration, integration처럼 개발자가 흔히 쓰는 영어 표현과 제품명, 기술명, 패키지명, 명령, 경로, 코드 식별자는 자연스럽게 영어로 유지한다.
- 널리 쓰이는 기술 영어를 억지로 번역하지 말고, 사람과 AI가 함께 읽기 쉬운 표현을 우선한다.
- 불확실한 내용은 단정하지 않고 `TODO` 또는 "확인 필요"로 남긴다.

## 먼저 확인할 것

- [ ] 루트 `README.md` 존재 여부와 기존 내용 확인
- [ ] `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, `docker-compose.yml` 등 실행/검증 명령 근거 확인
- [ ] `agent-ops/rules/project/rules.md`가 있으면 프로젝트 개요, 기술 스택, 도메인 매핑 확인
- [ ] `agent-roadmap/ROADMAP.md` 또는 로컬 `agent-roadmap/current.md`가 있으면 제품 방향과 활성 Milestone 문서 경로만 확인
- [ ] 주요 소스 디렉터리와 테스트 디렉터리를 `rg --files`로 가볍게 확인

## 실행 절차

1. **기존 README 처리 결정**
   - `README.md`가 없으면 새로 생성한다.
   - `README.md`가 있고 사용자가 덮어쓰기를 명시하지 않았으면 기존 내용을 보존하고, 필요한 섹션만 보완한다.
   - 기존 README의 제품 설명, 설치/실행 명령, 경고, 라이선스, 배포 정보를 삭제하지 않는다.

2. **프로젝트 근거 수집**
   - metadata 파일에서 프로젝트 이름, 설명, scripts, dependencies, runtime을 확인한다.
   - Makefile, compose 파일, CI 설정, 테스트 설정에서 실행 명령과 검증 명령을 확인한다.
   - 소스 구조는 전체 정독하지 않고 README 작성에 필요한 상위 경로와 대표 진입점만 확인한다.
   - 명령을 추론해야 하면 "추정"으로 쓰지 말고 TODO로 남긴다.

3. **README 초안 작성**
   - 표준 구성 순서를 기준으로 프로젝트에 맞는 섹션을 선택한다.
   - 빠른 시작에는 최소 실행 경로를 짧게 쓴다.
   - 주요 명령 표에는 실제로 확인한 명령만 넣는다.
   - 구조 표에는 AI가 작업 범위를 잡는 데 도움이 되는 경로만 넣는다.
   - 작업 맥락에는 agent-ops 문서, 로드맵, 도메인 규칙, 중요한 작업 경계를 연결한다.

4. **기존 내용 병합**
   - 기존 README가 있으면 중복 섹션을 합치고 정보가 더 정확한 쪽을 남긴다.
   - 확인 근거가 없는 오래된 내용은 삭제하지 말고 "확인 필요"로 표시한다.
   - 문서의 제목, 명령, 경로 표기가 실제 파일과 맞는지 확인한다.

5. **결과 보고**
   - 생성 또는 수정한 README 경로
   - 확인한 실행/테스트 명령
   - TODO 또는 확인 필요로 남긴 항목
   - 덮어쓰지 않고 보존한 기존 주요 내용

## 실행 결과 검증

- [ ] 루트 `README.md`가 존재하는가
- [ ] 프로젝트 목적, 빠른 시작, 주요 명령, 구조, 작업 맥락 중 프로젝트에 필요한 섹션이 포함되어 있는가
- [ ] README에 적은 명령이 실제 설정 파일 또는 프로젝트 관례에서 확인된 명령인가
- [ ] README에 적은 경로가 실제로 존재하는가
- [ ] agent-ops 문서를 복사해 중복하지 않고 필요한 경로만 연결했는가
- [ ] 불확실한 내용이 단정 표현이 아니라 TODO 또는 확인 필요로 남아 있는가
- 검증 실패 시: README의 해당 항목만 보완하고, 근거 없는 내용을 새로 만들지 않는다.

## 출력 형식

```markdown
## README 작성 완료

- README: README.md
- 처리 방식: <생성 | 보완 | 재작성>
- 확인한 명령:
  - <command>

## 확인 필요

- <TODO 또는 확인 필요 항목> (해당 시)
```

## 금지 사항

- 사용자가 명시하지 않은 상태에서 기존 README를 통째로 덮어쓰지 않는다.
- 확인하지 않은 설치, 실행, 테스트, 배포 명령을 사실처럼 쓰지 않는다.
- README를 긴 내부 설계 문서로 만들지 않는다. 상세 규칙은 `agent-ops/` 문서로 연결한다.
- README에 개인 설정, 비밀값, 로컬 전용 경로를 넣지 않는다.
- 로드맵이나 도메인 규칙 내용을 README에 길게 복사하지 않는다.
