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

15 KiB
Raw Blame History

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

로드맵 생성

목적

agent-ops/roadmap/ 하위에 전체 목표 / Phase / Milestone 기반 한국어 로드맵 구조를 처음 생성한다. 전체 로드맵은 로드맵 설계와 갱신 때만 읽고, 일반 작업에서는 current.md의 활성 Milestone 창과 관련 Milestone 문서만 읽도록 공통 로드맵 룰을 따른다. Milestone은 구현 계획이 아니라 방향성, 범위, 선행 조건, 브레이킹 포인트를 잡는 게이트 문서로 시작한다. 구현 수준으로 구체화되지 않은 Milestone에는 구현 잠금을 걸어 사용자가 단순히 "진행"을 요청해도 코드 구현이나 agent-task 구현 계획으로 내려가지 않게 한다.

언제 호출할지

  • 프로젝트에 파일 기반 로드맵을 처음 만들 때
  • 사용자가 "로드맵 만들어줘", "마일스톤 설계해줘", "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 단위 목표, 구현 잠금, 범위, capability 체크리스트, 완료 기준, 범위 제외 항목

로드맵 문서 템플릿

  • 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 형식을 따른다.
  • 섹션 순서는 목표, 단계, 상태, 구현 잠금, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트를 유지한다.
  • 새 Milestone은 사용자가 구현 구체화와 잠금 해제를 명시하지 않는 한 구현 잠금 상태를 잠금으로 둔다.
  • 구현 잠금에는 이 문서가 방향성/범위 정의인지, 구현 가능한 수준인지, 잠금 해제 조건과 잠금 중 금지 사항을 적는다.
  • 필수 기능은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 작성한다. 완료 근거가 명확한 항목만 - [x]로 표시한다.
  • 필수 기능의 각 체크리스트 항목은 - [ ] [item-id] 설명 형식을 사용한다. item-id는 사람이 타이핑하고 LLM이 참조하기 쉬운 공백 없는 짧은 ASCII 토큰으로 작성한다.
  • item-id는 영문/숫자 segment 14개로 작성하고, segment 구분자는 -, _, +, =만 사용한다. 가능하면 13 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에 확정하지 않는다.
    • 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의 섹션 순서와 형식을 따른다.
    • 각 Milestone 문서에 구현 잠금 섹션을 포함한다.
    • 사용자가 해당 Milestone의 구현 구체화와 잠금 해제를 명시적으로 승인하지 않았으면 구현 잠금 상태는 잠금으로 작성한다.
    • 필수 기능과 그 하위 항목은 capability 또는 산출물 수준의 - [ ] [item-id] 설명 체크리스트로 작성한다.
    • 완료 근거가 확인된 항목만 - [x]로 표시하고, 근거가 없으면 체크하지 않는다.
    • 완료 기준도 검증 가능한 조건의 - [ ] 체크리스트로 작성한다.
    • 미래 Milestone은 확정된 방향과 capability만 필수 기능에 넣고, 불확실한 구현 세부는 작업 컨텍스트의 확인 필요 항목으로 둔다.

  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 문서가 생성되었는가
  • 각 Milestone 문서가 roadmap-milestone-template.md의 섹션 순서와 형식을 따르는가
  • 각 Milestone 문서에 구현 잠금 섹션이 있고, 구현 구체화가 없으면 상태가 잠금인가
  • 각 Milestone 문서의 필수 기능과 완료 기준이 체크리스트 형식인가
  • 각 Milestone 문서의 필수 기능 체크리스트 항목이 - [ ] [item-id] 설명 형식이고 item-id가 해당 Milestone 안에서 유일한가
  • ROADMAP.md에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가
  • 로딩 정책에 구현 잠금이 없거나 잠긴 Milestone의 구현/계획 시작 금지 규칙이 포함되었는가
  • agent-ops/rules/common/rules.md가 로드맵 디렉터리 존재 시 rules-roadmap.md를 읽도록 라우팅하는가
  • agent-ops/rules/common/rules-roadmap.md가 로드맵 컨텍스트 로딩과 구현 잠금 규칙을 포함하는가
  • 검증 실패 시: 누락된 파일이나 섹션만 보완하고 기존 내용을 덮어쓰지 않는다.

출력 형식

## 생성 완료

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