nomadcode/agent-ops/skills/common/create-roadmap/SKILL.md

---
name: create-roadmap
version: 1.1.0
description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase, Milestone 기반 한국어 로드맵 파일과 기본/진행 중 Milestone 컨텍스트 로딩 규칙을 처음 생성하는 공통 스킬
---

# 로드맵 생성

## 목적

`agent-ops/roadmap/` 하위에 전체 목표 / Phase / Milestone 기반 한국어 로드맵 구조를 처음 생성한다.
전체 로드맵은 마일스톤 설계 시에만 읽고, 일반 작업에서는 `current.md`의 기본 Milestone 또는 요청에 맞는 진행 중인 Milestone 정의만 읽도록 컨텍스트 로딩 규칙을 만든다.

## 언제 호출할지

- 프로젝트에 파일 기반 로드맵을 처음 만들 때
- 사용자가 "로드맵 만들어줘", "마일스톤 설계해줘", "goal/phase 구조 잡아줘"라고 요청할 때
- AI-first 개인/소규모 개발 프로젝트의 현재 방향성과 작업 기준을 구조화해야 할 때
- 기존 README나 메모에 흩어진 계획을 `agent-ops/roadmap/` 구조로 분리할 때

## 입력

- `overall-goal`: 프로젝트 전체 목표 한 줄 또는 짧은 문단 (선택, 없으면 README와 현재 구조에서 추론)
- `phase-hints`: 예상 Phase 목록 또는 단계 힌트 (선택)
- `milestone-hints`: 예상 Milestone 목록 또는 기능 힌트 (선택)
- `default-milestone`: 애매한 요청이나 현재 집중 작업의 기본 Milestone 이름 또는 번호 (선택, 없으면 추론 후 사용자에게 확인)
- `active-milestones`: 동시에 진행 중인 Milestone 목록 (선택, 없으면 현재 구현 상태와 요청에서 추론)

## 생성 구조

```text
agent-ops/
  roadmap/
    ROADMAP.md
    current.md
    milestones/
      M01-<milestone-slug>.md
      M02-<milestone-slug>.md
```

| 파일 | 역할 |
|------|------|
| `agent-ops/roadmap/ROADMAP.md` | 전체 목표, Phase 흐름, Milestone 인덱스. 로드맵 생성/갱신/Phase 전환 때만 읽는다 |
| `agent-ops/roadmap/current.md` | 현재 Phase, 기본 Milestone, 동시에 진행 중인 Milestone 목록을 가리키는 얇은 포인터 |
| `agent-ops/roadmap/milestones/MNN-<milestone-slug>.md` | 일반 작업 시 읽는 Milestone 단위 목표, 범위, 기능 목록, 범위 제외 항목 |

## 작성 언어

- `agent-ops/roadmap/` 하위 로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 기본 작성 언어를 한국어로 한다.
- 전체 구성, 섹션 제목, 설명 문장, 기능 설명, 완료 기준, TODO, 가정은 한국어 문장으로 작성한다.
- Goal, Phase, Milestone, Scope, API, CLI처럼 개발자에게 자연스러운 일반 용어, 파일명, 경로, Milestone ID(`M01` 등), slug, 코드 식별자는 영어 또는 숫자를 유지할 수 있다.
- 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다.
- 프로젝트 규칙에 별도 문서 언어가 명시되어 있으면 그 규칙을 우선하되, 명시가 없으면 한국어를 기본값으로 삼는다.

### current.md 형식

`agent-ops/roadmap/current.md`는 아래 형식을 유지한다.

```markdown
# 현재 로드맵 컨텍스트

- 현재 Phase: <phase-name>
- 기본 Milestone: <MNN milestone-name>
- 기본 Milestone 파일: agent-ops/roadmap/milestones/MNN-<milestone-slug>.md

## 진행 중인 Milestone

- <MNN milestone-name>: agent-ops/roadmap/milestones/MNN-<milestone-slug>.md
```

기본 Milestone은 애매한 요청의 기본 작업 초점이다. 진행 중인 Milestone은 동시에 진행 중인 Milestone 후보 목록이며, 요청이 기본 Milestone과 맞지 않으면 이 목록에서 가장 관련 있는 Milestone을 읽는다.

## 먼저 확인할 것

- [ ] `agent-ops/roadmap/ROADMAP.md` 또는 `agent-ops/roadmap/current.md`가 이미 존재하는지 확인
- [ ] 이미 존재하면 덮어쓰지 말고 `update-roadmap` 스킬 사용을 안내
- [ ] `README.md`, `agent-ops/GUIDE.md`, `agent-ops/rules/project/rules.md` 등 프로젝트 방향을 설명하는 문서를 확인
- [ ] `rg --files`로 현재 프로젝트의 주요 구조를 가볍게 확인
- [ ] `agent-ops/rules/project/rules.md`가 있으면 마일스톤 컨텍스트 로딩 섹션 추가 위치 확인

## 실행 절차

1. **기존 로드맵 확인**
   - `agent-ops/roadmap/` 하위 기존 파일 존재 여부를 확인한다
   - 기존 로드맵이 있으면 새로 만들지 않고 `update-roadmap`을 사용하도록 안내한다
   - 일부 파일만 있으면 누락 파일을 보완할지, 기존 구조를 유지할지 사용자에게 짧게 확인한다

