로드맵 규칙

agent-ops/roadmap/ 디렉터리가 있는 프로젝트에서만 적용한다.

구조

최상위 로드맵은 agent-ops/roadmap/ROADMAP.md다.
활성 Phase는 agent-ops/roadmap/phase/<phase-slug>/PHASE.md에 둔다.
활성 Milestone은 해당 Phase 아래 agent-ops/roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md에 둔다.
완료된 Phase는 scaffold 그대로 agent-ops/roadmap/archive/phase/<phase-slug>/PHASE.md로 이동하고, 하위 Milestone도 archive/phase/<phase-slug>/milestones/ 아래에 둔다.
진행중 Phase 안에서 완료된 Milestone은 활성 PHASE.md에 짧은 archive 링크를 남기고, 상세 문서는 agent-ops/roadmap/archive/phase/<phase-slug>/milestones/로 이동한다.
archive PHASE.md는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 milestones/만 있을 수 있다.

로딩

세션 최초 1회 agent-ops/roadmap/current.md를 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다.
일반 작업에서는 ROADMAP.md를 읽지 않는다.
일반 작업에서는 agent-ops/roadmap/archive/**를 읽지 않는다.
기능 추가, 구조 변경, 구현 계획, 현재 작업 분석 전에는 요청과 변경 파일에 맞는 활성 Phase와 활성 Milestone 문서를 읽는다.
ROADMAP.md는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다.
과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 ROADMAP.md 또는 PHASE.md에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다.

Phase와 Milestone 선택

current.md는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
활성 Phase는 agent-ops/roadmap/phase/**/PHASE.md만 대상으로 한다.
활성 Milestone은 agent-ops/roadmap/phase/**/milestones/*.md만 대상으로 한다.
"로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 update-roadmap 스킬로 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다.
target 없는 신규 추가 요청은 먼저 요청 규모를 phase, milestone, epic, task, subtask, context 중 가장 작은 충분한 단위로 판정한다.
target 없는 신규 추가 요청은 활성 창만으로 결정하지 말고 필요한 경우 ROADMAP.md의 Phase 흐름과 관련 Phase/Milestone 문서를 비교한다.
배치는 Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
동일/유사 항목이 이미 있으면 새로 만들지 말고 기존 항목을 업데이트한다.
적절한 기존 후보가 없을 때만 판정한 규모에 맞는 새 항목을 만든다.
부모 후보는 있고 판정 규모의 항목만 없으면 부모 아래에 새 항목을 만들고, 부모도 없을 때만 필요한 부모 항목을 함께 만든다.
자동 배치할 때는 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 결과에 남긴다.
current.md가 아카이브 경로를 가리키면 해당 항목은 활성 후보로 읽지 말고 로드맵 갱신이 필요하다고 보고한다.
선택한 Phase/Milestone의 목표 또는 범위 제외와 요청이 충돌하면 구현 전에 사용자에게 확인한다.

상태 표기

Phase와 Milestone 상태 표기는 [계획], [진행중], [완료], [보류], [폐기] 중 하나만 사용한다.
갱신 범위에 포함된 기존 진행 상태 표기는 [진행중]으로 정리한다.
ROADMAP.md의 Phase 흐름과 PHASE.md의 Milestone 흐름은 완료, 진행중, 계획 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다.

구현 잠금

구현 잠금은 승인 의식이 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다.
제품 방향, 범위, 우선순위, 책임 경계처럼 사용자만 결정할 수 있는 항목이 남아 있으면 상태를 잠금으로 두고 결정 필요 체크리스트에 질문을 적는다.
기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 결정 필요가 아니라 작업 컨텍스트의 표준선이나 구현 가정으로 기록한다.
Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제로 둔다.
선택한 Milestone에 구현 잠금 섹션이 없거나 상태가 잠금이면 코드 구현, agent-task 구현 계획, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 결정 필요 항목만 사용자에게 확인한다.
현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 표준선으로 처리 가능한 작업을 막지 않는다.
잠금 상태를 바꾸더라도 필수 기능이나 완료 기준을 자동 완료 처리하지 않는다.

Epic과 Task id

Milestone 문서의 필수 기능은 Epic heading과 Task 체크리스트로 작성한다.
Epic heading은 ### Epic: [epic-id] <이름> 형식을 사용한다.
Task는 - [ ] [item-id] 설명 또는 - [x] [item-id] 설명 형식을 사용한다.
epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 영문/숫자 segment 1~~4개로 작성하고 segment 구분자는 -, _, +, =만 사용한다. 가능하면 1~~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
epic-id와 item-id는 해당 Milestone 안에서만 유일하면 된다.
다른 Milestone에서는 같은 id를 다시 사용할 수 있다. 여러 Milestone 후보에서 같은 id가 발견되면 Milestone 이름이나 문서 경로로 대상을 확정한다.
사용자가 epic-id 또는 item-id를 언급하면 해당 Milestone의 Epic/Task 항목을 우선 anchor로 삼고, 기존 id는 명시적 요청 없이 바꾸지 않는다.

작업 지점 분석

현재 작업 지점이나 남은 작업 분석 요청은 analyze-roadmap-position 스킬로 처리한다.
분석 답변은 agent-ops/skills/common/_templates/roadmap-position-report-template.md 섹션과 필드 순서를 따른다.
이때 current.md만으로 단정하지 말고 코드, git 상태, diff, 활성 Phase, 활성 Milestone 문서를 함께 본다.
Phase 또는 Milestone 후보가 여럿이면 단순 나열하지 말고 1순위와 2순위를 추천하고 근거를 함께 제시한다.

7.4 KiB Raw Blame History

로드맵 규칙

구조

로딩

Phase와 Milestone 선택

상태 표기

구현 잠금

Epic과 Task id

작업 지점 분석

아카이브

7.4 KiB

Raw Blame History