toki 5a67729cd6 update roadmap archive policy

2026-05-24 07:08:55 +09:00

36 KiB

Raw Blame History

name	version	description
update-roadmap	1.9.0	기존 전체 목표, Phase, 구현 구체화 잠금이 있는 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 신규 작업 배치, current.md 동기화, 완료/폐기 Milestone 아카이빙을 처리하는 공통 스킬

로드맵 업데이트

목적

기존 agent-ops/roadmap/ 구조를 현재 프로젝트 방향과 진행 상태에 맞게 한국어로 갱신한다. 로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, current.md의 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다. Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트를 잡는 게이트 문서로 유지한다. 구현 구체화가 필요한 Milestone은 구현 잠금 상태를 잠금으로 두고, 구현 잠금 섹션이 없는 Milestone도 구체화 상태 불명으로 보아 사용자가 단순히 "진행"을 요청해도 코드 구현이나 agent-task 구현 계획으로 내려가지 않게 한다. 완료 또는 폐기되어 현재 작업 후보에서 제외할 과거 Milestone은 agent-ops/roadmap/archive/YYYY/MM/로 이동하고, ROADMAP.md에는 아카이빙 당시 요약만 남긴다. 아카이브된 Milestone은 최신 스킬 규약이나 템플릿에 맞춰 재포맷하지 않고, 사용자가 명시적으로 과거 기록 확인이나 복원을 요청한 경우에만 읽는다.

언제 호출할지

사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 활성 마일스톤 바꿔줘"라고 요청할 때
사용자가 "로드맵 한국어 전환", "로드맵 번역", "영문 로드맵을 한국어로 바꿔줘"라고 요청할 때
Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때
완료 또는 폐기된 Milestone을 요약하고 archive로 이동해야 할 때
특정 기능이나 작업을 새 Milestone, 기존 Milestone의 태스크, 기존 태스크 하위 항목 중 적절한 위치에 추가해야 할 때
활성 Milestone 창에 포함할 Milestone 목록이 달라졌을 때
기본 목표, Phase, Milestone의 목표, 범위, 필수 기능, 완료 기준이 달라졌을 때
ROADMAP.md 또는 current.md 형식이 템플릿과 달라 표준화해야 할 때
Milestone 문서 형식이 제각각이라 템플릿 기준으로 표준화해야 할 때
실제 구현 상태와 로드맵 파일이 어긋난 것 같아 동기화가 필요할 때
사용자가 Milestone의 구현 구체화, 구현 잠금 해제, 또는 잠금 상태 점검을 요청할 때

입력

mode: status / milestone / phase / replan / sync / concretize / archive 중 하나 (선택, 요청에서 추론 가능)
target-milestone: 갱신할 Milestone 이름, slug, 파일 경로 (선택)
active-milestones: 활성 Milestone 창에 둘 Milestone 이름, slug, 파일 경로 목록 (선택)
new-feature: 추가할 기능, 작업, 또는 새 Milestone 설명 (선택)
placement: 새 작업 배치 위치. 예: <anchor-milestone> 앞, <anchor-milestone> 뒤, <milestone-name> 안, <phase-name> 안, <anchor-task> 앞, <anchor-task> 아래, auto (선택, 없으면 자동 판단)
placement-unit: 삽입 단위. milestone / task / subtask / auto 중 하나 (선택, 없으면 작업 성격으로 판단)
lock-state: Milestone 구현 잠금 상태. 잠금 / 해제 중 하나 (선택, 없으면 기존 상태 유지 또는 신규 Milestone은 잠금)
concretization-evidence: 구현 잠금 해제 근거가 되는 사용자 승인, 설계 문서, API/프로토콜 결정, 검증 기준 (선택)
change-summary: 반영할 방향 변경 또는 진행 상황 요약 (선택)
evidence: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택)
archive-date: Milestone 아카이브 날짜. 없으면 현재 날짜를 사용한다 (선택)
archive-summary: ROADMAP.md에 남길 과거 Milestone 요약. 없으면 대상 Milestone 문서와 evidence에서 1~2문장으로 추출한다 (선택)

모드

