toki/agent-shell
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agent-shell/agent-ops/skills/common/create-roadmap/SKILL.md

16 KiB
Raw Blame History

name version description
create-roadmap 1.16.1 AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, 로컬 current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하는 공통 스킬

로드맵 생성

목적

agent-roadmap/ 하위에 Roadmap -> Phase -> Milestone 기반 한국어 로드맵 구조를 처음 생성한다. 전체 로드맵은 전체 방향과 Phase index만 담당하고, 일반 작업에서는 브랜치별 로컬 current.md의 활성 Phase/Milestone 링크와 관련 문서만 읽도록 만든다. Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서다. Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 기능 안에서 관리한다. 별도 완료 기준 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 검증: 문구로 통합한다.

언제 호출할지

  • 프로젝트에 파일 기반 로드맵을 처음 만들 때
  • 사용자가 "로드맵 만들어줘", "마일스톤 설계해줘", "goal/phase 구조 잡아줘"라고 요청할 때
  • 기존 README나 메모에 흩어진 계획을 agent-roadmap/ 구조로 분리할 때

입력

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

생성 구조

agent-roadmap/
    ROADMAP.md
    current.md  # local, git ignored
    phase/
      <phase-slug>/
        PHASE.md
        milestones/
          <milestone-slug>.md
    sdd/
      <phase-slug>/
        <milestone-slug>/
          SDD.md
          USER_REVIEW.md
    archive/
      phase/
        <phase-slug>/
          PHASE.md
          milestones/
            <milestone-slug>.md
      sdd/
        <phase-slug>/
          <milestone-slug>/
            SDD.md
파일 역할
agent-roadmap/ROADMAP.md 전체 목표와 Phase 흐름만 담는 최상위 지도. 로드맵 생성/갱신/Phase 전환 때만 읽는다
agent-roadmap/current.md 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 브랜치별 로컬 포인터
agent-roadmap/phase/<phase-slug>/PHASE.md Phase 목표, 상태, Milestone 흐름, Phase 경계를 담는 문서
agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md 일반 작업 시 읽는 Milestone 단위 목표, 스케치 승격 조건, 구현 잠금, 범위, 기능 Epic/Task 체크리스트, 범위 제외 항목
agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md 큰 Milestone의 source of truth, 상태 전이, interface, acceptance scenario, evidence map을 담는 설계 게이트
agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md SDD에서 에이전트가 확정할 수 없는 결정 항목이 있을 때 열리는 파일 기반 리뷰 gate
agent-roadmap/archive/phase/<phase-slug>/... 완료 또는 폐기되어 현재 후보에서 제외한 과거 Phase/Milestone. 일반 작업에서는 읽지 않는다
agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/... 완료 또는 폐기된 Milestone의 SDD 스냅샷과 해결된 사용자 리뷰 로그

템플릿

  • ROADMAP.md는 agent-ops/skills/common/_templates/roadmap-template.md 형식을 따른다.
  • current.md는 agent-ops/skills/common/_templates/roadmap-current-template.md 형식을 따른다.
  • PHASE.md는 agent-ops/skills/common/_templates/roadmap-phase-template.md 형식을 따른다.
  • Milestone 문서는 agent-ops/skills/common/_templates/roadmap-milestone-template.md 형식을 따른다.
  • SDD 본문은 agent-ops/skills/common/_templates/roadmap-sdd-template.md 형식을 따른다.
  • SDD 사용자 리뷰는 agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md 형식을 따른다.
  • ROADMAP.md에는 Milestone 상세 체크리스트를 넣지 않는다.
  • current.md는 git 추적 대상이 아니며, 예시 파일을 agent-roadmap/에 따로 만들지 않는다.
  • current.md는 활성 Phase/Milestone 후보만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다.
  • archive 경로는 current.md의 활성 항목에 넣지 않는다.

