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

9.7 KiB
Raw Blame History

name version description
update-roadmap 1.2.0 기존 전체 목표, Phase, 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 current.md의 활성 Milestone 창을 동기화하는 공통 스킬

로드맵 업데이트

목적

기존 agent-ops/roadmap/ 구조를 현재 프로젝트 방향과 진행 상태에 맞게 한국어로 갱신한다. 로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, current.md의 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다.

언제 호출할지

  • 사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 활성 마일스톤 바꿔줘"라고 요청할 때
  • 사용자가 "로드맵 한국어 전환", "로드맵 번역", "영문 로드맵을 한국어로 바꿔줘"라고 요청할 때
  • Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때
  • 활성 Milestone 창에 포함할 Milestone 목록이 달라졌을 때
  • 기본 목표, Phase, Milestone의 목표, 범위, 필수 기능, 완료 기준이 달라졌을 때
  • 실제 구현 상태와 로드맵 파일이 어긋난 것 같아 동기화가 필요할 때

입력

  • mode: status / milestone / phase / replan / sync 중 하나 (선택, 요청에서 추론 가능)
  • target-milestone: 갱신할 Milestone 이름, slug, 파일 경로 (선택)
  • active-milestones: 활성 Milestone 창에 둘 Milestone 이름, slug, 파일 경로 목록 (선택)
  • change-summary: 반영할 방향 변경 또는 진행 상황 요약 (선택)
  • evidence: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택)

모드

mode 사용 상황
status 기능 체크박스, Milestone 상태, 완료 기준만 갱신
milestone Milestone 목표, 범위, 기능 목록, 완료 기준 수정
phase Phase 설명 또는 활성 Milestone 창 전환
replan 전체 Phase/Milestone 흐름 재구성
sync 실제 프로젝트 상태와 로드맵 불일치 점검 후 보정

작성 언어

  • agent-ops/roadmap/ 하위 로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 기본 작성 언어를 한국어로 한다.
  • 전체 구성, 섹션 제목, 설명 문장, 기능 설명, 완료 기준, TODO, 가정은 한국어 문장으로 작성한다.
  • Goal, Phase, Milestone, Scope, API, CLI처럼 개발자에게 자연스러운 일반 용어, 파일명, 경로, slug, 코드 식별자는 영어 또는 숫자를 유지할 수 있다.
  • 상태 값은 계획, 진행 중, 완료, 보류, 폐기 중 하나만 사용한다.
  • 기존 영문 상태 값은 Planned -> 계획, Active -> 진행 중, Done -> 완료, Paused -> 보류, Dropped -> 폐기로 맞춘다.
  • 기존 영문 섹션명이 갱신 범위에 포함되면 아래 한국어 표준 섹션명으로 정리한다.
    • Goal -> 목표
    • Phase -> 단계
    • Status -> 상태
    • Scope -> 범위
    • Required Features -> 필수 기능
    • Success Criteria -> 완료 기준
    • Non-Goals -> 범위 제외
    • Context for Work -> 작업 컨텍스트

순서 정책

  • Phase와 Milestone 이름에 1, 2, M01, P1 같은 순번을 붙이지 않는다.
  • 진행 순서는 ROADMAP.md에 적힌 위에서 아래 순서로만 해석한다.
  • 새 Milestone 파일은 순번 없이 agent-ops/roadmap/milestones/<milestone-slug>.md로 만든다.
  • 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
  • 기존 프로젝트에 이미 순번 파일명이 있으면 대규모 rename을 하지 말고, 갱신 범위에 포함된 새 항목부터 순번 없는 형식을 적용한다.

current.md 형식

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

# 현재 로드맵 컨텍스트

## 활성 Milestone

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

## 선택 규칙

- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택한다.
- 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.

current.md는 개인별 작업 위치나 완료 상태의 진실이 아니다. 현재 열려 있는 Milestone 후보 목록이며, 실제 현 작업 지점과 남은 작업은 analyze-roadmap-position 스킬이 코드와 git 상태를 함께 읽고 분석한다.

먼저 확인할 것

  • agent-ops/roadmap/ROADMAP.md 존재 여부 확인
  • agent-ops/roadmap/current.md 존재 여부 확인
  • current.md가 가리키는 활성 Milestone 문서 존재 여부 확인
  • current.md가 정해진 한국어 형식을 유지하는지 확인
  • 로드맵 파일이 없으면 create-roadmap 스킬 사용을 안내하고 중단
  • 완료 상태로 바꾸는 경우 사용자의 명시 또는 확인 가능한 evidence가 있는지 확인

