toki/agentic-framework
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agentic-framework/agent-ops/skills/common/create-roadmap/SKILL.md
toki 20d16fe58e feat: add roadmap templates and update SKILL.md files 
- Add roadmap template files (roadmap-template.md, roadmap-milestone-template.md, roadmap-current-template.md)
- Update create-roadmap and update-roadmap SKILL.md files
- Update README.md and GUIDE.md
2026-05-22 08:32:53 +09:00

12 KiB
Raw Blame History

name version description
create-roadmap 1.4.0 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 목록 또는 기능 힌트 (선택)
  • active-milestones: 현재 열어둘 Milestone 목록 (선택, 없으면 현재 구현 상태와 요청에서 추론)

생성 구조

agent-ops/
  roadmap/
    ROADMAP.md
    current.md
    milestones/
      <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 단위 목표, 범위, 태스크 체크리스트, 범위 제외 항목

로드맵 문서 템플릿

  • 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 목록, 로딩 정책만 담고, 상세 작업 체크리스트를 넣지 않는다.
  • current.md는 활성 Milestone 후보 목록과 선택 규칙만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다.

Milestone 문서 템플릿

  • 새 Milestone 문서는 agent-ops/skills/common/_templates/roadmap-milestone-template.md 형식을 따른다.
  • 섹션 순서는 목표, 단계, 상태, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트를 유지한다.
  • 필수 기능은 해야 할 작업 목록이므로 - [ ] 체크리스트로 작성한다. 완료 근거가 명확한 항목만 - [x]로 표시한다.
  • 필수 기능의 하위 작업도 체크리스트로 작성하고, 부모 태스크를 완성하는 구현 세부/보완/테스트/문서화 항목만 하위에 둔다.
  • 완료 기준은 검증 가능한 조건의 체크리스트로 작성한다.
  • 범위, 범위 제외, 작업 컨텍스트는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.

작성 언어

  • 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/project/rules.md가 있으면 마일스톤 컨텍스트 로딩 섹션 추가 위치 확인

실행 절차

  1. 기존 로드맵 확인

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

  2. 프로젝트 방향 분석

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

  3. 목표 / Phase / Milestone 설계

    • 전체 목표는 프로젝트가 궁극적으로 만들려는 결과를 1~3문장으로 작성한다.
    • Phase는 큰 진화 단위로 나누고, 각 Phase에 목표를 둔다.
    • Milestone은 Phase 안에서 완료 판단이 가능한 단위로 나눈다.
    • 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 문서에 둔다.
    • current.md에는 활성 Milestone 목록과 선택 규칙만 작성하고, 개인별 현재 작업 위치나 완료 상태는 적지 않는다.
    • 각 Milestone 문서는 roadmap-milestone-template.md의 섹션 순서와 형식을 따른다.
    • 필수 기능과 그 하위 작업은 - [ ] 체크리스트로 작성한다.
    • 완료 근거가 확인된 항목만 - [x]로 표시하고, 근거가 없으면 체크하지 않는다.
    • 완료 기준도 검증 가능한 조건의 - [ ] 체크리스트로 작성한다.
    • 미래 Milestone은 확정된 내용만 필수 기능에 넣고, 불확실한 기능은 작업 컨텍스트의 확인 필요 항목으로 둔다.

  5. 마일스톤 컨텍스트 로딩 규칙 추가

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

- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다.
- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다.
- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다.
- 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다.
- 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.
    • 같은 섹션이 이미 있으면 중복 추가하지 않고 필요한 문장만 보완한다.
    • agent-ops/rules/project/rules.md가 없으면 파일을 새로 만들지 말고, 추가하지 못한 항목으로 보고한다.

  6. 결과 보고

    • 생성한 로드맵 파일 목록
    • 활성 Milestone 목록
    • rules/project/rules.md에 추가한 로딩 규칙 여부
    • 확인이 필요한 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 문서가 생성되었는가
  • 각 Milestone 문서가 roadmap-milestone-template.md의 섹션 순서와 형식을 따르는가
  • 각 Milestone 문서의 필수 기능과 완료 기준이 체크리스트 형식인가
  • ROADMAP.md에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가
  • agent-ops/rules/project/rules.md가 있는 경우 마일스톤 컨텍스트 로딩 섹션이 추가되었는가
  • 검증 실패 시: 누락된 파일이나 섹션만 보완하고 기존 내용을 덮어쓰지 않는다.

출력 형식

## 생성 완료

- 로드맵: agent-ops/roadmap/ROADMAP.md
- 현재 컨텍스트: agent-ops/roadmap/current.md
- Milestone 문서: <N개>
- 활성 Milestone: <N개>
- 프로젝트 규칙 업데이트: <추가함 | 이미 존재함 | rules/project/rules.md 없음>

## 활성 Milestone

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

## TODO 항목

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

금지 사항

  • 기존 agent-ops/roadmap/ 파일을 덮어쓰지 않는다.
  • 일반 작업마다 전체 ROADMAP.md를 읽도록 규칙을 만들지 않는다.
  • Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
  • ROADMAP.md에 Milestone 상세 작업 체크리스트를 넣지 않는다.
  • current.md에 개인별 현재 작업 위치나 완료 상태를 적지 않는다.
  • Milestone 문서를 단순 TODO 목록으로만 만들지 않는다. 반드시 템플릿의 목표, 단계, 상태, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트를 포함한다.
  • 해야 할 작업을 일반 불릿이나 설명 문장에 숨기지 않는다. 필수 기능 또는 그 하위 작업의 체크리스트로 작성한다.
  • 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다.
  • agent-ops/rules/common/이나 agent-ops/skills/common/을 타겟 프로젝트에서 직접 수정하지 않는다.