mode	사용 상황
`status`	태스크 체크박스, Milestone 상태, 완료 기준만 갱신
`milestone`	Milestone 목표, 범위, 태스크 체크리스트, 완료 기준 수정
`phase`	Phase 설명 또는 활성 Milestone 창 전환
`replan`	전체 Phase/Milestone 흐름 재구성
`sync`	실제 프로젝트 상태와 로드맵 불일치 점검 후 보정
`concretize`	잠긴 Milestone을 구현 가능한 수준으로 구체화하고 잠금 해제 여부를 결정
`archive`	완료 또는 폐기된 Milestone을 요약하고 `agent-ops/roadmap/archive/YYYY/MM/`로 이동

작성 언어

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

로드맵 문서 템플릿

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 요약, 로딩 정책이다.
ROADMAP.md에는 Phase/Milestone 흐름, 현재 참조할 Milestone 문서 링크, 아카이브된 Milestone 요약만 두고, 상세 작업 체크리스트는 Milestone 문서에 둔다.
Milestone 목록은 현재 흐름에서 직접 참조할 아카이브되지 않은 Milestone 목록이다. 아카이브된 항목은 이 목록에서 제거하고 아카이브 Milestone 요약으로 옮긴다.
아카이브 Milestone 요약에는 아카이브 당시 상태, 날짜, 목표 요약, 핵심 산출물 또는 근거, 후속 영향만 짧게 남긴다. 아카이브 문서 링크나 상세 경로는 넣지 않는다.
current.md 표준 섹션은 활성 Milestone, 선택 규칙이다.
current.md는 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태의 진실로 쓰지 않는다.
current.md의 활성 Milestone은 agent-ops/roadmap/milestones/ 하위 문서만 가리키며, agent-ops/roadmap/archive/**는 포함하지 않는다.
갱신 범위에 포함된 ROADMAP.md나 current.md가 템플릿과 다르면, 프로젝트 로드맵 정보는 보존하면서 표준 섹션 순서로 재배치한다.
current.md에 남아 있는 개인별 또는 세션별 작업 위치/완료 상태는 공유 로드맵 정보로 이관하지 말고 결과 보고의 확인 필요 항목에 남긴다.

Milestone 문서 템플릿

Milestone 문서는 agent-ops/skills/common/_templates/roadmap-milestone-template.md 형식을 기준으로 생성·갱신한다.
표준 섹션 순서는 목표, 단계, 상태, 구현 잠금, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트다.
갱신 범위에 포함된 Milestone 문서가 제각각 형식이면, 내용을 삭제하지 말고 표준 섹션 순서로 재배치한다.
기존 Milestone에 구현 잠금 섹션이 없으면 추가한다. 구현 구체화가 명시되지 않았거나 구현 가능한 수준인지 불확실하면 잠금으로 둔다.
구현 잠금 섹션이 없거나 상태가 잠금이면 이 Milestone은 구현 계획이 아니라 범위/방향성 게이트다. 코드 구현, agent-task 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
구현 잠금을 해제하려면 사용자가 Milestone 구체화 업데이트 또는 잠금 해제를 명시해야 하며, 책임 경계, API/프로토콜, 검증 기준, 선행 조건이 문서에 반영되어야 한다.
필수 기능은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 유지한다.
필수 기능의 각 체크리스트 항목은 - [ ] [item-id] 설명 형식을 사용한다. item-id는 사람이 타이핑하고 LLM이 참조하기 쉬운 공백 없는 짧은 ASCII 토큰으로 작성한다.
item-id는 영문/숫자 segment 1~~4개로 작성하고, segment 구분자는 -, _, +, =만 사용한다. 가능하면 1~~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
item-id의 유일성 범위는 해당 Milestone 문서 안으로 제한하며, 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. 기존 item-id는 사용자가 명시적으로 바꾸라고 하지 않는 한 보존하고, 새 항목에는 소문자 영문 중심의 의미 있는 id를 만든다.
완료 기준은 검증 가능한 조건의 체크리스트로 유지한다.
일반 불릿이나 설명 문장에 숨어 있는 capability/산출물은 성격을 판단해 필수 기능 체크리스트 또는 기존 항목의 하위 체크리스트로 옮긴다.
범위, 범위 제외, 작업 컨텍스트는 설명 목록으로 유지하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.

Milestone 아카이브 정책

활성 또는 예정 Milestone 문서는 agent-ops/roadmap/milestones/<milestone-slug>.md에 둔다.
완료 또는 폐기되어 현재 작업 후보에서 제외할 Milestone은 agent-ops/roadmap/archive/YYYY/MM/<milestone-slug>.md로 이동한다.
아카이브 날짜는 사용자 지정 archive-date, 완료 evidence 날짜, 현재 날짜 순으로 결정한다.
아카이브 전 대상 Milestone 문서를 1회 읽어 ROADMAP.md의 아카이브 Milestone 요약에 남길 요약을 만든다.
아카이브 요약은 Milestone 이름, 상태, 아카이브일, 요약, 핵심 산출물/근거, 후속 영향만 짧게 담는다.
첫 아카이브 항목을 추가할 때 아카이브 Milestone 요약의 - 없음 placeholder는 제거한다.
아카이브된 Milestone은 ROADMAP.md의 Milestone 목록에서 제거하고, current.md의 활성 Milestone에서도 제거한다.
agent-ops/roadmap/archive/**는 사용자가 과거 기록 확인, 복원, 또는 아카이브 문서 직접 수정을 명시적으로 요청한 경우에만 읽는다.
sync, 템플릿 표준화, 스킬 규약 업데이트는 아카이브 문서를 갱신 범위에 포함하지 않는다.
아카이브 문서는 아카이빙 당시의 기록 스냅샷으로 보고, 최신 roadmap-milestone-template.md 형식에 맞춰 재포맷하지 않는다.
아카이브 대상 경로가 이미 있으면 덮어쓰지 않고 확장자 앞에 -1, -2처럼 다음 숫자를 붙인다.

순서 정책

Phase와 Milestone 이름에 1, 2, M01, P1 같은 순번을 붙이지 않는다.
진행 순서는 ROADMAP.md에 적힌 위에서 아래 순서로만 해석한다.
새 Milestone 파일은 순번 없이 agent-ops/roadmap/milestones/<milestone-slug>.md로 만든다.
중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
기존 프로젝트에 이미 순번 파일명이 있으면 대규모 rename을 하지 말고, 갱신 범위에 포함된 새 항목부터 순번 없는 형식을 적용한다.
새 작업은 습관적으로 새 Milestone으로 만들거나 목록 맨 앞/뒤에 붙이지 않는다.
사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 기존 태스크 item-id, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
사용자가 위치를 지정하지 않으면 ROADMAP.md의 Phase 흐름, 기존 Milestone 목표, 기존 필수 기능/태스크, 선후 의존성, 활성 Milestone 창, 완료 기준을 보고 가장 자연스러운 위치를 자동으로 판단한다.
자동 배치한 경우 결과 보고에 선택한 삽입 단위, Phase/Milestone/태스크 위치, 판단 근거를 짧게 남긴다.

삽입 단위 정책

신규 추가 요청은 먼저 "어디에 둘지"와 "어떤 단위로 둘지"를 분리해서 판단한다. 여기서 태스크는 Milestone 문서 필수 기능 섹션의 체크리스트 항목 또는 기존 체크리스트 항목을 뜻한다.

삽입 단위	사용 기준
새 Milestone	독립적인 목표와 완료 기준이 필요하거나, 여러 기능을 묶는 산출물이고, 별도 상태 추적이 필요하며, Phase 흐름이나 선후 의존성에 의미 있는 경계를 만든다
기존 Milestone의 태스크	기존 Milestone의 목표와 범위 안에 들어가며, 하나의 완료 가능한 capability/산출물이지만 별도 Milestone 상태 추적까지는 필요하지 않다
기존 태스크의 하위 작업	잠금 해제된 Milestone에서 기존 태스크의 구현 세부, 보완, 테스트, 문서화, 예외 처리, 완료 기준 구체화처럼 부모 태스크를 완성하기 위한 세부 항목이다
작업 컨텍스트/TODO	요구가 아직 불확실하거나 조사/확인이 먼저 필요해 필수 기능으로 확정하기 어렵다

신규 Milestone은 기본적으로 구현 잠금: 잠금으로 생성한다. 사용자가 구현 구체화와 잠금 해제를 명시한 경우에만 해제를 검토한다.
잠긴 Milestone 안에 새 작업을 추가할 때는 구현 태스크가 아니라 capability, 결정 안건, 선행 조건, 완료 기준 후보로 작성한다.
구현 잠금이 없거나 잠긴 Milestone에 대해 사용자가 "진행", "구현", "계획 작성"을 요청하면 로드맵을 우회하지 않는다. 먼저 Milestone 문서 구체화 업데이트와 잠금 해제를 요청한다.
위치 지정이 있으면 anchor의 레벨을 먼저 확인한다. <anchor-task> 아래처럼 하위 위치가 명시되면 기존 태스크 하위 항목으로 넣고, <anchor-task> 앞/뒤면 같은 목록 레벨의 형제 항목으로 넣는다.
사용자가 item-id를 언급하면 해당 Milestone의 필수 기능 체크리스트에서 정확히 일치하는 item-id를 우선 매칭한다. 중복되거나 없으면 임의로 고르지 말고 확인한다.
여러 Milestone 후보에서 같은 item-id가 발견되면 item-id만으로 확정하지 말고 Milestone 이름이나 문서 경로를 확인한다.
위치는 지정됐지만 단위가 명시되지 않은 경우, anchor 레벨과 작업 성격을 함께 보고 새 Milestone, 태스크, 하위 작업 중 하나를 선택한다.
위치 지정이 <phase-name> 안 또는 <milestone-name> 안처럼 컨테이너만 지정된 경우, 잠금 해제된 Milestone에서 작업 내용이 기존 태스크의 세부 구현이면 해당 컨테이너 안에서 가장 관련 있는 태스크 아래에 넣을 수 있다. 이 경우 결과 보고에 "위치는 지정된 컨테이너를 따랐고, 단위는 하위 작업으로 판단"처럼 남긴다.
위치 지정이 <anchor-milestone> 앞/뒤 또는 <anchor-task> 앞/뒤처럼 순서 anchor인 경우, 같은 레벨의 앞/뒤 배치를 유지한다. 작업 성격상 다른 레벨이 더 적절해 보여도 조용히 재배치하지 말고 사용자에게 확인한다.
placement-unit을 사용자가 명시한 경우 그 단위를 우선한다. 다만 지정 단위가 anchor 레벨, Milestone 목표, 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다.
작업이 둘 이상의 Milestone에 걸치면 바로 하나의 기존 태스크에 넣지 않는다. 공통 기반 작업이면 새 Milestone을 고려하고, 단순 연계 작업이면 각 Milestone에 나눌지 사용자에게 확인한다.
기존 태스크와 중복되거나 기존 태스크의 완료 기준으로 자연스럽게 흡수되는 요청은 새 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 존재 여부 확인
current.md가 가리키는 활성 Milestone 문서 존재 여부 확인
current.md가 agent-ops/roadmap/archive/** 경로를 가리키지 않는지 확인
current.md가 정해진 한국어 형식을 유지하는지 확인
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 형식 확인
로드맵 파일이 없으면 create-roadmap 스킬 사용을 안내하고 중단
완료 상태로 바꾸는 경우 사용자의 명시 또는 확인 가능한 evidence가 있는지 확인
archive 모드이면 대상 Milestone이 agent-ops/roadmap/milestones/ 하위에 있고, ROADMAP.md에 남길 요약 근거가 있는지 확인
대상 Milestone의 구현 잠금 상태를 확인. 섹션이 없거나 잠금 상태에서 구현/계획을 요청받은 경우 Milestone 구체화 업데이트가 먼저 필요함을 보고하고 구현으로 진행하지 않는다.
잠금 해제를 요청받은 경우 책임 경계, API/프로토콜, 검증 기준, 선행 조건이 Milestone 문서에 반영될 수 있는지 확인

실행 절차

갱신 범위 결정
- 요청에서 mode, target Milestone, new feature, placement, placement-unit을 추론한다.
- 요청이 Milestone 구체화 또는 잠금 해제이면 concretize로 본다.
- 요청이 완료 또는 폐기된 Milestone을 과거 기록으로 넘기는 것이라면 archive로 본다.
- 로드맵 언어 전환, ROADMAP/current 형식 표준화, 또는 Milestone 형식 표준화 요청이면 sync로 보고 ROADMAP.md, current.md, agent-ops/roadmap/milestones/ 하위 Milestone 문서를 갱신 범위에 포함할 수 있다.
- sync 또는 템플릿 표준화 요청에서도 agent-ops/roadmap/archive/**는 갱신 범위에 포함하지 않는다.
- status 갱신이면 current.md와 대상 Milestone 문서를 우선 읽는다.
- archive이면 ROADMAP.md, current.md, 대상 Milestone 문서만 읽고 아카이브 디렉터리의 다른 문서는 읽지 않는다.
- 요청이 활성 Milestone에 없으면 ROADMAP.md의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- Phase 전환, Milestone 추가/삭제, 순서 변경, 전체 재계획이면 ROADMAP.md도 읽는다.
- 신규 작업 추가이고 placement가 명시되어 있으면 anchor의 종류(Phase, Milestone, 태스크), 앞/뒤/안/아래 방향, 대상 Phase 또는 Milestone을 함께 기록한다.
- 불필요하게 모든 Milestone 문서를 읽지 않는다.
현재 로드맵 상태 파악
- ROADMAP.md의 전체 목표, Phase 흐름, Milestone 목록, 아카이브 Milestone 요약을 확인한다.
- current.md의 활성 Milestone 창과 선택 규칙을 확인한다.
- current.md에 아카이브 경로가 있으면 해당 항목을 읽지 말고 제거 대상으로 기록한다.
- ROADMAP.md와 current.md가 표준 템플릿 섹션 순서와 형식을 따르는지 확인한다.
- 대상 또는 후보 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 범위 제외 항목을 확인한다.
- 대상 또는 후보 Milestone 문서의 구현 잠금 상태와 해제 조건을 확인한다.
- 구현 잠금이 없거나 잠긴 Milestone에 대한 구현, 구현 계획, 세부 API/파일 구조 확정 요청이면 수정으로 진행하지 않고 잠금 상태와 필요한 구체화 업데이트를 사용자에게 보고한다.
- 대상 Milestone 문서가 표준 템플릿 섹션 순서와 체크리스트 형식을 따르는지 확인한다.
- 대상 Milestone 문서의 필수 기능 item-id 목록을 확인하고, 중복 또는 누락이 갱신 범위에 있으면 보정 대상으로 기록한다.
- 신규 작업과 이름, 산출물, 코드 경계, 완료 기준이 겹치는 기존 태스크가 있는지 확인한다.
신규 작업 삽입 단위와 위치 판단
- 추가 요청이면 placement, placement-unit, 작업 성격을 함께 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업, 작업 컨텍스트/TODO 중 어느 단위가 맞는지 결정한다.
- 사용자가 위치를 지정한 경우 ROADMAP.md에서 anchor Phase/Milestone을 확인하고, 필요한 경우 대상 Milestone 문서의 태스크 anchor까지 확인해 충돌 여부를 확인한다.
- 지정된 anchor가 없거나 여러 항목과 매칭되어 모호하면 임의 배치하지 말고 사용자에게 짧게 확인한다.
- 사용자가 순서 anchor를 지정했으면 같은 레벨의 앞/뒤 배치를 유지하고, 컨테이너 anchor를 지정했으면 컨테이너 안에서 작업 성격에 맞는 하위 단위를 선택한다.
- 위치 지정이 없으면 ROADMAP.md의 위아래 흐름, 현재 활성 Milestone, 선행되어야 할 작업, 후속 작업이 기대하는 산출물, 관련 코드/문서 경계, 기존 태스크와의 포함 관계를 기준으로 자동 배치한다.
- 자동 배치는 "가장 빨리 할 수 있는 곳"이 아니라 "의존성과 완료 기준이 자연스럽게 이어지는 곳"을 우선한다.
- 대상 Milestone이 잠겨 있으면 새 항목은 구현 작업이 아니라 capability/산출물/결정 안건/선행 조건/완료 기준 후보로만 배치한다.
- 잠금 해제된 Milestone에서 기존 태스크를 완성하는 세부 구현이면 하위 작업으로 넣고, 기존 태스크와 같은 수준의 독립 완료 항목이면 같은 Milestone의 태스크로 넣는다.
- 기존 Milestone의 목표/범위를 넓히거나 완료 기준을 과도하게 키우는 작업이면 새 Milestone으로 분리한다.
- 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다.
변경 내용 검증
- 기능 완료 체크는 사용자 설명 또는 파일/테스트/커밋 등 확인 가능한 근거를 기준으로 한다.
- evidence 없이 완료 여부가 불확실하면 체크하지 않고 TODO 또는 확인 필요로 남긴다.
- 변경 요청이 전체 목표 또는 Phase 목표와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.
로드맵 파일 갱신
- ROADMAP.md는 전체 목표, Phase 흐름, Milestone 목록, 아카이브 Milestone 요약, 로딩 정책이 바뀔 때만 수정한다.
- current.md는 활성 Milestone 창이 바뀔 때 roadmap-current-template.md 형식으로 수정한다.
- 갱신 대상 ROADMAP.md가 표준 템플릿과 다르면 기존 내용을 보존하면서 전체 목표, Phase 흐름, Milestone 목록, 아카이브 Milestone 요약, 로딩 정책 순서로 정리한다.
- 갱신 대상 current.md가 표준 템플릿과 다르면 기존 활성 Milestone 목록을 보존하면서 활성 Milestone, 선택 규칙 순서로 정리한다.
- current.md에 agent-ops/roadmap/archive/** 경로가 있으면 활성 Milestone에서 제거하고, 필요하면 결과 보고의 확인 필요 항목에 남긴다.
- ROADMAP.md에 상세 작업 체크리스트가 있으면 삭제하지 말고 관련 Milestone 문서의 필수 기능 체크리스트로 옮긴다.
- current.md에 개인별 현재 작업 위치나 완료 상태가 있으면 current.md에서는 제거하고 공유 로드맵으로 이관하지 않는다. 프로젝트에 의미 있는 근거가 명확한 내용만 관련 Milestone 문서나 작업 컨텍스트로 옮기고, 이관하지 않은 내용은 결과 보고의 확인 필요 항목에 남긴다.
- Milestone 문서는 해당 Milestone의 목표, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다.
- 갱신 대상 Milestone 문서가 표준 템플릿과 다르면 기존 내용을 보존하면서 템플릿 섹션 순서로 정리하고, 누락 섹션은 TODO 또는 확인 필요 표시와 함께 추가한다.
- 갱신 대상 Milestone 문서에 구현 잠금 섹션이 없으면 추가한다. 구현 구체화가 불충분하면 상태를 잠금으로 둔다.
- concretize 모드에서는 구현 세부를 무작정 채우지 말고, 책임 경계, 결정 안건, API/프로토콜 후보, 검증 기준, 선행 조건, 범위 제외를 사용자와 합의된 수준으로만 반영한다.
- 구현 잠금을 해제로 바꿀 때는 사용자 명시 승인 또는 문서화된 구체화 근거를 결과 보고에 남긴다.
- 새 Milestone은 사용자 지정 또는 자동 판단 위치에 삽입하고, 기존 Milestone 이름이나 파일명을 순서 맞춤 목적으로 바꾸지 않는다.
- 새 Milestone은 사용자가 구현 구체화와 잠금 해제를 명시하지 않는 한 구현 잠금 상태를 잠금으로 작성한다.
- 기존 Milestone에 새 태스크를 넣는 경우 필수 기능 체크리스트에 사용자 지정 또는 자동 판단 위치로 삽입하고, 근거 없이 목록 맨 앞이나 맨 뒤에 붙이지 않는다.
- 잠금 해제된 Milestone에서 기존 태스크의 하위 작업으로 넣는 경우 부모 태스크 아래의 하위 체크리스트로 작성하고, 부모 태스크의 의미가 바뀌면 부모 문장도 필요한 만큼만 보완한다.
- 새로 추가하거나 형식 보정 범위에 포함된 필수 기능 항목은 - [ ] [item-id] 설명 또는 - [x] [item-id] 설명 형식으로 작성한다.
- 기존 필수 기능이 일반 불릿이면 상태 근거를 보존해 - [ ] [item-id] 설명 또는 - [x] [item-id] 설명 체크리스트로 변환한다.
- 기존 필수 기능 체크리스트에 item-id가 있으면 사용자가 명시적으로 바꾸라고 하지 않는 한 유지한다. item-id가 없는 항목을 갱신 범위에서 보정할 때는 해당 Milestone 안에서 중복되지 않는 id를 붙인다.
- 기존 완료 기준이 일반 불릿이면 검증 조건 단위의 체크리스트로 변환한다.
- 상태 값은 계획, 진행 중, 완료, 보류, 폐기 중 하나만 사용한다.
- 단순 상태 갱신이면 완료된 Milestone의 기록을 삭제하지 않고 상태만 변경한다.
- archive 모드에서는 대상 Milestone의 최종 상태를 완료 또는 폐기로 확정할 근거가 있는지 확인한 뒤 진행한다.
- archive 모드에서는 대상 Milestone 문서에서 ROADMAP.md의 아카이브 Milestone 요약에 남길 요약을 추출하거나, 사용자가 준 archive-summary를 반영한다.
- archive 모드에서는 ROADMAP.md의 Milestone 목록에서 대상 링크를 제거하고, 아카이브 Milestone 요약에 상태, 아카이브일, 요약, 핵심 산출물/근거, 후속 영향을 짧게 추가한다.
- archive 모드에서는 current.md의 활성 Milestone 목록에서 대상 Milestone을 제거한다.
- archive 모드에서는 대상 파일을 agent-ops/roadmap/archive/YYYY/MM/<milestone-slug>.md로 이동하고, 아카이브 대상 경로가 이미 있으면 확장자 앞에 다음 숫자를 붙인다.
- 아카이브로 이동한 Milestone 문서는 이동 전 내용 그대로 보존하고, 최신 템플릿에 맞춘 재포맷이나 체크리스트 보정을 하지 않는다.
로드맵 룰 라우팅 점검
- agent-ops/rules/common/rules.md가 agent-ops/roadmap/ 디렉터리 존재 시 agent-ops/rules/common/rules-roadmap.md를 읽도록 라우팅하는지 확인한다.
- agent-ops/rules/common/rules.md와 rules-roadmap.md에 agent-ops/roadmap/archive/**를 명시 요청 없이 읽지 않는 규칙이 있는지 확인한다.
- agent-ops/rules/common/rules-roadmap.md에 current.md 의미, Milestone 선택, ROADMAP.md 로딩 조건, 구현 잠금, 현재 작업 지점 확인 방법, Milestone archive 정책이 포함되어 있는지 확인한다.
- 로드맵 컨텍스트 로딩 규칙은 공통 로드맵 룰에 둔다. 프로젝트 전용 rules/project/rules.md에는 중복 마일스톤 컨텍스트 로딩 섹션을 추가하지 않는다.
- 기존 프로젝트 규칙에 마일스톤 컨텍스트 로딩 섹션이 남아 있으면 프로젝트 고유 내용이 아닌지 확인하고, 공통 룰과 중복되는 내용은 제거 대상으로 보고한다.
결과 보고
- 수정한 파일 목록
- 변경된 Phase / Milestone / 상태
- 신규 작업의 삽입 단위와 배치 위치, 자동 배치인 경우 판단 근거
- ROADMAP/current/Milestone 문서 템플릿 보정 여부
- 활성 Milestone 창 변경 사항
- archive 모드이면 아카이브 경로와 ROADMAP.md에 남긴 요약
- 체크하거나 추가/제거한 태스크 또는 하위 작업
- 확인 필요로 남긴 항목

실행 결과 검증

current.md의 활성 Milestone 경로가 실제 파일을 가리키는가
current.md의 활성 Milestone 경로가 agent-ops/roadmap/archive/**를 가리키지 않는가
ROADMAP.md가 roadmap-template.md의 섹션 순서와 형식을 따르는가
ROADMAP.md에 아카이브 Milestone 요약 섹션이 있는가
current.md가 roadmap-current-template.md의 섹션 순서와 형식을 따르는가
ROADMAP.md의 Milestone 목록과 대상 Milestone 문서의 상태가 서로 충돌하지 않는가
갱신 대상 Milestone 문서가 roadmap-milestone-template.md의 섹션 순서와 형식을 따르는가
갱신 대상 Milestone 문서에 구현 잠금 섹션이 있는가
구현 잠금이 없거나 잠긴 Milestone에 구현 태스크, agent-task 계획, 세부 API/파일 구조 확정을 추가하지 않았는가
잠금 해제한 경우 사용자 승인 또는 구체화 근거를 결과 보고에 남겼는가
갱신 대상 Milestone 문서의 필수 기능과 완료 기준이 체크리스트 형식인가
갱신 대상 Milestone 문서의 필수 기능 체크리스트 항목이 - [ ] [item-id] 설명 형식이고 item-id가 해당 Milestone 안에서 유일한가
신규 작업이 사용자 지정 위치를 따랐거나, 위치 미지정 시 자동 배치 근거가 남아 있는가
신규 작업의 삽입 단위가 작업 성격과 기존 태스크 포함 관계에 맞는가
자동 배치 위치가 Phase/Milestone 목표, 범위 제외 항목, 선후 의존성과 충돌하지 않는가
대상 Milestone 문서의 상태가 계획, 진행 중, 완료, 보류, 폐기 중 하나인가
완료 처리한 기능에 사용자 설명 또는 확인 가능한 evidence가 있는가
archive 모드이면 대상 Milestone이 Milestone 목록과 current.md에서 제거되고 아카이브 Milestone 요약에 당시 요약이 남았는가
archive 모드이면 이동한 문서를 최신 템플릿으로 재포맷하지 않았는가
rules/common/rules.md가 로드맵 디렉터리 존재 시 rules-roadmap.md를 읽도록 라우팅하는가
rules/common/rules-roadmap.md에 로드맵 컨텍스트 로딩, 구현 잠금, 아카이브 제외 규칙이 유지되는가
검증 실패 시: 불일치한 파일만 다시 읽고 해당 항목만 수정한다.

출력 형식

## 업데이트 완료

- 모드: <status | milestone | phase | replan | sync | concretize | archive>
- 수정 파일: <해당 항목만 나열>
  - agent-ops/roadmap/ROADMAP.md
  - agent-ops/roadmap/current.md
  - agent-ops/roadmap/milestones/<milestone-slug>.md
  - agent-ops/roadmap/archive/YYYY/MM/<milestone-slug>.md (archive 모드)

## 변경 사항

- Phase: <변경 없음 | 요약>
- 삽입 단위: <Milestone | 태스크 | 하위 작업 | 작업 컨텍스트/TODO | 변경 없음>
- 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음>
- 템플릿 보정: <ROADMAP 적용 | current.md 적용 | Milestone 적용 | 이미 일치 | 변경 없음>
- 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>
- 활성 Milestone: <변경 없음 | 추가/제거 요약>
- 아카이브: <변경 없음 | 이동 경로와 ROADMAP 요약>
- 상태: <변경 없음 | 이전 -> 이후>
- 태스크: <추가/수정/완료/제거 요약>

## TODO 항목

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

금지 사항

로드맵 파일이 없는데 새 구조를 임의로 만들지 않는다. 이 경우 create-roadmap을 사용한다.
evidence 없이 기능이나 Milestone을 완료 처리하지 않는다.
전체 ROADMAP.md를 모든 작업의 필수 로딩 파일로 만들지 않는다.
ROADMAP.md에 상세 작업 체크리스트를 남기지 않는다.
current.md에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다.
current.md에 agent-ops/roadmap/archive/** 경로를 남기지 않는다.
완료된 Milestone 기록을 삭제하지 않는다.
아카이브된 Milestone 문서를 명시 요청 없이 읽거나 최신 템플릿으로 재포맷하지 않는다.
아카이브된 Milestone을 ROADMAP.md의 활성 Milestone 목록에 링크로 계속 남기지 않는다.
Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
기존 순번 파일명을 대규모 rename하지 않는다.
신규 작업을 근거 없이 항상 새 Milestone으로 만들거나 맨 앞/맨 뒤에 추가하지 않는다.
작업 성격과 기존 태스크 포함 관계를 확인하지 않고 모든 신규 작업을 같은 단위로 처리하지 않는다.
구현 잠금이 없거나 잠긴 Milestone에 대해 사용자의 단순 "진행" 요청만으로 코드 구현, agent-task 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
사용자 명시 승인과 구체화 근거 없이 Milestone의 구현 잠금을 해제로 바꾸지 않는다.
구현 구체화가 필요한 초기 Milestone을 구현 계획처럼 자세한 package/file/function 체크리스트로 채우지 않는다.
사용자가 지정한 앞/뒤/아래 anchor 또는 대상 Phase/Milestone 컨테이너를 무시하지 않는다.
Milestone 목표와 범위 제외 항목을 무시하고 태스크 체크리스트만 갱신하지 않는다.
해야 할 작업을 필수 기능 체크리스트 밖의 설명 문장에 숨기지 않는다.
사용자가 명시하지 않은 기존 필수 기능 item-id를 바꾸지 않는다.
갱신 대상 Milestone의 형식이 다르다는 이유로 기존 내용이나 완료 체크 근거를 삭제하지 않는다.
타겟 프로젝트에서 agent-ops/rules/common/ 또는 agent-ops/skills/common/을 직접 수정하지 않는다.

36 KiB Raw Blame History