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

---
name: create-roadmap
version: 1.9.0
description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase, 결정 필요 체크리스트 기반 구현 잠금이 있는 순번 없는 Milestone 문서, 활성 Milestone 창을 처음 생성하는 공통 스킬
---

# 로드맵 생성

## 목적

`agent-ops/roadmap/` 하위에 전체 목표 / Phase / Milestone 기반 한국어 로드맵 구조를 처음 생성한다.
전체 로드맵은 로드맵 설계와 갱신 때만 읽고, 일반 작업에서는 `current.md`의 활성 Milestone 창과 관련 Milestone 문서만 읽도록 공통 로드맵 룰을 따른다.
Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서로 시작한다.
새 Milestone의 `구현 잠금`은 사용자만 결정할 수 있는 항목이 있을 때만 잠금으로 둔다. 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 정할 수 있는 항목은 `결정 필요`가 아니라 필요 시 표준선으로 기록한다.
Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제 상태로 둔다.

## 언제 호출할지

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

## 입력

- `overall-goal`: 프로젝트 전체 목표 한 줄 또는 짧은 문단 (선택, 없으면 README와 현재 구조에서 추론)
- `phase-hints`: 예상 Phase 목록 또는 단계 힌트 (선택)
- `milestone-hints`: 예상 Milestone 목록 또는 기능 힌트 (선택)
- `active-milestones`: 현재 열어둘 Milestone 목록 (선택, 없으면 현재 구현 상태와 요청에서 추론)

## 생성 구조

```text
agent-ops/
  roadmap/
    ROADMAP.md
    current.md
    milestones/
      <milestone-slug>.md
    archive/
      YYYY/MM/<milestone-slug>.md  # 아카이빙 시 생성
```

| 파일 | 역할 |
|------|------|
| `agent-ops/roadmap/ROADMAP.md` | 전체 목표, Phase 흐름, 문서 순서 기반 Milestone 목록. 로드맵 생성/갱신/Phase 전환 때만 읽는다 |
| `agent-ops/roadmap/current.md` | 지금 열려 있는 활성 Milestone 창과 선택 규칙을 담는 얇은 포인터 |
| `agent-ops/roadmap/milestones/<milestone-slug>.md` | 일반 작업 시 읽는 Milestone 단위 목표, 구현 잠금, 범위, capability 체크리스트, 완료 기준, 범위 제외 항목 |
| `agent-ops/roadmap/archive/YYYY/MM/<milestone-slug>.md` | 완료 또는 폐기되어 현재 후보에서 제외한 과거 Milestone. 사용자가 명시적으로 요청한 경우에만 읽는다 |

## 로드맵 문서 템플릿