작성 규칙

  • 기본 작성 언어는 한국어다.
  • 상태 표기는 [스케치], [계획], [진행중], [검토중], [완료], [보류], [폐기] 중 하나만 사용한다.
  • [스케치]는 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태다. 구현 가능한 계획이 아니므로 구현 계획 생성 대상이 아니다.
  • [계획]은 목표, 범위, 기능 Task, 구현 잠금, 결정 필요 항목이 문서화되어 잠금 해제 후 구현 계획을 만들 수 있는 상태다.
  • Phase와 Milestone 이름, 파일명에는 1, 2, M01, P1 같은 순번을 붙이지 않는다.
  • 진행 순서는 ROADMAP.md와 각 PHASE.md의 위에서 아래 순서로 표현한다.
  • Phase 파일명은 agent-roadmap/phase/<phase-slug>/PHASE.md로 만든다.
  • Milestone 파일명은 agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md로 만든다.
  • <phase-slug>와 <milestone-slug>는 소문자 영문, 숫자, 하이픈만 사용하고, 공백/언더스코어/순번 prefix를 넣지 않는다.
  • 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.

Milestone 작성 규칙

  • Milestone 기본 섹션은 위치, 목표, 상태, 구현 잠금, 범위, 기능, 완료 리뷰, 범위 제외, 작업 컨텍스트다.
  • 승격 조건은 [스케치] Milestone에서 필수다. [계획] 이상 상태에서는 섹션을 생략하거나 - 없음으로 둘 수 있다.
  • [스케치] Milestone은 승격 조건을 체크리스트로 작성하고, [계획]으로 전환하기 위해 필요한 정의, 결정, 경계, 후속 구현 Milestone 후보를 적는다.
  • 새 Milestone은 에이전트가 확정할 수 없는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 구현 잠금을 잠금으로 둔다.
  • 새 [스케치] Milestone은 구현 잠금을 잠금으로 둔다.
  • Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제로 둔다.
  • 구현 잠금에는 상태, SDD 필요 여부, 잠금 해제 조건, 결정 필요 체크리스트를 적는다. 결정할 항목이 없으면 결정 필요: 없음으로 적는다.
  • SDD가 필요한 기준: cross-repo 계약, 외부 provider 쓰기, 상태 머신/lifecycle, idempotency/retry/identity map, API/proto/config/env/schema 변경, field smoke, 사용자 승인 gate 영향.
  • SDD가 불필요한 기준: 단일 repo 내부의 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task 검증:만으로 닫히는 작업.
  • SDD가 필요한 Milestone은 SDD 문서 경로를 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md로 적고, SDD 잠금이 해제될 때까지 구현 잠금을 잠금으로 둔다.
  • 로드맵 생성 흐름에서 SDD가 필요한 신규 Milestone은 SDD 경로만 남기지 않고 해당 경로에 SDD 초안을 만든다.
  • 새 Milestone이 다른 프로젝트 Milestone 완료 전까지 잠겨야 하면 구현 잠금을 잠금으로 두고 프로젝트 상위 .agent-roadmap-sync/locks.yaml에 entry를 만든다. 의존 대상 확정과 entry 형식은 update-roadmap의 프로젝트 간 잠금 규칙을 따른다.
  • 기능은 Epic heading과 Task 체크리스트로 작성한다.
  • Epic heading은 ### Epic: [epic-id] <이름> 형식으로 작성한다.
  • Task는 - [ ] [item-id] 설명 형식으로 작성한다.
  • epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 해당 Milestone 안에서만 유일하면 된다.
  • 검증이 필요한 Task에만 같은 항목 안에 검증: <명령/확인 방법/기대 결과>를 붙인다. 검증이 필요 없는 기능에는 억지 검증을 붙이지 않는다.
  • 완료 리뷰는 새 Milestone에서는 상태: 없음, 요청일: 없음으로 두고, 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 구현 잠금이 해제된 뒤 에이전트/런타임 완료 근거를 기록할 때 갱신한다. 에이전트가 확정할 수 없는 결정 항목은 완료 리뷰가 아니라 구현 잠금 > 결정 필요 또는 SDD USER_REVIEW.md로 분리한다.
  • 범위, 범위 제외, 작업 컨텍스트는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.