2. **프로젝트 방향 분석**
   - README와 프로젝트 규칙에서 대상 사용자, 해결하려는 문제, 현재 구현 상태를 파악한다
   - 전체 코드를 정독하지 않는다. 로드맵 설계에 필요한 문서와 상위 구조만 확인한다
   - 불확실한 제품 방향은 단정하지 않고 "가정" 또는 `<!-- TODO: 확인 필요 -->`로 남긴다

3. **목표 / Phase / Milestone 설계**
   - 전체 목표는 프로젝트가 궁극적으로 만들려는 결과를 1~3문장으로 작성한다
   - Phase는 큰 진화 단위로 나누고, 각 Phase에 목표를 둔다
   - Milestone은 Phase 안에서 완료 판단이 가능한 단위로 나눈다
   - Milestone ID는 `M01`, `M02`처럼 2자리 번호를 사용하고 파일명은 `M01-<milestone-slug>.md`로 만든다
   - 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다

4. **로드맵 파일 생성**
   - `agent-ops/roadmap/ROADMAP.md`에는 전체 목표, 현재 위치, Phase 개요, Milestone 인덱스, 로딩 정책을 작성한다
   - `agent-ops/roadmap/current.md`에는 정해진 `current.md 형식` 그대로 현재 Phase, 기본 Milestone, 진행 중인 Milestone 목록을 작성한다
   - 각 Milestone 문서에는 아래 섹션을 포함한다
     - `목표`
     - `단계`
     - `상태`
     - `범위`
     - `필수 기능`
     - `완료 기준`
     - `범위 제외`
     - `작업 컨텍스트`
   - 미래 Milestone은 확정된 내용만 작성하고, 불확실한 기능은 TODO로 둔다

5. **마일스톤 컨텍스트 로딩 규칙 추가**
   - `agent-ops/rules/project/rules.md`가 있으면 아래 섹션을 추가한다
     ```markdown
     ## 마일스톤 컨텍스트 로딩

     - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다.
     - 요청이 기본 Milestone 범위에 맞으면 기본 Milestone 문서를 같은 세션에서 1회 읽는다.
     - 요청이 기본 Milestone과 맞지 않으면 `current.md`의 진행 중인 Milestone 목록에서 가장 관련 있는 Milestone 문서를 같은 세션에서 1회 읽는다.
     - 진행 중인 Milestone에도 맞지 않으면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 인덱스를 확인하고 사용자에게 진행/전환 여부를 확인한다.
     - `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
     - 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.
     ```
   - 같은 섹션이 이미 있으면 중복 추가하지 않고 필요한 문장만 보완한다
   - `agent-ops/rules/project/rules.md`가 없으면 파일을 새로 만들지 말고, 추가하지 못한 항목으로 보고한다

6. **결과 보고**
   - 생성한 로드맵 파일 목록
   - 현재 Phase, 기본 Milestone, 진행 중인 Milestone
   - `rules/project/rules.md`에 추가한 로딩 규칙 여부
   - 확인이 필요한 TODO 또는 가정

## 실행 결과 검증

- [ ] `agent-ops/roadmap/ROADMAP.md`가 생성되었는가
- [ ] `agent-ops/roadmap/current.md`가 기본 Milestone 문서 경로와 진행 중인 Milestone 문서 경로를 정확히 가리키는가
- [ ] `agent-ops/roadmap/milestones/` 하위에 Milestone 문서가 생성되었는가
- [ ] 각 Milestone 문서가 한국어 필수 섹션을 포함하는가
- [ ] `ROADMAP.md`에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가
- [ ] `agent-ops/rules/project/rules.md`가 있는 경우 마일스톤 컨텍스트 로딩 섹션이 추가되었는가
- 검증 실패 시: 누락된 파일이나 섹션만 보완하고 기존 내용을 덮어쓰지 않는다

## 출력 형식

```markdown
## 생성 완료

- 로드맵: agent-ops/roadmap/ROADMAP.md
- 현재 컨텍스트: agent-ops/roadmap/current.md
- 기본 Milestone: agent-ops/roadmap/milestones/MNN-<milestone-slug>.md
- 진행 중인 Milestone: <N개>
- 프로젝트 규칙 업데이트: <추가함 | 이미 존재함 | rules/project/rules.md 없음>

## 현재 위치

- Phase: <phase-name>
- 기본 Milestone: <MNN milestone-name>

## TODO 항목

- <확인이 필요한 가정 또는 미정 항목> (해당 시)
```

## 금지 사항

- 기존 `agent-ops/roadmap/` 파일을 덮어쓰지 않는다
- 일반 작업마다 전체 `ROADMAP.md`를 읽도록 규칙을 만들지 않는다
- Milestone 문서를 단순 TODO 목록으로만 만들지 않는다. 반드시 목표, 범위, 완료 기준, 범위 제외 항목을 포함한다
- 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다
- `agent-ops/rules/common/`이나 `agent-ops/skills/common/`을 타겟 프로젝트에서 직접 수정하지 않는다