- `agent-ops/roadmap/ROADMAP.md`는 `agent-ops/skills/common/_templates/roadmap-template.md` 형식을 따른다.
- `agent-ops/roadmap/current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 따른다.
- `ROADMAP.md`는 전체 목표, Phase 흐름, Milestone 목록, 아카이브 Milestone 요약, 로딩 정책만 담고, 상세 작업 체크리스트를 넣지 않는다.
- `current.md`는 활성 Milestone 후보 목록과 선택 규칙만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다.
- 아카이브된 과거 Milestone은 `ROADMAP.md`의 `아카이브 Milestone 요약`에 당시 요약만 남기며, 아카이브 문서 자체는 일반 컨텍스트로 읽지 않는다.

## Milestone 문서 템플릿

- 새 Milestone 문서는 `agent-ops/skills/common/_templates/roadmap-milestone-template.md` 형식을 따른다.
- 섹션 순서는 `목표`, `단계`, `상태`, `구현 잠금`, `범위`, `필수 기능`, `완료 기준`, `범위 제외`, `작업 컨텍스트`를 유지한다.
- 새 Milestone은 제품 방향, 범위, 우선순위, 책임 경계 등 사용자만 결정할 수 있는 항목이 남아 있으면 `구현 잠금` 상태를 `잠금`으로 둔다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다.
- `구현 잠금`에는 상태와 `결정 필요` 체크리스트만 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적고, 별도 해제 근거/금지 목록을 만들지 않는다.
- 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 처리 가능한 내용은 `결정 필요`에 넣지 않고, 필요할 때만 `작업 컨텍스트`의 `표준선`에 기록한다.
- `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 작성한다. 완료 근거가 명확한 항목만 `- [x]`로 표시한다.
- `필수 기능`의 각 체크리스트 항목은 `- [ ] [item-id] 설명` 형식을 사용한다. item-id는 사람이 타이핑하고 LLM이 참조하기 쉬운 공백 없는 짧은 ASCII 토큰으로 작성한다.
- item-id는 영문/숫자 segment 1~4개로 작성하고, segment 구분자는 `-`, `_`, `+`, `=`만 사용한다. 가능하면 1~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
- item-id의 유일성 범위는 해당 Milestone 문서 안으로 제한하며, 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. 소문자 영문 중심의 의미 있는 단어를 우선하고, 숫자나 기호는 구분이나 충돌 방지가 필요할 때만 사용한다.
- `필수 기능`의 하위 작업은 구현 세부가 아니라 capability를 판단하는 제품/운영/문서 수준의 확인 항목으로 제한한다.
- `완료 기준`은 검증 가능한 조건의 체크리스트로 작성한다.
- `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.

## 작성 언어

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

## 순서 정책

- Phase와 Milestone 이름에 `1`, `2`, `M01`, `P1` 같은 순번을 붙이지 않는다.
- 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로만 해석한다.
- Milestone 파일명은 순번 없이 `agent-ops/roadmap/milestones/<milestone-slug>.md`로 만든다.
- 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.

### current.md 형식

`agent-ops/roadmap/current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 유지한다.

`current.md`는 개인별 작업 위치가 아니라 현재 열어둘 Milestone 후보 목록이다. 실제 현 작업 지점과 남은 작업은 `analyze-roadmap-position` 스킬이 코드와 git 상태를 함께 읽고 분석한다.

## 먼저 확인할 것