실행 절차

  1. 갱신 범위 결정

    • 요청에서 mode와 target Milestone을 추론한다.
    • 로드맵 언어 전환 요청이면 sync로 보고 ROADMAP.md, current.md, 전체 Milestone 문서를 갱신 범위에 포함할 수 있다.
    • status 갱신이면 current.md와 대상 Milestone 문서를 우선 읽는다.
    • 요청이 활성 Milestone에 없으면 ROADMAP.md의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
    • Phase 전환, Milestone 추가/삭제, 순서 변경, 전체 재계획이면 ROADMAP.md도 읽는다.
    • 불필요하게 모든 Milestone 문서를 읽지 않는다.

  2. 현재 로드맵 상태 파악

    • ROADMAP.md의 전체 목표, Phase 개요, Milestone 목록을 확인한다.
    • current.md의 활성 Milestone 창과 선택 규칙을 확인한다.
    • 대상 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 범위 제외 항목을 확인한다.

  3. 변경 내용 검증

    • 기능 완료 체크는 사용자 설명 또는 파일/테스트/커밋 등 확인 가능한 근거를 기준으로 한다.
    • evidence 없이 완료 여부가 불확실하면 체크하지 않고 TODO 또는 확인 필요로 남긴다.
    • 변경 요청이 전체 목표 또는 Phase 목표와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.

  4. 로드맵 파일 갱신

    • ROADMAP.md는 전체 목표, Phase 개요, Milestone 목록, 로딩 정책이 바뀔 때만 수정한다.
    • current.md는 활성 Milestone 창이 바뀔 때 정해진 current.md 형식으로 수정한다.
    • Milestone 문서는 해당 Milestone의 목표, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
    • 상태 값은 계획, 진행 중, 완료, 보류, 폐기 중 하나만 사용한다.
    • 완료된 Milestone의 기록은 삭제하지 않고 상태만 변경한다.

  5. 마일스톤 컨텍스트 로딩 규칙 점검

    • agent-ops/rules/project/rules.md가 있으면 ## 마일스톤 컨텍스트 로딩 섹션이 있는지 확인한다.
    • 없으면 create-roadmap과 동일한 로딩 규칙을 추가한다.
    • 기존 섹션이 있으면 전체 ROADMAP.md를 일반 작업마다 읽도록 되어 있지 않은지 확인하고 보정한다.
    • 기존 섹션이 current.md를 현재 작업 위치로 단정하게 만들면 활성 Milestone 후보 목록으로 의미를 고친다.

  6. 결과 보고

    • 수정한 파일 목록
    • 변경된 Phase / Milestone / 상태
    • 활성 Milestone 창 변경 사항
    • 체크하거나 추가/제거한 필수 기능
    • 확인 필요로 남긴 항목

실행 결과 검증

  • current.md의 활성 Milestone 경로가 실제 파일을 가리키는가
  • current.md가 # 현재 로드맵 컨텍스트, 활성 Milestone, 선택 규칙 형식을 유지하는가
  • ROADMAP.md의 Milestone 목록과 대상 Milestone 문서의 상태가 서로 충돌하지 않는가
  • 대상 Milestone 문서의 상태가 계획, 진행 중, 완료, 보류, 폐기 중 하나인가
  • 완료 처리한 기능에 사용자 설명 또는 확인 가능한 evidence가 있는가
  • rules/project/rules.md가 있는 경우 마일스톤 컨텍스트 로딩 섹션이 유지되는가
  • 검증 실패 시: 불일치한 파일만 다시 읽고 해당 항목만 수정한다.

출력 형식

## 업데이트 완료

- 모드: <status | milestone | phase | replan | sync>
- 수정 파일:
  - agent-ops/roadmap/ROADMAP.md
  - agent-ops/roadmap/current.md
  - agent-ops/roadmap/milestones/<milestone-slug>.md

## 변경 사항

- Phase: <변경 없음 | 요약>
- 활성 Milestone: <변경 없음 | 추가/제거 요약>
- 상태: <변경 없음 | 이전 -> 이후>
- 필수 기능: <추가/수정/완료/제거 요약>

## TODO 항목

- <확인이 필요한 항목> (해당 시)

금지 사항

  • 로드맵 파일이 없는데 새 구조를 임의로 만들지 않는다. 이 경우 create-roadmap을 사용한다.
  • evidence 없이 기능이나 Milestone을 완료 처리하지 않는다.
  • 전체 ROADMAP.md를 모든 작업의 필수 로딩 파일로 만들지 않는다.
  • 완료된 Milestone 기록을 삭제하지 않는다.
  • Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
  • 기존 순번 파일명을 대규모 rename하지 않는다.
  • Milestone 목표와 범위 제외 항목을 무시하고 기능 목록만 갱신하지 않는다.
  • 타겟 프로젝트에서 agent-ops/rules/common/ 또는 agent-ops/skills/common/을 직접 수정하지 않는다.