먼저 확인할 것

  • agent-roadmap/ROADMAP.md 또는 로컬 agent-roadmap/current.md가 이미 존재하는지 확인
  • 이미 존재하면 덮어쓰지 말고 update-roadmap 스킬 사용을 안내
  • README.md, agent-ops/GUIDE.md, agent-ops/rules/project/rules.md 등 프로젝트 방향을 설명하는 문서를 확인
  • rg --files로 현재 프로젝트의 주요 구조를 가볍게 확인
  • roadmap-template.md, roadmap-current-template.md, roadmap-phase-template.md, roadmap-milestone-template.md를 읽어 최신 형식 확인
  • SDD가 필요한 Milestone 후보가 있으면 agent-ops/skills/common/roadmap-sdd/SKILL.md, roadmap-sdd-template.md, roadmap-sdd-user-review-template.md를 읽어 최신 절차와 형식 확인
  • agent-ops/rules/common/rules.md가 로드맵 디렉터리 존재 시 agent-ops/rules/common/rules-roadmap.md를 읽도록 라우팅하는지 확인

실행 절차

  1. 기존 로드맵 확인

    • agent-roadmap/ 하위 기존 파일 존재 여부를 확인한다.
    • 기존 로드맵이 있으면 새로 만들지 않고 update-roadmap을 사용하도록 안내한다.

  2. 프로젝트 방향 분석

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

  3. 목표 / Phase / Milestone 설계

    • 전체 목표는 프로젝트가 궁극적으로 만들려는 결과를 1~3문장으로 작성한다.
    • Phase는 큰 진화 단위로 나누고, 각 Phase에 목표와 상태를 둔다.
    • Milestone은 Phase 안에서 완료 판단이 가능한 단위로 나눈다.
    • Milestone 내부에서 여러 기능 묶음이 필요하면 Epic으로 선언하고, Epic 아래 flat Task 체크리스트를 둔다.

  4. 파일 생성

    • ROADMAP.md, 로컬 current.md, 각 Phase의 PHASE.md, 각 Milestone 문서를 템플릿 순서대로 생성한다.
    • 활성 Phase와 활성 Milestone은 current.md에 모두 기록한다.
    • .gitignore의 Agent-Ops 관리 block에 agent-roadmap/current.md가 있는지 확인하고 없으면 추가한다.
    • ROADMAP.md의 Phase 흐름에는 완료/검토중/진행중/계획/스케치 Phase 모두를 위에서 아래 순서로 두고, 계획 Phase는 진행중 Phase보다 아래에, 스케치 Phase는 계획 Phase보다 아래에 둔다.
    • 완료된 Phase가 초기 구조에 포함되어야 하는 경우 archive/phase/<phase-slug>/PHASE.md로 만들고 ROADMAP.md에서 archive 경로를 가리킨다.
    • 완료된 Milestone이 진행중 Phase에 포함되어야 하는 경우 archive/phase/<phase-slug>/milestones/<milestone-slug>.md로 만들고 해당 활성 PHASE.md에서 archive 경로를 가리킨다.
    • archive PHASE.md는 Phase 자체가 완료/폐기된 경우에만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 milestones/만 둘 수 있다.
    • SDD가 필요한 Milestone은 구현 잠금에 SDD 경로와 잠금 해제 조건을 적고, 같은 흐름에서 roadmap-sdd의 create 절차를 적용해 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md 초안을 만든다.
    • roadmap-sdd create 결과 SDD 결정 항목이 있으면 roadmap-sdd의 review-ready 절차에 따라 같은 디렉터리에 USER_REVIEW.md를 만들고, SDD와 Milestone 구현 잠금을 잠금으로 둔다.
    • 외부 의존 잠금이 있으면 프로젝트 상위 .agent-roadmap-sync/locks.yaml을 생성하거나 기존 entry를 upsert한다. 의존 대상이 명시 경로, slug, 제목, 문서 힌트, 로컬 current 단일 후보 중 하나로 확정되지 않으면 lock entry를 만들지 않고 TODO로 남긴다.

  5. 검증

    • 생성한 링크가 실제 파일을 가리키는지 확인한다.
    • 로컬 current.md 활성 항목에 agent-roadmap/archive/** 경로가 없는지 확인한다.
    • Epic heading과 Task 체크리스트 id가 형식을 따르는지 확인한다.
    • 상태 표기가 [진행중]처럼 공백 없는 표준값인지 확인한다.
    • [스케치] Milestone에 승격 조건 섹션이 있고 구현 잠금이 잠금인지 확인한다.
    • 각 Milestone의 구현 잠금에 SDD: 필요|불필요와 판정 사유가 있는지 확인한다.
    • SDD: 필요 Milestone은 SDD 경로와 잠금 해제 조건이 있고, 해당 SDD.md 파일이 실제 존재하는지 확인한다.
    • 생성된 각 SDD.md는 roadmap-sdd의 check-gate 절차로 표준 top-level 섹션, 필수 표 컬럼, SDD 상태, SDD 잠금, USER_REVIEW.md 존재 여부, Acceptance Scenario와 Milestone 기능 Task 연결, Evidence Map 연결성을 최종 확인한다.
    • check-gate 결과는 SDD gate 항목에 pass, review-required, blocked, invalid 중 하나로 분리해 남긴다. review-ready로 만든 USER_REVIEW.md 때문에 막힌 경우는 review-required로 보고하고 형식 보완 실패로 보지 않는다.
    • [검토중] Milestone이 있다면 구현 잠금이 해제되어 있고 미완료 결정 필요 항목이 없는지 확인한다.
    • Milestone 문서에 완료 리뷰 섹션이 있는지 확인한다.

출력 형식

## 생성 결과

- 로드맵: agent-roadmap/ROADMAP.md
- 로컬 현재 컨텍스트: agent-roadmap/current.md
- Phase 문서: <N개>
- Milestone 문서: <N개>
- 활성 Phase: <N개>
- 활성 Milestone: <N개>
- 구현 잠금: <잠금 Milestone N개 | 해제 Milestone N개>
- SDD gate: <필요 N개 | 불필요 N개 | 작성 N개 | pass N개 | review-required N개 | blocked/invalid N개>
- 최종 확인: <통과 | 사용자 리뷰 필요 | 보완 필요: SDD gate/링크/상태/형식>
- Workspace 잠금: <생성/갱신 N개 | 없음>
- 공통 로드맵 룰: <확인함 | 설치 필요 | 해당 없음>

## 활성 항목

- Phase: <phase-name>: agent-roadmap/phase/<phase-slug>/PHASE.md
- Milestone: <milestone-name>: agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md

## TODO 항목

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

금지 사항

  • 기존 agent-roadmap/ 파일을 덮어쓰지 않는다.
  • 일반 작업마다 전체 ROADMAP.md를 읽도록 규칙을 만들지 않는다.
  • 로컬 current.md에 agent-roadmap/archive/** 경로를 넣지 않는다.
  • agent-roadmap/current.md를 git 추적 대상으로 만들지 않는다.
  • Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
  • ROADMAP.md에 Milestone 상세 작업 체크리스트를 넣지 않는다.
  • Epic과 Task를 별도 파일로 분리하지 않는다.
  • Milestone 문서에서 구현 잠금 섹션을 생략하지 않는다.
  • 에이전트가 확정할 수 없는 결정 항목이 남아 있는데 새 Milestone을 해제 상태로 만들지 않는다.
  • 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다.