- [ ] `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/skills/common/_templates/roadmap-template.md`를 읽어 최신 ROADMAP 형식 확인
- [ ] `agent-ops/skills/common/_templates/roadmap-current-template.md`를 읽어 최신 current.md 형식 확인
- [ ] `agent-ops/skills/common/_templates/roadmap-milestone-template.md`를 읽어 최신 Milestone 형식 확인
- [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `agent-ops/rules/common/rules-roadmap.md`를 읽도록 라우팅하는지 확인
- [ ] `agent-ops/rules/common/rules-roadmap.md`가 없으면 로드맵 룰이 설치되지 않은 상태로 보고하고, 프로젝트 전용 규칙에 마일스톤 컨텍스트 로딩 섹션을 추가하지 않는다
- [ ] 각 Milestone에 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있는지 확인. 없으면 새 Milestone도 해제로 둔다.

## 실행 절차

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

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

3. **목표 / Phase / Milestone 설계**
   - 전체 목표는 프로젝트가 궁극적으로 만들려는 결과를 1~3문장으로 작성한다.
   - Phase는 큰 진화 단위로 나누고, 각 Phase에 목표를 둔다.
   - Milestone은 Phase 안에서 완료 판단이 가능한 단위로 나눈다.
   - Milestone은 기본적으로 구현 계획이 아니라 방향성과 완료 판단 기준을 공유하는 문서로 작성한다.
   - package, 함수, DB schema, API 필드, 파일 구조 같은 구현 세부는 사용자가 별도 상세 설계를 요청하기 전까지 Milestone에 확정하지 않는다.
   - 사용자만 결정할 수 있는 항목은 구현 세부로 확정하지 말고 `구현 잠금`의 `결정 필요` 체크리스트로 남긴다.
   - 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 정할 수 있는 항목은 표준선으로 기록하고 사용자 결정 항목으로 올리지 않는다.
   - Phase와 Milestone은 순번 없이 이름으로만 작성하고, 순서는 문서의 위에서 아래 흐름으로 표현한다.
   - 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다.

4. **로드맵 파일 생성**
   - `agent-ops/roadmap/ROADMAP.md`는 `roadmap-template.md`의 섹션 순서와 형식을 따른다.
   - `agent-ops/roadmap/current.md`는 `roadmap-current-template.md`의 섹션 순서와 형식을 따른다.
   - `ROADMAP.md`에는 전체 목표, Phase 흐름, Milestone 목록, 아카이브 Milestone 요약, 로딩 정책을 작성하고, 상세 작업 체크리스트는 Milestone 문서에 둔다.
   - `current.md`에는 활성 Milestone 목록과 선택 규칙만 작성하고, 개인별 현재 작업 위치나 완료 상태는 적지 않는다.
   - 새 로드맵의 `아카이브 Milestone 요약`은 아카이브된 항목이 없으면 `- 없음`으로 둔다.
   - 각 Milestone 문서는 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따른다.
   - 각 Milestone 문서에 `구현 잠금` 섹션을 포함한다.
   - 사용자만 결정할 수 있는 항목이 있으면 `구현 잠금` 상태는 `잠금`으로 작성하고, 필요한 결정을 체크리스트로 적는다.
   - Milestone 전체에서 사용자만 결정할 항목이 더 이상 없으면 `구현 잠금` 상태를 `해제`로 작성하고, `결정 필요`는 `없음`으로 둔다.
   - `필수 기능`과 그 하위 항목은 capability 또는 산출물 수준의 `- [ ] [item-id] 설명` 체크리스트로 작성한다.
   - 완료 근거가 확인된 항목만 `- [x]`로 표시하고, 근거가 없으면 체크하지 않는다.
   - `완료 기준`도 검증 가능한 조건의 `- [ ]` 체크리스트로 작성한다.
   - 미래 Milestone은 확정된 방향과 capability만 `필수 기능`에 넣는다. 사용자만 결정할 수 있는 불확실성은 `구현 잠금`의 `결정 필요` 체크리스트에 두고, 표준선이나 단순 조사/참고 TODO는 `작업 컨텍스트`에 둔다.

5. **로드맵 룰 라우팅 확인**
   - `agent-ops/rules/common/rules.md`는 `agent-ops/roadmap/` 디렉터리가 있을 때만 `agent-ops/rules/common/rules-roadmap.md`를 읽도록 라우팅해야 한다.
   - `agent-ops/rules/common/rules-roadmap.md`에는 `current.md` 의미, Milestone 선택, `ROADMAP.md` 로딩 조건, 구현 잠금, 현재 작업 지점 확인 방법이 들어 있어야 한다.
   - 로드맵 컨텍스트 로딩 규칙은 공통 로드맵 룰에 둔다. `agent-ops/rules/project/rules.md`에는 프로젝트 고유 구조, 도메인 매핑, 기술 스택만 남기고 마일스톤 컨텍스트 로딩 섹션을 추가하지 않는다.
   - 공통 로드맵 룰이 설치되지 않은 프로젝트에서는 타겟 프로젝트의 공통 파일을 임의 수정하지 말고 agent-ops 업데이트 필요 항목으로 보고한다.

6. **결과 보고**
   - 생성한 로드맵 파일 목록
   - 활성 Milestone 목록
   - 공통 로드맵 룰 라우팅 확인 여부
   - 확인이 필요한 TODO 또는 가정

## 실행 결과 검증

- [ ] `agent-ops/roadmap/ROADMAP.md`가 생성되었는가
- [ ] `agent-ops/roadmap/current.md`가 활성 Milestone 문서 경로를 정확히 가리키는가
- [ ] `ROADMAP.md`가 `roadmap-template.md`의 섹션 순서와 형식을 따르는가
- [ ] `current.md`가 `roadmap-current-template.md`의 섹션 순서와 형식을 따르는가
- [ ] `agent-ops/roadmap/milestones/` 하위에 순번 없는 Milestone 문서가 생성되었는가
- [ ] `ROADMAP.md`에 `아카이브 Milestone 요약` 섹션이 있고, 아카이브된 항목이 없으면 `- 없음`으로 표시했는가
- [ ] 각 Milestone 문서가 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따르는가
- [ ] 각 Milestone 문서에 `구현 잠금` 섹션이 있고, 사용자만 결정할 수 있는 항목만 잠금 상태인가
- [ ] 잠금 상태인 Milestone의 `구현 잠금` 섹션에 `결정 필요` 체크리스트가 있는가
- [ ] 각 Milestone 문서의 `필수 기능`과 `완료 기준`이 체크리스트 형식인가
- [ ] 각 Milestone 문서의 `필수 기능` 체크리스트 항목이 `- [ ] [item-id] 설명` 형식이고 item-id가 해당 Milestone 안에서 유일한가
- [ ] `ROADMAP.md`에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가
- [ ] 로딩 정책에 `agent-ops/roadmap/archive/**`를 명시 요청 없이 읽지 않는다는 규칙이 포함되었는가
- [ ] 로딩 정책에 `구현 잠금`이 없거나 잠긴 Milestone의 현재 요청과 직접 관련된 `결정 필요` 체크리스트 확인 규칙이 포함되었는가
- [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `rules-roadmap.md`를 읽도록 라우팅하는가
- [ ] `agent-ops/rules/common/rules-roadmap.md`가 로드맵 컨텍스트 로딩과 구현 잠금 규칙을 포함하는가
- 검증 실패 시: 누락된 파일이나 섹션만 보완하고 기존 내용을 덮어쓰지 않는다.

## 출력 형식

```markdown
## 생성 완료

- 로드맵: agent-ops/roadmap/ROADMAP.md
- 현재 컨텍스트: agent-ops/roadmap/current.md
- Milestone 문서: <N개>
- 활성 Milestone: <N개>
- 구현 잠금: <잠금 Milestone N개 | 해제 Milestone N개>
- 공통 로드맵 룰: <확인함 | 설치 필요 | 해당 없음>

## 활성 Milestone

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

## TODO 항목

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

## 금지 사항

- 기존 `agent-ops/roadmap/` 파일을 덮어쓰지 않는다.
- 일반 작업마다 전체 `ROADMAP.md`를 읽도록 규칙을 만들지 않는다.
- `current.md`에 `agent-ops/roadmap/archive/**` 경로를 넣지 않는다.
- Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
- `ROADMAP.md`에 Milestone 상세 작업 체크리스트를 넣지 않는다.
- `current.md`에 개인별 현재 작업 위치나 완료 상태를 적지 않는다.
- Milestone 문서를 단순 TODO 목록으로만 만들지 않는다. 반드시 템플릿의 목표, 단계, 상태, 구현 잠금, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트를 포함한다.
- Milestone 문서에서 `구현 잠금` 섹션을 생략하지 않는다.
- 사용자만 결정할 수 있는 항목이 남아 있는데 새 Milestone을 `해제` 상태로 만들지 않는다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없는 Milestone을 관성적으로 `잠금` 상태로 만들지 않는다.
- Milestone을 구현 계획처럼 package/file/function 단위로 과도하게 세분화하지 않는다.
- 해야 할 capability 또는 산출물을 일반 불릿이나 설명 문장에 숨기지 않는다. `필수 기능` 또는 그 하위 항목의 item-id가 있는 체크리스트로 작성한다.
- 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다.
- `agent-ops/rules/common/`이나 `agent-ops/skills/common/`을 타겟 프로젝트에서 직접 수정하지 않는다.