diff --git a/.aiexclude b/.aiexclude index d37067e..1ce2388 100644 --- a/.aiexclude +++ b/.aiexclude @@ -1,2 +1,7 @@ agent-task/archive/** agent-ops/roadmap/archive/** + +# BEGIN Agent-Ops managed ignore +agent-task/archive/** +agent-ops/roadmap/archive/** +# END Agent-Ops managed ignore diff --git a/.clineignore b/.clineignore index d37067e..1ce2388 100644 --- a/.clineignore +++ b/.clineignore @@ -1,2 +1,7 @@ agent-task/archive/** agent-ops/roadmap/archive/** + +# BEGIN Agent-Ops managed ignore +agent-task/archive/** +agent-ops/roadmap/archive/** +# END Agent-Ops managed ignore diff --git a/.clinerules b/.clinerules index 3dd8000..0fd81a0 100644 --- a/.clinerules +++ b/.clinerules @@ -5,7 +5,8 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. -- `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. diff --git a/.cursorignore b/.cursorignore index d37067e..1ce2388 100644 --- a/.cursorignore +++ b/.cursorignore @@ -1,2 +1,7 @@ agent-task/archive/** agent-ops/roadmap/archive/** + +# BEGIN Agent-Ops managed ignore +agent-task/archive/** +agent-ops/roadmap/archive/** +# END Agent-Ops managed ignore diff --git a/.cursorrules b/.cursorrules index 3dd8000..0fd81a0 100644 --- a/.cursorrules +++ b/.cursorrules @@ -5,7 +5,8 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. -- `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. diff --git a/.geminiignore b/.geminiignore index d37067e..1ce2388 100644 --- a/.geminiignore +++ b/.geminiignore @@ -1,2 +1,7 @@ agent-task/archive/** agent-ops/roadmap/archive/** + +# BEGIN Agent-Ops managed ignore +agent-task/archive/** +agent-ops/roadmap/archive/** +# END Agent-Ops managed ignore diff --git a/AGENTS.md b/AGENTS.md index 3dd8000..0fd81a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,8 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. -- `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. diff --git a/CLAUDE.md b/CLAUDE.md index 3dd8000..0fd81a0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,8 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. -- `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. diff --git a/GEMINI.md b/GEMINI.md index 3dd8000..0fd81a0 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -5,7 +5,8 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. -- `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. diff --git a/agent-ops/.version b/agent-ops/.version index a8646df..da44c7f 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.48 +1.1.50 diff --git a/agent-ops/bin/ai-ignore.sh b/agent-ops/bin/ai-ignore.sh index 186deaa..4c36c39 100755 --- a/agent-ops/bin/ai-ignore.sh +++ b/agent-ops/bin/ai-ignore.sh @@ -3,17 +3,48 @@ # Shared AI ignore / permission defaults for init and sync flows. AGENT_OPS_TASK_ARCHIVE_IGNORE_PATTERN="agent-task/archive/**" AGENT_OPS_ROADMAP_ARCHIVE_IGNORE_PATTERN="agent-ops/roadmap/archive/**" +AGENT_OPS_AI_IGNORE_BLOCK_BEGIN="# BEGIN Agent-Ops managed ignore" +AGENT_OPS_AI_IGNORE_BLOCK_END="# END Agent-Ops managed ignore" AGENT_OPS_AI_IGNORE_FILES=(".geminiignore" ".aiexclude" ".cursorignore" ".clineignore") AGENT_OPS_AI_PERMISSION_FILES=(".claude/settings.json" "opencode.json") AGENT_OPS_AI_SYNC_FILES=("${AGENT_OPS_AI_IGNORE_FILES[@]}" "${AGENT_OPS_AI_PERMISSION_FILES[@]}") -agent_ops_append_unique_line() { +agent_ops_ensure_ai_ignore_block() { local file="$1" - local line="$2" + local tmp touch "$file" - if ! grep -qxF "$line" "$file"; then - printf "%s\n" "$line" >> "$file" + if grep -qxF "$AGENT_OPS_AI_IGNORE_BLOCK_BEGIN" "$file" \ + && grep -qxF "$AGENT_OPS_AI_IGNORE_BLOCK_END" "$file"; then + tmp="$(mktemp "$file.tmp.XXXXXX")" + awk \ + -v begin="$AGENT_OPS_AI_IGNORE_BLOCK_BEGIN" \ + -v end="$AGENT_OPS_AI_IGNORE_BLOCK_END" \ + -v task="$AGENT_OPS_TASK_ARCHIVE_IGNORE_PATTERN" \ + -v roadmap="$AGENT_OPS_ROADMAP_ARCHIVE_IGNORE_PATTERN" ' + $0 == begin { + print begin + print task + print roadmap + print end + in_block = 1 + next + } + $0 == end && in_block { + in_block = 0 + next + } + !in_block { print } + ' "$file" > "$tmp" + mv "$tmp" "$file" + else + if [[ -s "$file" ]]; then + printf "\n" >> "$file" + fi + printf "%s\n" "$AGENT_OPS_AI_IGNORE_BLOCK_BEGIN" >> "$file" + printf "%s\n" "$AGENT_OPS_TASK_ARCHIVE_IGNORE_PATTERN" >> "$file" + printf "%s\n" "$AGENT_OPS_ROADMAP_ARCHIVE_IGNORE_PATTERN" >> "$file" + printf "%s\n" "$AGENT_OPS_AI_IGNORE_BLOCK_END" >> "$file" fi } @@ -51,14 +82,13 @@ def as_object: | .permissions.deny = ( (.permissions.deny | as_array) | append_unique("Read(./agent-task/archive/**)") - | append_unique("Read(./agent-ops/roadmap/archive/**)") ) ' agent_ops_merge_json_with_jq \ "$file" \ "$filter" \ - "Note: .claude/settings.json exists; add Read(./agent-task/archive/**) and Read(./agent-ops/roadmap/archive/**) manually." + "Note: .claude/settings.json exists; add Read(./agent-task/archive/**) manually." } agent_ops_claude_settings_complete() { @@ -68,13 +98,13 @@ def as_array: if type == "array" then . elif . == null then [] else [.] end; (.permissions.deny | as_array) -| index("Read(./agent-task/archive/**)") and index("Read(./agent-ops/roadmap/archive/**)") +| index("Read(./agent-task/archive/**)") ' if command -v jq >/dev/null 2>&1; then jq -e "$filter" "$file" >/dev/null 2>&1 else - grep -q "agent-task/archive" "$file" && grep -q "agent-ops/roadmap/archive" "$file" + grep -q "agent-task/archive" "$file" fi } @@ -91,10 +121,8 @@ def as_object: .permission = ((.permission // {}) | as_object) | .permission.read = ((.permission.read // {}) | as_object) | .permission.read["agent-task/archive/**"] = "deny" -| .permission.read["agent-ops/roadmap/archive/**"] = "deny" | .permission.glob = ((.permission.glob // {}) | as_object) | .permission.glob["agent-task/archive/**"] = "deny" -| .permission.glob["agent-ops/roadmap/archive/**"] = "deny" | .watcher = ((.watcher // {}) | as_object) | .watcher.ignore = ( (.watcher.ignore | as_array) @@ -106,7 +134,7 @@ def as_object: agent_ops_merge_json_with_jq \ "$file" \ "$filter" \ - "Note: opencode.json exists; add agent-task/archive/** and agent-ops/roadmap/archive/** read/glob deny and watcher ignore manually." + "Note: opencode.json exists; add agent-task/archive/** read/glob deny and agent-task/archive/** plus agent-ops/roadmap/archive/** watcher ignore manually." } agent_ops_opencode_config_complete() { @@ -116,9 +144,7 @@ def as_array: if type == "array" then . elif . == null then [] else [.] end; (.permission.read["agent-task/archive/**"] == "deny") -and (.permission.read["agent-ops/roadmap/archive/**"] == "deny") and (.permission.glob["agent-task/archive/**"] == "deny") -and (.permission.glob["agent-ops/roadmap/archive/**"] == "deny") and ((.watcher.ignore | as_array) | index("agent-task/archive/**") and index("agent-ops/roadmap/archive/**")) ' @@ -129,6 +155,46 @@ and ((.watcher.ignore | as_array) | index("agent-task/archive/**") and index("ag fi } +agent_ops_warn_existing_roadmap_hard_deny() { + local target_dir="$1" + local found="0" + local file + + file="$target_dir/.claude/settings.json" + if [[ -f "$file" ]]; then + if command -v jq >/dev/null 2>&1; then + if jq -e ' +def as_array: + if type == "array" then . elif . == null then [] else [.] end; +(.permissions.deny | as_array) +| index("Read(./agent-ops/roadmap/archive/**)") +' "$file" >/dev/null 2>&1; then + found="1" + fi + elif grep -q "Read(./agent-ops/roadmap/archive/**)" "$file"; then + found="1" + fi + fi + + file="$target_dir/opencode.json" + if [[ -f "$file" ]]; then + if command -v jq >/dev/null 2>&1; then + if jq -e ' +(.permission.read["agent-ops/roadmap/archive/**"] == "deny") +or (.permission.glob["agent-ops/roadmap/archive/**"] == "deny") +' "$file" >/dev/null 2>&1; then + found="1" + fi + elif grep -Eq '"agent-ops/roadmap/archive/\*\*"[[:space:]]*:[[:space:]]*"deny"' "$file"; then + found="1" + fi + fi + + if [[ "$found" == "1" ]]; then + echo " Warning: 기존 roadmap archive hard deny는 사용자 설정으로 보고 보존했습니다. 링크 기반 archive 읽기가 필요하면 수동 확인하세요." + fi +} + ensure_agent_ops_ai_ignore_config() { local target_dir="$1" local ignore_file @@ -139,8 +205,7 @@ ensure_agent_ops_ai_ignore_config() { fi for ignore_file in "${AGENT_OPS_AI_IGNORE_FILES[@]}"; do - agent_ops_append_unique_line "$target_dir/$ignore_file" "$AGENT_OPS_TASK_ARCHIVE_IGNORE_PATTERN" - agent_ops_append_unique_line "$target_dir/$ignore_file" "$AGENT_OPS_ROADMAP_ARCHIVE_IGNORE_PATTERN" + agent_ops_ensure_ai_ignore_block "$target_dir/$ignore_file" done mkdir -p "$target_dir/.claude" @@ -150,8 +215,7 @@ ensure_agent_ops_ai_ignore_config() { "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "deny": [ - "Read(./agent-task/archive/**)", - "Read(./agent-ops/roadmap/archive/**)" + "Read(./agent-task/archive/**)" ] } } @@ -166,12 +230,10 @@ EOF "$schema": "https://opencode.ai/config.json", "permission": { "read": { - "agent-task/archive/**": "deny", - "agent-ops/roadmap/archive/**": "deny" + "agent-task/archive/**": "deny" }, "glob": { - "agent-task/archive/**": "deny", - "agent-ops/roadmap/archive/**": "deny" + "agent-task/archive/**": "deny" } }, "watcher": { @@ -185,4 +247,6 @@ EOF elif ! agent_ops_opencode_config_complete "$target_dir/opencode.json"; then agent_ops_merge_opencode_config "$target_dir/opencode.json" fi + + agent_ops_warn_existing_roadmap_hard_deny "$target_dir" } diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index 0764d94..213e60c 100644 --- a/agent-ops/rules/common/rules-roadmap.md +++ b/agent-ops/rules/common/rules-roadmap.md @@ -2,21 +2,45 @@ `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서만 적용한다. +## 구조 + +- 최상위 로드맵은 `agent-ops/roadmap/ROADMAP.md`다. +- 활성 Phase는 `agent-ops/roadmap/phase//PHASE.md`에 둔다. +- 활성 Milestone은 해당 Phase 아래 `agent-ops/roadmap/phase//milestones/.md`에 둔다. +- 완료된 Phase는 scaffold 그대로 `agent-ops/roadmap/archive/phase//PHASE.md`로 이동하고, 하위 Milestone도 `archive/phase//milestones/` 아래에 둔다. +- 진행중 Phase 안에서 완료된 Milestone은 활성 `PHASE.md`에 짧은 archive 링크를 남기고, 상세 문서는 `agent-ops/roadmap/archive/phase//milestones/`로 이동한다. +- archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. + ## 로딩 -- 세션 최초 1회 `agent-ops/roadmap/current.md`를 읽고 활성 Milestone 후보의 이름, 경로, 선택 규칙만 짧게 기억한다. -- 활성 Milestone 후보는 `agent-ops/roadmap/milestones/` 하위 문서만 대상으로 한다. -- Milestone의 목표, 주요 범위, 범위 제외는 선택한 활성 Milestone 문서에서 확인한다. +- 세션 최초 1회 `agent-ops/roadmap/current.md`를 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다. - 일반 작업에서는 `ROADMAP.md`를 읽지 않는다. -- `ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정, 활성 Milestone 밖 작업 확인 때만 읽는다. -- `agent-ops/roadmap/archive/**`는 사용자가 과거 Milestone 상세 확인이나 복원을 명시적으로 요청한 경우에만 읽는다. +- 일반 작업에서는 `agent-ops/roadmap/archive/**`를 읽지 않는다. +- 기능 추가, 구조 변경, 구현 계획, 현재 작업 분석 전에는 요청과 변경 파일에 맞는 활성 Phase와 활성 Milestone 문서를 읽는다. +- `ROADMAP.md`는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다. +- 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다. -## Milestone 선택 +## Phase와 Milestone 선택 -- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. -- 기능 추가, 구조 변경, 스킬/문서 구조 변경 전에는 요청, 브랜치, 변경 파일, 관련 경로를 보고 관련 Milestone 문서를 1회 읽는다. -- 선택한 Milestone의 목표 또는 범위 제외와 요청이 충돌하면 구현 전에 사용자에게 확인한다. -- `current.md`가 아카이브 경로를 가리키면 그 항목은 활성 후보로 읽지 말고 로드맵 갱신이 필요하다고 보고한다. +- `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 흐름은 완료, 진행중, 계획 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다. ## 구현 잠금 @@ -28,23 +52,28 @@ - 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 표준선으로 처리 가능한 작업을 막지 않는다. - 잠금 상태를 바꾸더라도 `필수 기능`이나 `완료 기준`을 자동 완료 처리하지 않는다. -## 필수 기능 item-id +## Epic과 Task id -- Milestone 문서의 `필수 기능` 체크리스트는 `- [ ] [item-id] 설명` 형식을 사용한다. -- item-id는 공백 없는 짧은 ASCII 토큰이며, 영문/숫자 segment 1~4개로 작성하고 segment 구분자는 `-`, `_`, `+`, `=`만 사용한다. 가능하면 1~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다. -- item-id는 해당 Milestone 안에서만 유일하면 된다. -- 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. 여러 Milestone 후보에서 같은 item-id가 발견되면 Milestone 이름이나 문서 경로로 대상을 확정한다. -- 사용자가 item-id를 언급하면 해당 Milestone의 `필수 기능` 항목을 우선 anchor로 삼고, 기존 item-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, 활성 Milestone 문서를 함께 본다. +- 이때 `current.md`만으로 단정하지 말고 코드, git 상태, diff, 활성 Phase, 활성 Milestone 문서를 함께 본다. +- Phase 또는 Milestone 후보가 여럿이면 단순 나열하지 말고 1순위와 2순위를 추천하고 근거를 함께 제시한다. -## Milestone 아카이브 +## 아카이브 -- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Milestone은 `update-roadmap` 스킬로 아카이빙한다. -- 아카이브 대상 문서는 `agent-ops/roadmap/archive/YYYY/MM/.md`로 이동한다. -- 아카이빙할 때는 `ROADMAP.md`에 당시 요약만 남기고, 아카이브 문서 자체는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다. -- 아카이브된 Milestone은 `current.md`에 남기지 않고, 일반 Milestone 선택이나 위치 분석의 후보로 삼지 않는다. +- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 `update-roadmap` 스킬로 아카이빙한다. +- Phase 아카이브 대상은 `agent-ops/roadmap/archive/phase//PHASE.md`와 같은 scaffold로 이동한다. +- Milestone 아카이브 대상은 `agent-ops/roadmap/archive/phase//milestones/.md`로 이동한다. +- 아카이빙할 때는 활성 `ROADMAP.md` 또는 활성 `PHASE.md`에 archive 문서 링크와 짧은 요약만 남긴다. +- 아카이브된 Phase/Milestone은 `current.md`에 남기지 않고, 일반 Phase/Milestone 선택이나 위치 분석의 후보로 삼지 않는다. +- 아카이브 문서는 과거 기록 스냅샷으로 보고, 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다. diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index 3dd8000..0fd81a0 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -5,7 +5,8 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. -- `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. +- `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. diff --git a/agent-ops/skills/common/_templates/roadmap-current-template.md b/agent-ops/skills/common/_templates/roadmap-current-template.md index ff6695f..0acca3a 100644 --- a/agent-ops/skills/common/_templates/roadmap-current-template.md +++ b/agent-ops/skills/common/_templates/roadmap-current-template.md @@ -1,14 +1,24 @@ # 현재 로드맵 컨텍스트 +## 활성 Phase + +- [<계획 | 진행중 | 완료 | 보류 | 폐기>] + - 경로: `agent-ops/roadmap/phase//PHASE.md` + ## 활성 Milestone -- : agent-ops/roadmap/milestones/.md +- [<계획 | 진행중 | 완료 | 보류 | 폐기>] + - Phase: `agent-ops/roadmap/phase//PHASE.md` + - 경로: `agent-ops/roadmap/phase//milestones/.md` ## 선택 규칙 -- 이 문서는 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. -- 활성 Milestone은 `agent-ops/roadmap/milestones/` 하위 문서만 가리키며, `agent-ops/roadmap/archive/**`는 포함하지 않는다. -- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택하고 같은 세션에서 1회 읽는다. -- 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. -- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. +- 이 문서는 활성 Phase와 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. +- 활성 Phase는 `agent-ops/roadmap/phase//PHASE.md`를 가리킨다. +- 활성 Milestone은 `agent-ops/roadmap/phase//milestones/.md`를 가리킨다. +- 활성 항목은 아카이브 경로를 포함하지 않는다. +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Phase와 Milestone을 선택하고 같은 세션에서 1회 읽는다. +- 활성 Phase 또는 Milestone 둘 이상에 걸치면 필요한 문서를 모두 읽고 작업 범위를 좁힌다. +- 활성 범위 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. +- 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다. - 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금을 유지한 채 진행할 수 있으며, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다. diff --git a/agent-ops/skills/common/_templates/roadmap-milestone-template.md b/agent-ops/skills/common/_templates/roadmap-milestone-template.md index 31739d8..1668d12 100644 --- a/agent-ops/skills/common/_templates/roadmap-milestone-template.md +++ b/agent-ops/skills/common/_templates/roadmap-milestone-template.md @@ -1,16 +1,17 @@ -# +# Milestone: + +## 위치 + +- Roadmap: `agent-ops/roadmap/ROADMAP.md` +- Phase: `agent-ops/roadmap/phase//PHASE.md` ## 목표 <이 Milestone이 끝났을 때 달성되어야 하는 결과를 1~3문장으로 작성> -## 단계 - - - ## 상태 -<계획 | 진행 중 | 완료 | 보류 | 폐기> +[<계획 | 진행중 | 완료 | 보류 | 폐기>] ## 구현 잠금 @@ -24,7 +25,18 @@ ## 필수 기능 - + + +### Epic: [epic-id] + +<이 Epic이 묶는 capability 또는 산출물 설명> + - [ ] [item-id] <구현 세부가 아니라 이 Milestone에서 달성해야 할 capability 또는 산출물> ## 완료 기준 diff --git a/agent-ops/skills/common/_templates/roadmap-phase-template.md b/agent-ops/skills/common/_templates/roadmap-phase-template.md new file mode 100644 index 0000000..c166999 --- /dev/null +++ b/agent-ops/skills/common/_templates/roadmap-phase-template.md @@ -0,0 +1,22 @@ +# Phase: + +## 상태 + +[<계획 | 진행중 | 완료 | 보류 | 폐기>] + +## 목표 + +<이 Phase가 끝났을 때 달성되어야 하는 결과와 책임 경계를 1~3문장으로 작성> + +## Milestone 흐름 + +완료된 Milestone은 archive 경로를 가리키고, 진행중 또는 계획 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다. +완료, 진행중, 계획 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다. + +- [<계획 | 진행중 | 완료 | 보류 | 폐기>] + - 경로: `agent-ops/roadmap/phase//milestones/.md` 또는 `agent-ops/roadmap/archive/phase//milestones/.md` + - 요약: <목표 또는 결과 1문장> + +## Phase 경계 + +- <이 Phase에서 유지할 책임 경계 또는 범위 제외 기준> diff --git a/agent-ops/skills/common/_templates/roadmap-position-report-template.md b/agent-ops/skills/common/_templates/roadmap-position-report-template.md index 64b1dbf..8b7e228 100644 --- a/agent-ops/skills/common/_templates/roadmap-position-report-template.md +++ b/agent-ops/skills/common/_templates/roadmap-position-report-template.md @@ -1,7 +1,10 @@ # 현재 작업 분석 +- 추정 Phase: - 추정 Milestone: -- Milestone 링크: [](agent-ops/roadmap/milestones/.md) +- Phase 링크: [](agent-ops/roadmap/phase//PHASE.md) +- Milestone 링크: [](agent-ops/roadmap/phase//milestones/.md) +- 우선순위 추천: <단일 후보 | 1순위: phase/milestone; 2순위: phase/milestone; 추천 근거> - 신뢰도: <높음 | 중간 | 낮음> - 구현 잠금: <해제 | 잠금 | 정보 없음> - 결정 필요: <없음 | 현재 요청에 직접 영향을 주는 사용자 결정 항목 요약> @@ -14,15 +17,21 @@ - 로드맵 근거: - 코드/테스트 근거: <코드, 테스트, diff, 문서에서 확인한 근거> +## 후보 우선순위 + +- 1순위: <단일 후보 또는 가장 먼저 봐야 할 Phase/Milestone과 이유> +- 2순위: <없음 또는 다음으로 봐야 할 Phase/Milestone과 이유> +- 낮은 우선순위/보류: <없음 또는 후보에서 밀린 Phase/Milestone과 이유> + ## 구현된 것으로 보이는 부분 -- 확인됨: [] <코드/문서/테스트 근거가 있는 완료 후보> +- 확인됨: [] [] <코드/문서/테스트 근거가 있는 완료 후보> ## 남은 작업 -- 확인됨: [] <코드/문서/테스트 근거로 남았다고 볼 수 있는 작업> -- 추정됨: [] <구조상 필요해 보이나 추가 확인이 필요한 작업> -- 확인 필요: [] <사용자 판단, 범위 결정, 제품 의도가 필요한 작업> +- 확인됨: [] [] <코드/문서/테스트 근거로 남았다고 볼 수 있는 작업> +- 추정됨: [] [] <구조상 필요해 보이나 추가 확인이 필요한 작업> +- 확인 필요: [] [] <사용자 판단, 범위 결정, 제품 의도가 필요한 작업> ## 위험/불확실성 diff --git a/agent-ops/skills/common/_templates/roadmap-template.md b/agent-ops/skills/common/_templates/roadmap-template.md index c707f4c..2449c30 100644 --- a/agent-ops/skills/common/_templates/roadmap-template.md +++ b/agent-ops/skills/common/_templates/roadmap-template.md @@ -6,33 +6,32 @@ ## Phase 흐름 -- : <이 Phase의 목표와 역할> +위에서 아래로 진행된 순서와 예정 흐름을 나타낸다. +완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다. +진행중 Phase는 계획 Phase보다 위에 두어, 아래로 갈수록 미래 계획에 가까워지게 정렬한다. -## Milestone 목록 - -### - -- [](milestones/.md) - 상태: <계획 | 진행 중 | 완료 | 보류 | 폐기>; 목표: <짧은 목표 요약> - -## 아카이브 Milestone 요약 - - -- 없음 +- [<계획 | 진행중 | 완료 | 보류 | 폐기>] + - 경로: `agent-ops/roadmap/phase//PHASE.md` 또는 `agent-ops/roadmap/archive/phase//PHASE.md` + - 요약: <이 Phase의 목표와 역할 1문장> ## 로딩 정책 - 일반 작업에서는 `agent-ops/roadmap/ROADMAP.md`를 매번 읽지 않는다. - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다. -- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. +- `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다. - `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. -- `current.md`의 활성 Milestone은 `agent-ops/roadmap/milestones/` 하위 문서만 가리키며, `agent-ops/roadmap/archive/**`는 포함하지 않는다. -- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다. -- 활성 Milestone 밖의 작업이면 이 문서의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. -- 이 문서는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. -- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다. -- 완료 또는 폐기되어 아카이브된 Milestone은 이 문서의 `아카이브 Milestone 요약`에 당시 요약만 남기고, 아카이브 문서 링크나 상세 경로는 남기지 않는다. -- 상세 문서가 있는 `agent-ops/roadmap/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. -- 아카이브된 Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다. +- `current.md`의 활성 Phase는 `agent-ops/roadmap/phase//PHASE.md`를 가리킨다. +- `current.md`의 활성 Milestone은 `agent-ops/roadmap/phase//milestones/.md`를 가리킨다. +- `current.md`는 `agent-ops/roadmap/archive/**` 경로를 활성 항목으로 포함하지 않는다. +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다. +- 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. +- 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다. +- 상세 작업과 완료 기준은 각 Milestone 문서의 `필수 기능`, `완료 기준`으로 관리한다. +- 완료된 Phase는 `agent-ops/roadmap/archive/phase//PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다. +- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 `agent-ops/roadmap/archive/phase//milestones/`로 이동한다. +- archive `PHASE.md`는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. +- `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라가서 읽는다. +- 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다. - 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획 생성, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. - 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조/도메인 rule/플랫폼 관례로 정할 수 있는 작업은 표준선으로 기록하고 진행할 수 있다. - Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다. diff --git a/agent-ops/skills/common/_templates/skill-template.md b/agent-ops/skills/common/_templates/skill-template.md index 2372acb..d3acdc2 100644 --- a/agent-ops/skills/common/_templates/skill-template.md +++ b/agent-ops/skills/common/_templates/skill-template.md @@ -2,7 +2,6 @@ name: version: 1.0.0 description: <이 skill이 하는 일을 한 줄로 설명. 트리거 키워드 포함 권장> -depends: [] # 선택 — 의존 skill이 없으면 이 줄 삭제 --- # diff --git a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md index e2f77b4..d3b1fbb 100644 --- a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md +++ b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md @@ -1,64 +1,68 @@ --- name: analyze-roadmap-position -version: 1.5.0 -description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확인 요청에 대해 활성 Milestone과 코드 상태를 함께 읽어 현재 작업 지점, Milestone 문서 링크, 남은 일을 추정하는 읽기 전용 스킬" +version: 1.8.0 +description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확인 요청에 대해 로드맵이 있으면 활성 Phase/Milestone과 코드 상태를 함께 읽고, 로드맵이 없으면 git/active task 기준으로 현재 작업 지점과 남은 일을 추정하는 읽기 전용 스킬" --- # 작업 지점 분석 ## 목적 -현재 브랜치, 변경 파일, 코드 구조, 활성 Milestone 문서를 함께 분석해 지금 작업이 어느 Milestone에 걸쳐 있는지와 남은 작업 후보를 보고한다. -결과에는 추정한 Milestone의 문서 링크를 항상 함께 출력한다. -Milestone의 `필수 기능` 항목에 item-id가 있으면 남은 작업과 판단 근거에 함께 표시해 사용자가 짧은 id로 후속 지시를 할 수 있게 한다. -결과 보고는 `agent-ops/skills/common/_templates/roadmap-position-report-template.md` 템플릿의 섹션, 필드, 순서를 그대로 따라 작성한다. +현재 브랜치, 변경 파일, 코드 구조를 분석하고, 로드맵이 있으면 활성 Phase와 활성 Milestone 문서를 함께 읽어 지금 작업이 어느 Phase/Milestone에 걸쳐 있는지와 남은 작업 후보를 보고한다. +로드맵이 있으면 결과에는 추정한 Phase와 Milestone의 문서 링크를 함께 출력한다. +Phase나 Milestone 후보가 여럿이면 가장 먼저 볼 후보와 다음 후보를 추천하고, 추천 근거를 짧게 남긴다. +Milestone의 `필수 기능`에 Epic/Task id가 있으면 남은 작업과 판단 근거에 함께 표시해 사용자가 짧은 id로 후속 지시를 할 수 있게 한다. `current.md`만 보고 현재 작업 위치를 단정하지 않고, 실제 코드 상태와 요청 내용을 근거로 판단한다. +`agent-ops/roadmap/` 디렉터리 또는 `current.md`가 없으면 로드맵 분석을 건너뛰고 git 상태, active `agent-task`, 요청 문장을 기준으로만 보고한다. ## 언제 호출할지 - 사용자가 "지금 작업이 뭐지?", "현재 작업이 뭐야?", "어디까지 했지?"라고 물을 때 - 사용자가 현재 브랜치 또는 변경 파일 기준으로 남은 작업을 알고 싶어 할 때 -- 활성 Milestone 안에서 이번 요청이 어느 범위에 속하는지 확인해야 할 때 +- 활성 Phase/Milestone 안에서 이번 요청이 어느 범위에 속하는지 확인해야 할 때 - 구현 전에 로드맵 기준 작업 위치를 가볍게 점검해야 할 때 -## 입력 - -- `question`: 사용자의 현재 작업 지점 질문 또는 남은 작업 질문 (선택) -- `scope`: 분석할 경로, 기능명, 도메인명, 브랜치명 힌트 (선택) -- `depth`: `quick` 또는 `deep` (선택, 없으면 `quick`) - ## 먼저 확인할 것 - [ ] `agent-ops/skills/common/_templates/roadmap-position-report-template.md`를 읽어 최신 답변 템플릿 확인 +- [ ] `agent-ops/roadmap/` 디렉터리 존재 여부 확인 - [ ] `agent-ops/roadmap/current.md` 존재 여부 확인 -- [ ] `current.md`의 활성 Milestone 목록이 가리키는 문서 존재 여부 확인 -- [ ] 활성 Milestone 목록이 `agent-ops/roadmap/archive/**` 경로를 가리키지 않는지 확인 -- [ ] 활성 Milestone 이름과 문서 경로를 결과 출력에 쓸 Markdown 링크로 기록 +- [ ] 로드맵이 있으면 `current.md`의 활성 Phase와 활성 Milestone 목록이 가리키는 문서 존재 여부 확인 +- [ ] 로드맵이 있으면 활성 항목이 `agent-ops/roadmap/archive/**` 경로를 가리키지 않는지 확인 +- [ ] 로드맵이 있으면 활성 Phase/Milestone 이름과 문서 경로를 결과 출력에 쓸 Markdown 링크로 기록 - [ ] git 저장소이면 현재 브랜치, `git status --short`, 변경 파일 목록 확인 - [ ] 변경 파일이 있으면 `agent-ops/rules/project/rules.md`의 도메인 매핑 기준으로 관련 domain rule 확인 ## 실행 절차 -1. **활성 Milestone 창 확인** - - `agent-ops/roadmap/current.md`를 읽고 활성 Milestone 후보와 선택 규칙을 파악한다. +1. **활성 창 확인** + - `agent-ops/roadmap/` 디렉터리가 없으면 `ROADMAP.md`, `current.md`, Phase, Milestone, archive 문서를 읽지 않고 로드맵 없음으로 기록한 뒤 작업 흔적 확인으로 넘어간다. 이 경우 아래 로드맵 읽기 단계는 수행하지 않는다. + - `agent-ops/roadmap/current.md`가 없으면 `ROADMAP.md`를 자동으로 읽지 않는다. 로드맵 컨텍스트는 `없음` 또는 `확인 불가`로 기록하고 작업 흔적 확인으로 넘어간다. 이 경우 아래 로드맵 읽기 단계는 수행하지 않는다. + - `agent-ops/roadmap/current.md`를 읽고 활성 Phase, 활성 Milestone 후보와 선택 규칙을 파악한다. - `current.md`의 후보가 `agent-ops/roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 로드맵 갱신 필요 항목으로 기록한다. - - 활성 Milestone 문서를 모두 읽되, 목록이 많으면 사용자 요청이나 변경 파일과 관련 높은 문서부터 읽는다. - - 읽은 Milestone은 `: ` 형태로 보존하고, 결과 보고에서는 `[]()` Markdown 링크로 출력한다. - - `current.md`가 없거나 형식이 맞지 않으면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 불확실성을 보고한다. + - 관련 활성 Phase 문서를 읽고 Phase 목표, Milestone 흐름, Phase 경계를 확인한다. + - 관련 활성 Milestone 문서를 읽고 목표, 범위, 필수 기능, 완료 기준, 범위 제외, 구현 잠금을 확인한다. + - 목록이 많으면 사용자 요청이나 변경 파일과 관련 높은 Phase/Milestone부터 읽는다. + - `current.md` 형식이 맞지 않으면 `ROADMAP.md`를 자동으로 읽지 말고 로드맵 컨텍스트 불확실성을 보고한다. 2. **작업 흔적 확인** - git 저장소이면 `git branch --show-current`, `git status --short`, `git diff --name-only`, 필요 시 `git diff --stat`을 확인한다. - 변경 파일이 없으면 사용자의 요청 문장과 최근 대상 경로 힌트를 기준으로 추정한다. - 변경 파일이 있으면 관련 코드와 테스트 파일을 필요한 만큼만 읽는다. -3. **Milestone 매칭** +3. **Phase/Milestone 매칭** + - 로드맵이 없거나 `current.md`가 없으면 Phase/Milestone을 추정하지 않는다. `추정 Phase`, `추정 Milestone`, 문서 링크는 `없음`으로 기록하고 아래 Phase/Milestone 비교 항목은 수행하지 않는다. + - 활성 Phase의 목표/경계와 변경 파일/요청 내용을 비교한다. - 활성 Milestone의 목표, 범위, 완료 기준, 범위 제외 항목과 변경 파일/요청 내용을 비교한다. - - 활성 Milestone의 `필수 기능` 체크리스트를 확인하고, 관련 항목에 item-id가 있으면 판단 근거와 남은 작업에 item-id를 함께 기록한다. - - 여러 Milestone 후보에서 같은 item-id가 보이면 item-id만으로 위치를 확정하지 말고 Milestone 이름과 문서 링크를 함께 제시한다. - - 활성 Milestone의 `구현 잠금` 섹션, 상태, `결정 필요` 항목을 함께 확인한다. 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 사용자 결정 항목과 배경 미정 항목을 구분해 보고하고, 결정이 모두 정해진 작업이면 로드맵에서 해제 가능하다고 보고한다. + - Milestone의 `필수 기능`에서 관련 Epic/Task id가 있으면 판단 근거와 남은 작업에 함께 기록한다. + - 여러 Milestone 후보에서 같은 epic-id 또는 item-id가 보이면 id만으로 위치를 확정하지 말고 Milestone 이름과 문서 링크를 함께 제시한다. + - 활성 Milestone의 `구현 잠금` 섹션, 상태, `결정 필요` 항목을 함께 확인한다. - 하나의 Milestone에 명확히 속하면 단일 후보로 보고한다. - - 둘 이상의 Milestone에 걸치면 복수 후보로 보고하고, 어떤 파일이나 기능이 어느 Milestone에 닿는지 나눈다. - - 활성 Milestone 밖으로 보이면 `ROADMAP.md`의 Milestone 목록을 확인하고 전환 또는 신규 Milestone 필요성을 제안한다. + - 둘 이상의 Phase 또는 Milestone에 걸치면 복수 후보로 보고하고, 어떤 파일이나 기능이 어느 후보에 닿는지 나눈다. + - 복수 후보일 때는 후보 우선순위를 추천한다. 요청 문장/변경 파일 직접성, 현재 diff 근거, Milestone 상태, 구현 잠금, 선후 의존성, Phase/Milestone 흐름상 위치를 함께 본다. + - 관련성이 비슷하면 `[진행중]` 후보를 `[계획]` 후보보다 우선하고, 같은 상태라면 현재 변경 파일을 더 많이 설명하는 후보를 우선한다. + - 사용자가 특정 Phase, Milestone, epic-id, item-id, 파일 경로를 명시했으면 그 후보를 우선하되, 범위 제외나 잠금 결정 필요가 있으면 우선순위 근거에 같이 적는다. + - 로드맵이 있고 활성 Phase/Milestone 밖으로 보이면 `ROADMAP.md`의 Phase 흐름을 확인하고 전환 또는 신규 Phase/Milestone 필요성을 제안한다. 4. **남은 작업 분류** - `확인됨`: 코드, 문서, 테스트, diff로 근거가 있는 남은 작업 @@ -71,27 +75,27 @@ Milestone의 `필수 기능` 항목에 item-id가 있으면 남은 작업과 판 - 템플릿의 섹션 제목, 필드명, 순서를 바꾸지 않는다. - 템플릿의 모든 필드를 채우며, 근거가 없으면 생략하지 말고 `없음`, `확인 불가`, `확인 필요` 중 하나로 명시한다. - `판단 근거`에는 브랜치, 변경 파일, 로드맵 근거, 코드/테스트 근거를 각각 분리해 적는다. + - `후보 우선순위`에는 복수 후보일 때 1순위와 2순위를 적고, 단일 후보이면 `단일 후보`라고 적는다. - `남은 작업`은 `확인됨`, `추정됨`, `확인 필요` 세 분류를 모두 유지한다. - `다음 행동`에는 가장 우선해야 할 실행 또는 확인을 1~2개만 적는다. - `읽은 주요 파일`에는 실제로 읽은 핵심 파일만 적는다. -Milestone을 하나로 확정할 수 없으면 후보 Milestone마다 링크를 출력한다. -Milestone 문서 경로를 찾지 못한 경우에도 링크 항목을 생략하지 말고 `링크 확인 불가: <이유>`와 확인한 로드맵 파일 경로를 함께 적는다. - ## 실행 결과 검증 - [ ] `roadmap-position-report-template.md`를 읽고 그 섹션 순서와 필드명을 유지했는가 -- [ ] `current.md`만 근거로 현재 위치를 단정하지 않았는가 -- [ ] 활성 Milestone 문서의 목표와 범위 제외 항목을 확인했는가 +- [ ] 로드맵이 없는 프로젝트에서 `ROADMAP.md`, `current.md`, Phase, Milestone 문서를 읽으려 하지 않았는가 +- [ ] 로드맵이 있는 프로젝트에서 `current.md`만 근거로 현재 위치를 단정하지 않았는가 +- [ ] 로드맵이 있는 프로젝트에서 활성 Phase 문서의 목표와 Phase 경계를 확인했는가 +- [ ] 로드맵이 있는 프로젝트에서 활성 Milestone 문서의 목표와 범위 제외 항목을 확인했는가 - [ ] `agent-ops/roadmap/archive/**` 문서를 명시 요청 없이 읽지 않았는가 -- [ ] 활성 Milestone 문서의 `구현 잠금` 섹션 존재 여부, 상태, `결정 필요` 항목을 확인했는가 -- [ ] 추정 Milestone마다 문서 링크를 출력했는가 -- [ ] 관련 `필수 기능` 항목에 item-id가 있으면 결과에 함께 표시했는가 -- [ ] 변경 파일 또는 사용자 요청과 Milestone 판단 근거가 연결되어 있는가 +- [ ] 로드맵이 있는 프로젝트에서 활성 Milestone 문서의 `구현 잠금` 섹션 존재 여부, 상태, `결정 필요` 항목을 확인했는가 +- [ ] 로드맵이 있는 프로젝트에서 추정 Phase/Milestone마다 문서 링크를 출력했는가 +- [ ] 로드맵이 있는 프로젝트에서 Phase/Milestone 후보가 여럿이면 1순위와 2순위 추천 및 근거를 출력했는가 +- [ ] 로드맵이 있는 프로젝트에서 관련 Epic/Task id가 있으면 결과에 함께 표시했는가 +- [ ] 변경 파일 또는 사용자 요청과 Phase/Milestone 판단 근거가 연결되어 있는가 - [ ] 남은 작업을 `확인됨`, `추정됨`, `확인 필요`로 구분했는가 - [ ] 템플릿 필드를 근거 없이 생략하지 않고 `없음`, `확인 불가`, `확인 필요`로 채웠는가 - [ ] 로드맵 파일을 수정하지 않았는가 -- 검증 실패 시: 부족한 근거를 명시하고 신뢰도를 낮춘다. Milestone 링크 누락은 출력 전 반드시 보정한다. ## 출력 형식 @@ -99,11 +103,13 @@ Milestone 문서 경로를 찾지 못한 경우에도 링크 항목을 생략하 - 템플릿을 그대로 복사해 placeholder를 채운다. - 섹션 제목과 필드명을 임의로 번역, 축약, 삭제하지 않는다. - 값이 없는 필드는 `없음`, `확인 불가`, `확인 필요` 중 하나로 채운다. +- 로드맵이 없는 프로젝트에서는 추정 Phase, 추정 Milestone, Phase 링크, Milestone 링크, 로드맵 근거를 `없음`으로 채운다. ## 금지 사항 - `current.md`만 읽고 현재 작업 위치를 확정하지 않는다. -- 사용자가 명시하지 않은 상태에서 `ROADMAP.md`, `current.md`, Milestone 문서를 수정하지 않는다. +- 로드맵이 없는 프로젝트에서 로드맵 파일을 만들거나 읽는 것을 현재 작업 분석의 선행 조건으로 삼지 않는다. +- 사용자가 명시하지 않은 상태에서 `ROADMAP.md`, `current.md`, Phase, Milestone 문서를 수정하지 않는다. - 사용자가 명시하지 않은 상태에서 `agent-ops/roadmap/archive/**`를 읽지 않는다. -- evidence 없이 Milestone이나 기능을 완료 처리하지 않는다. -- 활성 Milestone 밖 작업을 임의로 새 Milestone으로 추가하지 않는다. +- evidence 없이 Phase, Milestone, Epic, Task를 완료 처리하지 않는다. +- 활성 Phase/Milestone 밖 작업을 임의로 새 항목으로 추가하지 않는다. diff --git a/agent-ops/skills/common/create-roadmap/SKILL.md b/agent-ops/skills/common/create-roadmap/SKILL.md index cb757d6..48963c1 100644 --- a/agent-ops/skills/common/create-roadmap/SKILL.md +++ b/agent-ops/skills/common/create-roadmap/SKILL.md @@ -1,24 +1,22 @@ --- name: create-roadmap -version: 1.9.0 -description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase, 결정 필요 체크리스트 기반 구현 잠금이 있는 순번 없는 Milestone 문서, 활성 Milestone 창을 처음 생성하는 공통 스킬 +version: 1.11.0 +description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하는 공통 스킬 --- # 로드맵 생성 ## 목적 -`agent-ops/roadmap/` 하위에 전체 목표 / Phase / Milestone 기반 한국어 로드맵 구조를 처음 생성한다. -전체 로드맵은 로드맵 설계와 갱신 때만 읽고, 일반 작업에서는 `current.md`의 활성 Milestone 창과 관련 Milestone 문서만 읽도록 공통 로드맵 룰을 따른다. -Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서로 시작한다. -새 Milestone의 `구현 잠금`은 사용자만 결정할 수 있는 항목이 있을 때만 잠금으로 둔다. 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 정할 수 있는 항목은 `결정 필요`가 아니라 필요 시 표준선으로 기록한다. -Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 해제 상태로 둔다. +`agent-ops/roadmap/` 하위에 `Roadmap -> Phase -> Milestone` 기반 한국어 로드맵 구조를 처음 생성한다. +전체 로드맵은 전체 방향과 Phase index만 담당하고, 일반 작업에서는 `current.md`의 활성 Phase/Milestone 링크와 관련 문서만 읽도록 만든다. +Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서다. +Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `필수 기능` 안에서 관리한다. ## 언제 호출할지 - 프로젝트에 파일 기반 로드맵을 처음 만들 때 - 사용자가 "로드맵 만들어줘", "마일스톤 설계해줘", "goal/phase 구조 잡아줘"라고 요청할 때 -- AI-first 개인/소규모 개발 프로젝트의 현재 방향성과 작업 기준을 구조화해야 할 때 - 기존 README나 메모에 흩어진 계획을 `agent-ops/roadmap/` 구조로 분리할 때 ## 입력 @@ -26,6 +24,7 @@ Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이 - `overall-goal`: 프로젝트 전체 목표 한 줄 또는 짧은 문단 (선택, 없으면 README와 현재 구조에서 추론) - `phase-hints`: 예상 Phase 목록 또는 단계 힌트 (선택) - `milestone-hints`: 예상 Milestone 목록 또는 기능 힌트 (선택) +- `active-phases`: 현재 열어둘 Phase 목록 (선택, 없으면 현재 구현 상태와 요청에서 추론) - `active-milestones`: 현재 열어둘 Milestone 목록 (선택, 없으면 현재 구현 상태와 요청에서 추론) ## 생성 구조 @@ -35,63 +34,59 @@ agent-ops/ roadmap/ ROADMAP.md current.md - milestones/ - .md + phase/ + / + PHASE.md + milestones/ + .md archive/ - YYYY/MM/.md # 아카이빙 시 생성 + phase/ + / + PHASE.md + milestones/ + .md ``` | 파일 | 역할 | |------|------| -| `agent-ops/roadmap/ROADMAP.md` | 전체 목표, Phase 흐름, 문서 순서 기반 Milestone 목록. 로드맵 생성/갱신/Phase 전환 때만 읽는다 | -| `agent-ops/roadmap/current.md` | 지금 열려 있는 활성 Milestone 창과 선택 규칙을 담는 얇은 포인터 | -| `agent-ops/roadmap/milestones/.md` | 일반 작업 시 읽는 Milestone 단위 목표, 구현 잠금, 범위, capability 체크리스트, 완료 기준, 범위 제외 항목 | -| `agent-ops/roadmap/archive/YYYY/MM/.md` | 완료 또는 폐기되어 현재 후보에서 제외한 과거 Milestone. 사용자가 명시적으로 요청한 경우에만 읽는다 | +| `agent-ops/roadmap/ROADMAP.md` | 전체 목표와 Phase 흐름만 담는 최상위 지도. 로드맵 생성/갱신/Phase 전환 때만 읽는다 | +| `agent-ops/roadmap/current.md` | 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 얇은 포인터 | +| `agent-ops/roadmap/phase//PHASE.md` | Phase 목표, 상태, Milestone 흐름, Phase 경계를 담는 문서 | +| `agent-ops/roadmap/phase//milestones/.md` | 일반 작업 시 읽는 Milestone 단위 목표, 구현 잠금, 범위, Epic/Task 체크리스트, 완료 기준, 범위 제외 항목 | +| `agent-ops/roadmap/archive/phase//...` | 완료 또는 폐기되어 현재 후보에서 제외한 과거 Phase/Milestone. 일반 작업에서는 읽지 않는다 | -## 로드맵 문서 템플릿 +## 템플릿 -- `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 요약, 로딩 정책만 담고, 상세 작업 체크리스트를 넣지 않는다. -- `current.md`는 활성 Milestone 후보 목록과 선택 규칙만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다. -- 아카이브된 과거 Milestone은 `ROADMAP.md`의 `아카이브 Milestone 요약`에 당시 요약만 남기며, 아카이브 문서 자체는 일반 컨텍스트로 읽지 않는다. +- `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` 형식을 따른다. +- `ROADMAP.md`에는 Milestone 상세 체크리스트를 넣지 않는다. +- `current.md`는 활성 Phase/Milestone 후보만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다. +- archive 경로는 `current.md`의 활성 항목에 넣지 않는다. -## Milestone 문서 템플릿 +## 작성 규칙 -- 새 Milestone 문서는 `agent-ops/skills/common/_templates/roadmap-milestone-template.md` 형식을 따른다. -- 섹션 순서는 `목표`, `단계`, `상태`, `구현 잠금`, `범위`, `필수 기능`, `완료 기준`, `범위 제외`, `작업 컨텍스트`를 유지한다. -- 새 Milestone은 제품 방향, 범위, 우선순위, 책임 경계 등 사용자만 결정할 수 있는 항목이 남아 있으면 `구현 잠금` 상태를 `잠금`으로 둔다. -- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다. -- `구현 잠금`에는 상태와 `결정 필요` 체크리스트만 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적고, 별도 해제 근거/금지 목록을 만들지 않는다. -- 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 처리 가능한 내용은 `결정 필요`에 넣지 않고, 필요할 때만 `작업 컨텍스트`의 `표준선`에 기록한다. -- `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 작성한다. 완료 근거가 명확한 항목만 `- [x]`로 표시한다. -- `필수 기능`의 각 체크리스트 항목은 `- [ ] [item-id] 설명` 형식을 사용한다. item-id는 사람이 타이핑하고 LLM이 참조하기 쉬운 공백 없는 짧은 ASCII 토큰으로 작성한다. -- item-id는 영문/숫자 segment 1~4개로 작성하고, segment 구분자는 `-`, `_`, `+`, `=`만 사용한다. 가능하면 1~3 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/.md`로 만든다. +- 기본 작성 언어는 한국어다. +- 상태 표기는 `[계획]`, `[진행중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다. +- Phase와 Milestone 이름, 파일명에는 `1`, `2`, `M01`, `P1` 같은 순번을 붙이지 않는다. +- 진행 순서는 `ROADMAP.md`와 각 `PHASE.md`의 위에서 아래 순서로 표현한다. +- Phase 파일명은 `agent-ops/roadmap/phase//PHASE.md`로 만든다. +- Milestone 파일명은 `agent-ops/roadmap/phase//milestones/.md`로 만든다. - 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다. -### current.md 형식 +## Milestone 작성 규칙 -`agent-ops/roadmap/current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 유지한다. - -`current.md`는 개인별 작업 위치가 아니라 현재 열어둘 Milestone 후보 목록이다. 실제 현 작업 지점과 남은 작업은 `analyze-roadmap-position` 스킬이 코드와 git 상태를 함께 읽고 분석한다. +- Milestone 표준 섹션은 `위치`, `목표`, `상태`, `구현 잠금`, `범위`, `필수 기능`, `완료 기준`, `범위 제외`, `작업 컨텍스트`다. +- 새 Milestone은 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `구현 잠금`을 `잠금`으로 둔다. +- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다. +- `구현 잠금`에는 상태와 `결정 필요` 체크리스트만 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적는다. +- `필수 기능`은 Epic heading과 Task 체크리스트로 작성한다. +- Epic heading은 `### Epic: [epic-id] <이름>` 형식으로 작성한다. +- Task는 `- [ ] [item-id] 설명` 형식으로 작성한다. +- epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 해당 Milestone 안에서만 유일하면 된다. +- `완료 기준`은 검증 가능한 조건의 체크리스트로 작성한다. +- `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다. ## 먼저 확인할 것 @@ -99,19 +94,14 @@ agent-ops/ - [ ] 이미 존재하면 덮어쓰지 말고 `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 형식 확인 +- [ ] `roadmap-template.md`, `roadmap-current-template.md`, `roadmap-phase-template.md`, `roadmap-milestone-template.md`를 읽어 최신 형식 확인 - [ ] `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와 프로젝트 규칙에서 대상 사용자, 해결하려는 문제, 현재 구현 상태를 파악한다. @@ -120,61 +110,23 @@ agent-ops/ 3. **목표 / Phase / Milestone 설계** - 전체 목표는 프로젝트가 궁극적으로 만들려는 결과를 1~3문장으로 작성한다. - - Phase는 큰 진화 단위로 나누고, 각 Phase에 목표를 둔다. + - Phase는 큰 진화 단위로 나누고, 각 Phase에 목표와 상태를 둔다. - Milestone은 Phase 안에서 완료 판단이 가능한 단위로 나눈다. - - Milestone은 기본적으로 구현 계획이 아니라 방향성과 완료 판단 기준을 공유하는 문서로 작성한다. - - package, 함수, DB schema, API 필드, 파일 구조 같은 구현 세부는 사용자가 별도 상세 설계를 요청하기 전까지 Milestone에 확정하지 않는다. - - 사용자만 결정할 수 있는 항목은 구현 세부로 확정하지 말고 `구현 잠금`의 `결정 필요` 체크리스트로 남긴다. - - 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 정할 수 있는 항목은 표준선으로 기록하고 사용자 결정 항목으로 올리지 않는다. - - Phase와 Milestone은 순번 없이 이름으로만 작성하고, 순서는 문서의 위에서 아래 흐름으로 표현한다. - - 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다. + - Milestone 내부에서 하위 작업 묶음이 필요하면 Epic으로 선언하고, Epic 아래 Task 체크리스트를 둔다. -4. **로드맵 파일 생성** - - `agent-ops/roadmap/ROADMAP.md`는 `roadmap-template.md`의 섹션 순서와 형식을 따른다. - - `agent-ops/roadmap/current.md`는 `roadmap-current-template.md`의 섹션 순서와 형식을 따른다. - - `ROADMAP.md`에는 전체 목표, Phase 흐름, Milestone 목록, 아카이브 Milestone 요약, 로딩 정책을 작성하고, 상세 작업 체크리스트는 Milestone 문서에 둔다. - - `current.md`에는 활성 Milestone 목록과 선택 규칙만 작성하고, 개인별 현재 작업 위치나 완료 상태는 적지 않는다. - - 새 로드맵의 `아카이브 Milestone 요약`은 아카이브된 항목이 없으면 `- 없음`으로 둔다. - - 각 Milestone 문서는 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따른다. - - 각 Milestone 문서에 `구현 잠금` 섹션을 포함한다. - - 사용자만 결정할 수 있는 항목이 있으면 `구현 잠금` 상태는 `잠금`으로 작성하고, 필요한 결정을 체크리스트로 적는다. - - Milestone 전체에서 사용자만 결정할 항목이 더 이상 없으면 `구현 잠금` 상태를 `해제`로 작성하고, `결정 필요`는 `없음`으로 둔다. - - `필수 기능`과 그 하위 항목은 capability 또는 산출물 수준의 `- [ ] [item-id] 설명` 체크리스트로 작성한다. - - 완료 근거가 확인된 항목만 `- [x]`로 표시하고, 근거가 없으면 체크하지 않는다. - - `완료 기준`도 검증 가능한 조건의 `- [ ]` 체크리스트로 작성한다. - - 미래 Milestone은 확정된 방향과 capability만 `필수 기능`에 넣는다. 사용자만 결정할 수 있는 불확실성은 `구현 잠금`의 `결정 필요` 체크리스트에 두고, 표준선이나 단순 조사/참고 TODO는 `작업 컨텍스트`에 둔다. +4. **파일 생성** + - `ROADMAP.md`, `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다. + - 활성 Phase와 활성 Milestone은 `current.md`에 모두 기록한다. + - `ROADMAP.md`의 Phase 흐름에는 완료/진행중/계획 Phase 모두를 위에서 아래 순서로 두고, 계획 Phase는 진행중 Phase보다 아래에 둔다. + - 완료된 Phase가 초기 구조에 포함되어야 하는 경우 `archive/phase//PHASE.md`로 만들고 `ROADMAP.md`에서 archive 경로를 가리킨다. + - 완료된 Milestone이 진행중 Phase에 포함되어야 하는 경우 `archive/phase//milestones/.md`로 만들고 해당 활성 `PHASE.md`에서 archive 경로를 가리킨다. + - archive `PHASE.md`는 Phase 자체가 완료/폐기된 경우에만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 둘 수 있다. -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 문서가 생성되었는가 -- [ ] `ROADMAP.md`에 `아카이브 Milestone 요약` 섹션이 있고, 아카이브된 항목이 없으면 `- 없음`으로 표시했는가 -- [ ] 각 Milestone 문서가 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따르는가 -- [ ] 각 Milestone 문서에 `구현 잠금` 섹션이 있고, 사용자만 결정할 수 있는 항목만 잠금 상태인가 -- [ ] 잠금 상태인 Milestone의 `구현 잠금` 섹션에 `결정 필요` 체크리스트가 있는가 -- [ ] 각 Milestone 문서의 `필수 기능`과 `완료 기준`이 체크리스트 형식인가 -- [ ] 각 Milestone 문서의 `필수 기능` 체크리스트 항목이 `- [ ] [item-id] 설명` 형식이고 item-id가 해당 Milestone 안에서 유일한가 -- [ ] `ROADMAP.md`에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가 -- [ ] 로딩 정책에 `agent-ops/roadmap/archive/**`를 명시 요청 없이 읽지 않는다는 규칙이 포함되었는가 -- [ ] 로딩 정책에 `구현 잠금`이 없거나 잠긴 Milestone의 현재 요청과 직접 관련된 `결정 필요` 체크리스트 확인 규칙이 포함되었는가 -- [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `rules-roadmap.md`를 읽도록 라우팅하는가 -- [ ] `agent-ops/rules/common/rules-roadmap.md`가 로드맵 컨텍스트 로딩과 구현 잠금 규칙을 포함하는가 -- 검증 실패 시: 누락된 파일이나 섹션만 보완하고 기존 내용을 덮어쓰지 않는다. +5. **검증** + - 생성한 링크가 실제 파일을 가리키는지 확인한다. + - `current.md` 활성 항목에 `agent-ops/roadmap/archive/**` 경로가 없는지 확인한다. + - Epic heading과 Task 체크리스트 id가 형식을 따르는지 확인한다. + - 상태 표기가 `[진행중]`처럼 공백 없는 표준값인지 확인한다. ## 출력 형식 @@ -183,14 +135,17 @@ agent-ops/ - 로드맵: agent-ops/roadmap/ROADMAP.md - 현재 컨텍스트: agent-ops/roadmap/current.md +- Phase 문서: - Milestone 문서: +- 활성 Phase: - 활성 Milestone: - 구현 잠금: <잠금 Milestone N개 | 해제 Milestone N개> - 공통 로드맵 룰: <확인함 | 설치 필요 | 해당 없음> -## 활성 Milestone +## 활성 항목 -- : agent-ops/roadmap/milestones/.md +- Phase: : agent-ops/roadmap/phase//PHASE.md +- Milestone: : agent-ops/roadmap/phase//milestones/.md ## TODO 항목 @@ -204,12 +159,7 @@ agent-ops/ - `current.md`에 `agent-ops/roadmap/archive/**` 경로를 넣지 않는다. - Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다. - `ROADMAP.md`에 Milestone 상세 작업 체크리스트를 넣지 않는다. -- `current.md`에 개인별 현재 작업 위치나 완료 상태를 적지 않는다. -- Milestone 문서를 단순 TODO 목록으로만 만들지 않는다. 반드시 템플릿의 목표, 단계, 상태, 구현 잠금, 범위, 필수 기능, 완료 기준, 범위 제외, 작업 컨텍스트를 포함한다. +- Epic과 Task를 별도 파일로 분리하지 않는다. - Milestone 문서에서 `구현 잠금` 섹션을 생략하지 않는다. - 사용자만 결정할 수 있는 항목이 남아 있는데 새 Milestone을 `해제` 상태로 만들지 않는다. -- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없는 Milestone을 관성적으로 `잠금` 상태로 만들지 않는다. -- Milestone을 구현 계획처럼 package/file/function 단위로 과도하게 세분화하지 않는다. -- 해야 할 capability 또는 산출물을 일반 불릿이나 설명 문장에 숨기지 않는다. `필수 기능` 또는 그 하위 항목의 item-id가 있는 체크리스트로 작성한다. - 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다. -- `agent-ops/rules/common/`이나 `agent-ops/skills/common/`을 타겟 프로젝트에서 직접 수정하지 않는다. diff --git a/agent-ops/skills/common/create-skill/SKILL.md b/agent-ops/skills/common/create-skill/SKILL.md index 07bb36c..ec895cb 100644 --- a/agent-ops/skills/common/create-skill/SKILL.md +++ b/agent-ops/skills/common/create-skill/SKILL.md @@ -12,6 +12,9 @@ description: 새로운 SKILL.md 파일을 생성하기 위한 범용 스킬 기존 skill-template.md 를 기반으로, 요청 목적에 맞는 내용을 채워 넣는다. 생성 후 라우팅 항목을 추가한다. +이 스킬은 프로젝트 내부 `agent-ops` 라우터가 읽는 스킬을 만든다. +`$CODEX_HOME/skills`에 설치되어 Codex가 직접 discover하는 스킬을 만들 때는 시스템 `skill-creator` 규칙을 우선하고, frontmatter는 `name`과 `description`만 사용한다. + ### 생성 위치 결정 - `.agent-ops-source` 파일이 **있으면** (공통 관리 레포): `agent-ops/skills/common//SKILL.md` - `.agent-ops-source` 파일이 **없으면** (타겟 프로젝트): `agent-ops/skills/project//SKILL.md` @@ -31,7 +34,7 @@ description: 새로운 SKILL.md 파일을 생성하기 위한 범용 스킬 ## 먼저 확인할 것 - [ ] `agent-ops/skills/common/` 및 `agent-ops/skills/project/` 하위에 동일 이름의 디렉터리가 이미 존재하는지 확인 -- [ ] `agent-ops/rules/common/rules.md` 및 `agent-ops/rules/project/rules.md` 에 이미 유사한 라우팅 항목이 있는지 확인 +- [ ] `agent-ops/skills/common/router.md` 및 `agent-ops/rules/project/rules.md` 에 이미 유사한 라우팅 항목이 있는지 확인 - [ ] `agent-ops/skills/common/_templates/skill-template.md` 를 읽어 최신 템플릿 형식 파악 ## 실행 절차 @@ -52,12 +55,14 @@ description: 새로운 SKILL.md 파일을 생성하기 위한 범용 스킬 3. **SKILL.md 생성** - 경로: 생성 위치 결정 규칙에 따라 `common/` 또는 `project/` 하위에 생성 - `skill-template.md` 형식을 따른다 + - agent-ops 내부 스킬은 기존 로컬 관례에 맞춰 `version`을 둘 수 있다. Codex 설치형 스킬로 배포할 목적이면 `version`이나 `depends` 같은 비표준 frontmatter를 넣지 않는다. - 프로젝트 특화 내용보다 범용 절차를 우선한다 - 절차는 구체적이되 지나치게 세부 구현을 기술하지 않는다 4. **라우팅 업데이트** - - `.agent-ops-source` 마커가 **있으면** (공통 관리 레포): `agent-ops/rules/common/rules.md`에 라우팅 항목 추가 + - `.agent-ops-source` 마커가 **있으면** (공통 관리 레포): `agent-ops/skills/common/router.md`에 라우팅 항목 추가 - `.agent-ops-source` 마커가 **없으면** (타겟 프로젝트): `agent-ops/rules/project/rules.md`의 프로젝트 스킬 라우터 섹션에 라우팅 항목 추가 + - 기존 공통 스킬을 수정해 trigger가 달라졌다면 새 skill을 만들지 말고 `agent-ops/skills/common/router.md`의 기존 행을 갱신한다 - 이 skill이 속할 라우팅 축(구조 분석/코드 변경/흐름 추적 등)을 판단한다 - 기존 라우팅 구조를 깨지 않는다 @@ -82,7 +87,8 @@ description: 새로운 SKILL.md 파일을 생성하기 위한 범용 스킬 - [ ] `agent-ops/skills/{common|project}//SKILL.md` 파일이 생성되었는가 - [ ] 생성된 파일이 `skill-template.md`의 필수 섹션(목적, 언제 호출할지, 실행 절차, 실행 결과 검증, 출력 형식, 금지 사항)을 포함하는가 -- [ ] frontmatter에 name, version, description이 올바르게 기재되었는가 +- [ ] frontmatter에 name, description이 올바르게 기재되었는가 +- [ ] agent-ops 내부 스킬이면 version 등 로컬 관례를 따르고, Codex 설치형 스킬이면 시스템 `skill-creator` frontmatter 규칙을 따르는가 - [ ] 라우팅 대상 파일에 해당 스킬의 라우팅 항목이 추가되었는가 - 검증 실패 시: 누락된 섹션 또는 라우팅 항목을 사용자에게 알리고 해당 부분만 보완한다 diff --git a/agent-ops/skills/common/init-agent-ops/SKILL.md b/agent-ops/skills/common/init-agent-ops/SKILL.md index 950428b..9f0003a 100644 --- a/agent-ops/skills/common/init-agent-ops/SKILL.md +++ b/agent-ops/skills/common/init-agent-ops/SKILL.md @@ -1,6 +1,6 @@ --- name: init-agent-ops -version: 1.1.2 +version: 1.1.3 description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드를 생성하기 위한 초기 규칙 --- @@ -71,8 +71,8 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 | `agent-ops/rules/project/domain//rules.md` | 도메인 분석 후 생성 | | `agent-ops/rules/private/` | 폴더만 생성 (내용은 개인이 작성) | | `.gitignore`에 `agent-ops/rules/private/` 추가 | git 추적 제외 | -| `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore` | `agent-task/archive/**`, `agent-ops/roadmap/archive/**` 한 줄씩 추가 | -| `.claude/settings.json`, `opencode.json` | 파일이 없으면 `agent-task/archive/**`, `agent-ops/roadmap/archive/**` 읽기/검색 제외 설정 생성, 있으면 구조적으로 병합하고 병합할 수 없을 때 수동 병합 안내 | +| `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore` | 사용자 항목은 보존하고 Agent-Ops 관리 block에 `agent-task/archive/**`, `agent-ops/roadmap/archive/**` 추가 | +| `.claude/settings.json`, `opencode.json` | 파일이 없으면 `agent-task/archive/**` 읽기/검색 제외 설정만 생성한다. `agent-ops/roadmap/archive/**`는 필요 시 링크로 읽을 수 있어야 하므로 hard read deny로 추가하지 않는다 | 에이전트별 파일명: @@ -177,8 +177,11 @@ common/rules.md와 내용이 중복되지 않도록 한다. - `rules/common/rules.md`를 `agent-ops/bin/entry-files.sh`의 파일 목록으로 프로젝트 루트에 복사한다 3. **AI ignore / permission 기본 설정** - - `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`를 추가한다 - - `.claude/settings.json`, `opencode.json`이 없으면 archive 읽기/검색 제외 설정을 생성하고, 있으면 가능한 경우 기존 설정을 보존하며 필요한 제외 설정만 병합한다 + - `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에는 사용자 항목을 건드리지 않고 Agent-Ops 관리 block만 추가하거나 교체한다 + - Agent-Ops 관리 block에는 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`를 넣는다 + - `.claude/settings.json`, `opencode.json`이 없으면 `agent-task/archive/**` 읽기/검색 제외 설정을 생성하고, 있으면 가능한 경우 기존 설정을 보존하며 필요한 제외 설정만 병합한다 + - `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않도록 AI ignore와 로드맵 규칙으로 제한하되, `.claude/settings.json`이나 `opencode.json`의 hard read deny에는 추가하지 않는다 + - 기존 `.claude/settings.json`이나 `opencode.json`에 `agent-ops/roadmap/archive/**` hard read/glob deny가 있으면 사용자 설정으로 보고 자동 삭제하지 않고 경고만 남긴다 - 대상 루트에 `.agent-ops-source`가 있으면 AI ignore / permission 파일은 보강하지 않는다 - `agent-task/archive/**`와 `agent-ops/roadmap/archive/**` 제외는 `.gitignore`에 추가하지 않는다 @@ -234,8 +237,10 @@ common/rules.md와 내용이 중복되지 않도록 한다. - [ ] 생성된 domain rules.md가 `domain-rule-template.md` 형식을 따르는가 - [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 생성된 도메인이 모두 등록되어 있는가 - [ ] `.gitignore`에 `agent-ops/rules/private/` 항목이 추가되어 있는가 -- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`가 포함되어 있는가 -- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**` 제외 설정이 있거나, 병합 불가 시 수동 병합 안내를 출력했는가 +- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`가 포함되어 있는가 +- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` 제외 설정이 있거나, 병합 불가 시 수동 병합 안내를 출력했는가 +- [ ] `.claude/settings.json`, `opencode.json`에 `agent-ops/roadmap/archive/**` hard read deny를 새로 추가하지 않았는가 +- [ ] 기존 `agent-ops/roadmap/archive/**` hard deny가 있으면 자동 삭제하지 않고 사용자 확인 대상으로 보고했는가 - [ ] `.gitignore`에 `agent-task/archive/**` 또는 `agent-ops/roadmap/archive/**`를 추가하지 않았는가 - 검증 실패 시: 누락된 파일/항목을 사용자에게 알리고 해당 부분만 보완한다 diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index d00a3e3..f027515 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -116,9 +116,12 @@ The routed plan file is the loop entry point. A missing active plan normally mea 로드맵 확인: -- `agent-ops/roadmap/current.md`가 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Milestone을 선택한다. -- `current.md`가 `agent-ops/roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 활성 Milestone이 아니라고 보고한다. -- 선택한 Milestone을 한 번 읽는다. `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인하고, 그 결정 없이는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, file/API/package 수준 구현 단계를 확정하지 않는다. +- `agent-ops/roadmap/current.md`가 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다. +- `current.md`가 `agent-ops/roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 활성 Phase/Milestone이 아니라고 보고한다. +- 선택한 Phase를 한 번 읽어 Phase 목표, Milestone 흐름, Phase 경계를 확인한다. +- 선택한 Milestone을 한 번 읽어 목표, 범위, 필수 기능, 완료 기준, 범위 제외, 구현 잠금을 확인한다. `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인하고, 그 결정 없이는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, file/API/package 수준 구현 단계를 확정하지 않는다. +- Phase 또는 Milestone 후보가 여럿이면 요청 문장, 변경 경로 직접성, Milestone 상태, 구현 잠금, 선후 의존성, Phase/Milestone 흐름상 위치를 기준으로 1순위와 2순위를 추천하고 필요한 후보 문서만 읽어 범위를 좁힌다. +- 로드맵 current가 있고 활성 Phase/Milestone 밖 작업이면 `ROADMAP.md`의 Phase 흐름을 확인하고 전환, 신규 Phase/Milestone, 또는 기존 활성 범위 내 배치 필요성을 보고한다. - 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조, 도메인 rule, 플랫폼 관례로 정할 수 있는 세부는 표준선/가정으로 계획에 기록하고 진행할 수 있다. - 사용자가 선택한 Milestone의 작업, 구현, 계획 작성을 명시했고 현재 계획에 필요한 결정이 모두 정해져 있다면 계획 작성을 이어간다. Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 roadmap update 흐름으로 `구현 잠금` 상태를 `해제`로 갱신한다. 현재 요청에 직접 걸리는 결정이 필요하면 그 항목만 체크리스트로 남기고 사용자에게 확인한다. - roadmap/current 파일이 없으면 기존 task routing 규칙대로 진행한다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index 8ad21f7..c6a65a6 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -7,7 +7,7 @@ | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` | | README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | -| 로드맵 업데이트, roadmap 갱신, 마일스톤 갱신, 마일스톤 아카이브, phase 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` | +| 로드맵 업데이트, roadmap 갱신, 로드맵에 추가, 로드맵 작업 추가, 로드맵 기능 추가, 로드맵 Epic 추가, 로드맵 에픽 추가, 로드맵 Task 추가, 로드맵 태스크 추가, 로드맵 테스크 추가, 로드맵 TODO 추가, 마일스톤에 추가, 마일스톤 추가, 마일스톤 갱신, 마일스톤 아카이브, phase 추가, phase 변경, 페이즈 추가, 페이즈 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` | | 지금 작업이 뭐지?, 현재 작업 분석, 어디까지 했지?, 남은 작업 뭐야 | `agent-ops/skills/common/analyze-roadmap-position/SKILL.md` | | 계획 세워줘, 계획 작성해, 계획 만들어줘, 구현 계획, PLAN.md, plan, plan 작성해, plan 만들어줘 | `agent-ops/skills/common/plan/SKILL.md` | | 코드 리뷰해줘, 리뷰 진행해, 리뷰해줘, code review, CODE_REVIEW.md, 리뷰 루프 | `agent-ops/skills/common/code-review/SKILL.md` | diff --git a/agent-ops/skills/common/sync-pull/SKILL.md b/agent-ops/skills/common/sync-pull/SKILL.md index 578068c..888a3a4 100644 --- a/agent-ops/skills/common/sync-pull/SKILL.md +++ b/agent-ops/skills/common/sync-pull/SKILL.md @@ -30,7 +30,9 @@ agent-ops/bin/sync.sh --pull - [ ] sync.sh 가 오류 없이 완료됐는가 - [ ] 현재 프로젝트 버전이 framework 버전과 일치하는가 - [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 갱신됐고, 내용이 framework의 `agent-ops/rules/common/rules.md`와 일치하는가 -- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`가 포함되어 있는가 +- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`가 포함되어 있는가 +- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` hard deny가 있고 `agent-ops/roadmap/archive/**` hard read deny를 새로 추가하지 않았는가 +- [ ] 현재 프로젝트에 기존 `agent-ops/roadmap/archive/**` hard deny가 있으면 자동 삭제하지 않고 사용자 확인 대상으로 보고했는가 - [ ] agentic-framework의 AI ignore / permission 파일은 수정되거나 stage되지 않았는가 ## 금지 사항 diff --git a/agent-ops/skills/common/sync-push/SKILL.md b/agent-ops/skills/common/sync-push/SKILL.md index 10dfc04..13f8005 100644 --- a/agent-ops/skills/common/sync-push/SKILL.md +++ b/agent-ops/skills/common/sync-push/SKILL.md @@ -44,7 +44,7 @@ description: 현재 프로젝트의 agent-ops를 agentic-framework로 올리거 4. target이 없으면 `sync.sh`가 현재 프로젝트 기준 상위 폴더(`../`)의 하위 디렉터리 중 `agent-ops/` 폴더가 있는 프로젝트를 모두 대상으로 삼는다 5. `sync.sh`는 현재 agentic-framework의 `agent-ops/rules/common/rules.md` 내용을 대상 프로젝트 루트의 진입 파일에 덮어쓴다 6. 적용 후 각 대상 repo에서 agent-ops 공통 관리 경로(`rules/common/rules.md` 포함), 진입 파일, AI ignore / permission 파일을 stage 하여 commit/push 한다 -7. AI ignore / permission 파일은 대상 프로젝트의 기존 내용을 덮어쓰지 않고, 누락된 표준 archive 제외 설정만 보강한다 +7. AI ignore / permission 파일은 대상 프로젝트의 기존 내용을 덮어쓰지 않고, Agent-Ops 관리 block 또는 Agent-Ops 전용 permission key만 보강한다 8. 이 과정에서는 버전을 새로 올리지 않고 현재 agentic-framework의 `agent-ops/.version` 값을 그대로 대상 프로젝트에 반영한다 덮어쓰기 대상은 `init-agent-ops` 초기 세팅과 동일하며, 실제 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용한다. @@ -59,6 +59,25 @@ description: 현재 프로젝트의 agent-ops를 agentic-framework로 올리거 대상 프로젝트에 기존 진입 파일이 있어도 보존하거나 병합하지 않고 `agent-ops/rules/common/rules.md` 내용으로 교체한다. +## AI Ignore / Permission 재적용 + +- 이 절차는 agentic-framework 원본 프로젝트에서 대상 프로젝트로 push할 때와 `--pull`로 agentic-framework에서 현재 프로젝트로 내려받을 때만 적용한다. +- 일반 프로젝트에서 agentic-framework로 올리는 push에서는 AI ignore / permission 파일을 수정하거나 stage하지 않는다. +- `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`는 사용자 영역을 수정하지 않고 아래 관리 block만 추가하거나 교체한다. + +```text +# BEGIN Agent-Ops managed ignore +agent-task/archive/** +agent-ops/roadmap/archive/** +# END Agent-Ops managed ignore +``` + +- 관리 block 밖의 기존 ignore 항목은 사용자 소유로 보고 삭제, 정렬, 중복 제거하지 않는다. +- `.claude/settings.json`과 `opencode.json`은 기존 사용자 설정을 보존하고 `agent-task/archive/**` hard read/glob deny만 보강한다. +- `agent-ops/roadmap/archive/**`는 필요한 경우 링크로 읽을 수 있어야 하므로 `.claude/settings.json`이나 `opencode.json`의 hard read deny로 새로 추가하지 않는다. +- 대상 프로젝트에 기존 `agent-ops/roadmap/archive/**` hard read/glob deny가 있으면 사용자 설정으로 보고 자동 삭제하지 않고 경고만 남긴다. +- `opencode.json`의 watcher ignore에는 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`를 둘 수 있다. + ```bash agent-ops/bin/sync.sh [target] ``` @@ -71,7 +90,9 @@ agent-ops/bin/sync.sh [target] - [ ] 버전 충돌 경고가 없었는가 — 있었다면 사용자에게 수동 머지 필요함을 알린다 - [ ] 대상 repo의 `agent-ops/rules/common/rules.md`가 현재 agentic-framework의 `agent-ops/rules/common/rules.md`와 일치하는가 - [ ] agentic-framework에서 대상 프로젝트로 push한 경우, `agent-ops/bin/entry-files.sh`의 모든 진입 파일 내용이 현재 agentic-framework의 `agent-ops/rules/common/rules.md`와 일치하는가 -- [ ] framework에서 대상 프로젝트로 push한 경우, `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`가 포함되어 있는가 +- [ ] framework에서 대상 프로젝트로 push한 경우, `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`가 포함되어 있는가 +- [ ] framework에서 대상 프로젝트로 push한 경우, `.claude/settings.json`과 `opencode.json`에 `agent-task/archive/**` hard deny가 있고 `agent-ops/roadmap/archive/**` hard read deny를 새로 추가하지 않았는가 +- [ ] 대상 프로젝트에 기존 `agent-ops/roadmap/archive/**` hard deny가 있으면 자동 삭제하지 않고 사용자 확인 대상으로 보고했는가 - [ ] 일반 프로젝트에서 agentic-framework로 push한 경우, AI ignore / permission 파일이 agentic-framework에 유입되지 않았는가 - [ ] 대상 repo에 commit/push 된 path가 방향별 허용 범위로 제한되었는가 diff --git a/agent-ops/skills/common/update-roadmap/SKILL.md b/agent-ops/skills/common/update-roadmap/SKILL.md index 529fd1a..d50584c 100644 --- a/agent-ops/skills/common/update-roadmap/SKILL.md +++ b/agent-ops/skills/common/update-roadmap/SKILL.md @@ -1,329 +1,272 @@ --- name: update-roadmap -version: 1.12.0 -description: 기존 전체 목표, Phase, 결정 필요 체크리스트 기반 구현 잠금이 있는 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 신규 작업 배치, current.md 동기화, 완료/폐기 Milestone 아카이빙을 처리하는 공통 스킬 +version: 1.16.0 +description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 current.md 동기화와 archive 이동을 처리한다. --- # 로드맵 업데이트 ## 목적 -기존 `agent-ops/roadmap/` 구조를 현재 프로젝트 방향과 진행 상태에 맞게 한국어로 갱신한다. -로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, `current.md`의 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다. +기존 `agent-ops/roadmap/` 구조를 현재 프로젝트 방향과 진행 상태에 맞게 갱신한다. +표준 구조는 `ROADMAP.md -> phase//PHASE.md -> phase//milestones/.md`다. +archive도 같은 Phase scaffold를 유지하며 `archive/phase//...` 아래에 둔다. +로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, `current.md`의 활성 Phase와 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다. + Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서로 유지한다. -구현 잠금은 승인 절차가 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다. -제품 방향, 범위, 우선순위, 책임 경계처럼 사용자만 결정할 수 있는 항목이 남아 있으면 `잠금`으로 두고 `결정 필요` 체크리스트에 질문을 적는다. -기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 `결정 필요`가 아니라 필요 시 표준선으로 기록한다. -Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다. -잠금 상태 변경은 Milestone 완료 판정이 아니므로 `필수 기능`과 `완료 기준`을 자동 완료 처리하지 않는다. -완료 또는 폐기되어 현재 작업 후보에서 제외할 과거 Milestone은 `agent-ops/roadmap/archive/YYYY/MM/`로 이동하고, `ROADMAP.md`에는 아카이빙 당시 요약만 남긴다. -아카이브된 Milestone은 최신 스킬 규약이나 템플릿에 맞춰 재포맷하지 않고, 사용자가 명시적으로 과거 기록 확인이나 복원을 요청한 경우에만 읽는다. +Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `필수 기능` 안에서 관리한다. ## 언제 호출할지 - 사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 활성 마일스톤 바꿔줘"라고 요청할 때 -- 사용자가 "로드맵 한국어 전환", "로드맵 번역", "영문 로드맵을 한국어로 바꿔줘"라고 요청할 때 +- 사용자가 "로드맵에 추가", "로드맵 작업 추가", "로드맵 기능 추가", "로드맵 Epic/Task 추가", "로드맵 에픽/태스크 추가", "마일스톤에 추가", "마일스톤 추가"처럼 로드맵에 새 내용을 넣어 달라고 요청할 때 - Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때 -- 완료 또는 폐기된 Milestone을 요약하고 archive로 이동해야 할 때 -- 특정 기능이나 작업을 새 Milestone, 기존 Milestone의 태스크, 기존 태스크 하위 항목 중 적절한 위치에 추가해야 할 때 -- 활성 Milestone 창에 포함할 Milestone 목록이 달라졌을 때 -- 기본 목표, Phase, Milestone의 목표, 범위, 필수 기능, 완료 기준이 달라졌을 때 -- `ROADMAP.md` 또는 `current.md` 형식이 템플릿과 달라 표준화해야 할 때 -- Milestone 문서 형식이 제각각이라 템플릿 기준으로 표준화해야 할 때 -- 실제 구현 상태와 로드맵 파일이 어긋난 것 같아 동기화가 필요할 때 -- 사용자가 Milestone의 방향/범위 보완, 구현 잠금 해제, 또는 잠금 상태 점검을 요청할 때 +- Phase 완료, 보류, 폐기, 신규 추가가 필요할 때 +- 완료 또는 폐기된 Phase/Milestone을 archive로 이동해야 할 때 +- 특정 기능이나 작업을 새 Milestone, 기존 Milestone의 Epic, 기존 Epic의 Task 중 적절한 위치에 추가해야 할 때 +- 활성 Phase/Milestone 창에 포함할 목록이 달라졌을 때 +- 기존 로드맵을 `phase//PHASE.md` scaffold로 마이그레이션하거나 표준화해야 할 때 ## 입력 - `mode`: `status` / `milestone` / `phase` / `replan` / `sync` / `concretize` / `archive` 중 하나 (선택, 요청에서 추론 가능) +- `target-phase`: 갱신할 Phase 이름, slug, 파일 경로 (선택) - `target-milestone`: 갱신할 Milestone 이름, slug, 파일 경로 (선택) +- `active-phases`: 활성 Phase 창에 둘 Phase 이름, slug, 파일 경로 목록 (선택) - `active-milestones`: 활성 Milestone 창에 둘 Milestone 이름, slug, 파일 경로 목록 (선택) - `new-feature`: 추가할 기능, 작업, 또는 새 Milestone 설명 (선택) -- `placement`: 새 작업 배치 위치. 예: ` 앞`, ` 뒤`, ` 안`, ` 안`, ` 앞`, ` 아래`, `auto` (선택, 없으면 자동 판단) -- `placement-unit`: 삽입 단위. `milestone` / `task` / `subtask` / `auto` 중 하나 (선택, 없으면 작업 성격으로 판단) -- `lock-state`: Milestone 구현 잠금 상태. `잠금` / `해제` 중 하나 (선택, 없으면 기존 상태 유지 또는 결정 필요 여부로 판단) +- `placement`: 새 작업 배치 위치. 예: ` 안`, ` 안`, ` 아래`, ` 앞`, ` 뒤`, `auto` (선택) +- `placement-unit`: 삽입 단위. `phase` / `milestone` / `epic` / `task` / `subtask` / `auto` 중 하나 (선택) +- `lock-state`: Milestone 구현 잠금 상태. `잠금` / `해제` 중 하나 (선택) - `decision-needed`: `구현 잠금`에 남길 사용자만 결정할 수 있는 질문 목록 (선택) -- `unlock-evidence`: 이전 문서 호환 입력. 새 문서에서는 별도 해제 근거 대신 필요한 사용자 결정이 남아 있는지로 상태를 판단한다 (선택) -- `concretization-evidence`: 이전 문서 호환 입력. 새 문서에서는 `decision-needed`를 우선 사용한다 (선택) -- `change-summary`: 반영할 방향 변경 또는 진행 상황 요약 (선택) - `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택) -- `archive-date`: Milestone 아카이브 날짜. 없으면 현재 날짜를 사용한다 (선택) -- `archive-summary`: `ROADMAP.md`에 남길 과거 Milestone 요약. 없으면 대상 Milestone 문서와 evidence에서 1~2문장으로 추출한다 (선택) +- `archive-date`: Phase/Milestone 아카이브 날짜. 없으면 현재 날짜를 사용한다 (선택) -## 모드 +## 표준 구조 -| mode | 사용 상황 | -|------|-----------| -| `status` | 태스크 체크박스, Milestone 상태, 완료 기준만 갱신 | -| `milestone` | Milestone 목표, 범위, 태스크 체크리스트, 완료 기준 수정 | -| `phase` | Phase 설명 또는 활성 Milestone 창 전환 | -| `replan` | 전체 Phase/Milestone 흐름 재구성 | -| `sync` | 실제 프로젝트 상태와 로드맵 불일치 점검 후 보정 | -| `concretize` | Milestone의 방향/범위를 보완하거나 결정 필요 여부에 따라 잠금 상태를 갱신 | -| `archive` | 완료 또는 폐기된 Milestone을 요약하고 `agent-ops/roadmap/archive/YYYY/MM/`로 이동 | +```text +agent-ops/roadmap/ + ROADMAP.md + current.md + phase/ + / + PHASE.md + milestones/ + .md + archive/ + phase/ + / + PHASE.md + milestones/ + .md +``` -## 작성 언어 +- `ROADMAP.md`는 전체 목표와 Phase 흐름만 담는다. +- `PHASE.md`는 해당 Phase의 목표, 상태, Milestone 흐름, Phase 경계를 담는다. +- Milestone 문서는 해당 Phase 하위 `milestones/`에 둔다. +- 완료된 Phase는 `archive/phase//PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다. +- 진행중 Phase 안에서 완료된 Milestone은 `archive/phase//milestones/.md`로 이동하고, 활성 `PHASE.md`에는 짧은 archive 링크를 남긴다. +- archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우에는 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. +- `current.md`는 활성 Phase와 활성 Milestone을 모두 가리킨다. +- `current.md`에는 archive 경로를 넣지 않는다. -- `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` -> `작업 컨텍스트` +## 상태와 id -## 로드맵 문서 템플릿 +- 상태 표기는 `[계획]`, `[진행중]`, `[완료]`, `[보류]`, `[폐기]` 중 하나만 사용한다. +- 기존 비표준 상태 표기는 갱신 범위에 포함될 때 표준 상태 표기로 정리한다. +- `ROADMAP.md`의 Phase 흐름과 `PHASE.md`의 Milestone 흐름은 완료, 진행중, 계획 순서를 기본으로 하며 아래로 갈수록 미래 작업에 가까워지게 정렬한다. +- Epic heading은 `### Epic: [epic-id] <이름>` 형식으로 작성한다. +- Task는 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 형식으로 작성한다. +- epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 해당 Milestone 안에서만 유일하면 된다. +- 사용자가 epic-id 또는 item-id를 언급하면 해당 항목을 우선 anchor로 삼고, 기존 id는 명시적 요청 없이 바꾸지 않는다. -- `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 문서 템플릿 +- 일반 갱신은 `current.md`, 관련 활성 Phase, 관련 활성 Milestone을 우선 읽는다. +- `ROADMAP.md`는 Phase 흐름, 전체 구조, 활성 범위 밖 작업, 전체 재계획, archive 링크 갱신이 필요할 때 읽는다. +- `agent-ops/roadmap/archive/**`는 일반 작업이나 sync에서 읽지 않는다. +- archive 모드에서 이동 대상이 아직 활성 경로에 있으면 그 대상 문서는 읽을 수 있다. +- 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 요청이면 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라 필요한 archive 문서만 읽는다. -- Milestone 문서는 `agent-ops/skills/common/_templates/roadmap-milestone-template.md` 형식을 기준으로 생성·갱신한다. -- 표준 섹션 순서는 `목표`, `단계`, `상태`, `구현 잠금`, `범위`, `필수 기능`, `완료 기준`, `범위 제외`, `작업 컨텍스트`다. -- 갱신 범위에 포함된 Milestone 문서가 제각각 형식이면, 내용을 삭제하지 말고 표준 섹션 순서로 재배치한다. -- 기존 Milestone에 `구현 잠금` 섹션이 없으면 추가하고, 사용자만 결정할 수 있는 항목이 남아 있는지 보고 `잠금` 또는 `해제`를 정한다. -- `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. -- `구현 잠금`은 사용자만 결정할 수 있는 항목이 있으면 `잠금`, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되면 `해제`로 둔다. -- `구현 잠금`에는 상태와 `결정 필요` 체크리스트만 유지한다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적고, 별도 해제 근거/금지 목록은 만들지 않는다. -- 기존 Milestone 문서에 `이유`, `해제 근거`, `잠금 중 금지`, 잠금 해제를 위한 별도 체크리스트가 있으면 사용자만 결정할 수 있는 질문만 `결정 필요` 체크리스트로 옮기고, 표준선이나 배경 설명은 `작업 컨텍스트`로 옮기거나 제거한다. -- `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 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 아카이브 정책 +- `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` -- 활성 또는 예정 Milestone 문서는 `agent-ops/roadmap/milestones/.md`에 둔다. -- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Milestone은 `agent-ops/roadmap/archive/YYYY/MM/.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/.md`로 만든다. -- 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다. -- 기존 프로젝트에 이미 순번 파일명이 있으면 대규모 rename을 하지 말고, 갱신 범위에 포함된 새 항목부터 순번 없는 형식을 적용한다. -- 새 작업은 습관적으로 새 Milestone으로 만들거나 목록 맨 앞/뒤에 붙이지 않는다. -- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 기존 태스크 item-id, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다. -- 사용자가 위치를 지정하지 않으면 `ROADMAP.md`의 Phase 흐름, 기존 Milestone 목표, 기존 필수 기능/태스크, 선후 의존성, 활성 Milestone 창, 완료 기준을 보고 가장 자연스러운 위치를 자동으로 판단한다. -- 자동 배치한 경우 결과 보고에 선택한 삽입 단위, Phase/Milestone/태스크 위치, 판단 근거를 짧게 남긴다. +- `구현 잠금`은 승인 절차가 아니라 사용자 결정이 필요한지 표시하는 얇은 상태다. +- 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `잠금`으로 두고 `결정 필요` 체크리스트에 질문을 적는다. +- 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 `결정 필요`가 아니라 `작업 컨텍스트`의 표준선으로 기록한다. +- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다. +- 잠금 상태 변경은 Milestone 완료 판정이 아니므로 `필수 기능`과 `완료 기준`을 자동 완료 처리하지 않는다. ## 삽입 단위 정책 -신규 추가 요청은 먼저 "어디에 둘지"와 "어떤 단위로 둘지"를 분리해서 판단한다. 여기서 태스크는 Milestone 문서 `필수 기능` 섹션의 체크리스트 항목 또는 기존 체크리스트 항목을 뜻한다. - | 삽입 단위 | 사용 기준 | |-----------|-----------| -| 새 Milestone | 독립적인 목표와 완료 기준이 필요하거나, 여러 기능을 묶는 산출물이고, 별도 상태 추적이 필요하며, Phase 흐름이나 선후 의존성에 의미 있는 경계를 만든다 | -| 기존 Milestone의 태스크 | 기존 Milestone의 목표와 범위 안에 들어가며, 하나의 완료 가능한 capability/산출물이지만 별도 Milestone 상태 추적까지는 필요하지 않다 | -| 기존 태스크의 하위 작업 | 기존 태스크의 구현 세부, 보완, 테스트, 문서화, 예외 처리, 완료 기준 보완처럼 부모 태스크를 완성하기 위한 세부 항목이다. 잠긴 Milestone이어도 현재 작업에 직접 영향을 주는 사용자 결정이 없고 표준선으로 처리 가능하면 사용할 수 있다 | -| 작업 컨텍스트/TODO | 사용자 결정이 아니라 조사/확인이 먼저 필요해 필수 기능으로 확정하기 어렵다 | +| 새 Phase | 독립적인 제품 진화 단계와 여러 Milestone 묶음이 필요하다 | +| 새 Milestone | 독립적인 목표와 완료 기준이 필요하고 Phase 흐름에 의미 있는 경계를 만든다 | +| 새 Epic | 기존 Milestone 안에서 여러 Task를 묶는 상위 capability 또는 산출물이다 | +| 새 Task | 기존 Epic 아래에 들어가는 완료 가능한 capability, 산출물, 검증 항목이다 | +| 하위 작업 | 기존 Task를 완성하기 위한 구현 세부, 테스트, 문서화, 예외 처리다 | +| 작업 컨텍스트/TODO | 사용자 결정 또는 조사/확인이 먼저 필요해 필수 기능으로 확정하기 어렵다 | -- 신규 Milestone은 사용자만 결정할 수 있는 항목이 있으면 `구현 잠금: 잠금`, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없으면 `구현 잠금: 해제`로 생성한다. -- 잠긴 Milestone 안에 새 작업을 추가할 때 현재 요청에 직접 걸리는 사용자 결정은 `결정 필요` 체크리스트로 옮기고, 표준선으로 처리 가능한 세부 작업은 관련 `필수 기능` 항목의 하위 작업이나 `작업 컨텍스트`로 배치한다. -- `구현 잠금`이 없거나 잠긴 Milestone에 대해 사용자가 작업, 구현, 계획 작성을 명시하면 현재 요청에 직접 영향을 주는 결정 필요 항목이 남아 있는지 먼저 판단한다. 남은 결정이 없으면 잠금을 유지하더라도 표준선으로 요청한 작업을 이어갈 수 있고, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 상태를 `해제`로 갱신한다. -- 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다. ` 아래`처럼 하위 위치가 명시되면 기존 태스크 하위 항목으로 넣고, ` 앞/뒤`면 같은 목록 레벨의 형제 항목으로 넣는다. -- 사용자가 item-id를 언급하면 해당 Milestone의 `필수 기능` 체크리스트에서 정확히 일치하는 item-id를 우선 매칭한다. 중복되거나 없으면 임의로 고르지 말고 확인한다. -- 여러 Milestone 후보에서 같은 item-id가 발견되면 item-id만으로 확정하지 말고 Milestone 이름이나 문서 경로를 확인한다. -- 위치는 지정됐지만 단위가 명시되지 않은 경우, anchor 레벨과 작업 성격을 함께 보고 새 Milestone, 태스크, 하위 작업 중 하나를 선택한다. -- 위치 지정이 ` 안` 또는 ` 안`처럼 컨테이너만 지정된 경우, 해제된 Milestone에서 작업 내용이 기존 태스크의 세부 구현이면 해당 컨테이너 안에서 가장 관련 있는 태스크 아래에 넣을 수 있다. 이 경우 결과 보고에 "위치는 지정된 컨테이너를 따랐고, 단위는 하위 작업으로 판단"처럼 남긴다. -- 위치 지정이 ` 앞/뒤` 또는 ` 앞/뒤`처럼 순서 anchor인 경우, 같은 레벨의 앞/뒤 배치를 유지한다. 작업 성격상 다른 레벨이 더 적절해 보여도 조용히 재배치하지 말고 사용자에게 확인한다. -- `placement-unit`을 사용자가 명시한 경우 그 단위를 우선한다. 다만 지정 단위가 anchor 레벨, Milestone 목표, 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다. -- 작업이 둘 이상의 Milestone에 걸치면 바로 하나의 기존 태스크에 넣지 않는다. 공통 기반 작업이면 새 Milestone을 고려하고, 단순 연계 작업이면 각 Milestone에 나눌지 사용자에게 확인한다. -- 기존 태스크와 중복되거나 기존 태스크의 완료 기준으로 자연스럽게 흡수되는 요청은 새 Milestone이나 새 형제 태스크로 만들지 말고 기존 태스크를 보완한다. +- 먼저 요청 내용의 규모를 판정한다. 배치 위치를 찾기 전에 `phase`, `milestone`, `epic`, `task`, `subtask`, `context` 중 가장 작은 충분한 단위를 고른다. +- 가장 작은 충분한 단위 원칙을 따른다. 애매하면 새 Phase나 새 Milestone으로 키우지 말고, 기존 Milestone의 Epic/Task에 넣을 수 있는지 먼저 확인한다. +- 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다. +- ` 아래`는 해당 Epic 아래 Task로 넣는다. +- ` 앞/뒤`는 같은 Epic 안의 형제 Task로 넣는다. +- ` 아래`는 해당 Task의 하위 작업으로 넣는다. +- ` 안`은 새 Milestone 또는 기존 Milestone/Epic/Task 중 작업 성격에 맞는 단위로 배치한다. +- 위치 지정이 없으면 `auto`로 본다. `current.md`의 활성 창만으로 결정하지 않고, 필요한 경우 `ROADMAP.md`의 Phase 흐름까지 확인해 완료/진행중/계획 Phase를 비교한다. +- target 없는 신규 추가 요청은 요청 문장, 관련 파일/도메인 힌트, Phase 목표, Milestone 목표, 기존 Epic/Task, 선후 의존성, 상태, 활성 창을 비교해 가장 자연스러운 위치를 자동 판단한다. +- 자동 배치 후보가 여러 개이면 1순위와 2순위 후보를 비교하고, 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 짧게 남긴다. +- 관련성이 비슷하면 `[진행중]` Milestone을 `[계획]` Milestone보다 우선하되, 요청 내용이 계획 Phase/Milestone 목표에 더 직접 연결되면 계획 항목에 배치할 수 있다. +- 자동 배치한 경우 결과 보고에 선택한 삽입 단위, 위치, 판단 근거, 비교한 후보를 짧게 남긴다. +- 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 선후 의존성과 충돌하면 수정 전에 사용자에게 확인한다. -### current.md 형식 +## 레벨별 탐색과 upsert 정책 -`agent-ops/roadmap/current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 유지한다. +target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다. -`current.md`는 개인별 작업 위치나 완료 상태의 진실이 아니다. 현재 열려 있는 Milestone 후보 목록이며, 실제 현 작업 지점과 남은 작업은 `analyze-roadmap-position` 스킬이 코드와 git 상태를 함께 읽고 분석한다. +1. **요청 정규화** + - 요청 문장에서 기능명, 목표, 산출물, 관련 경로/도메인, 완료 기대, 제약, 명시 anchor를 뽑는다. + - 사용자가 Phase/Milestone/Epic/Task/id/path를 명시했으면 그 anchor를 우선 후보로 둔다. -## 먼저 확인할 것 +2. **규모 판정** + - 여러 Milestone을 묶는 제품/운영 단계면 Phase 규모다. + - 독립 목표, 별도 완료 기준, 여러 Epic이 필요한 결과면 Milestone 규모다. + - 한 Milestone 안의 capability 묶음이면 Epic 규모다. + - Epic 아래에서 완료 가능한 단일 capability, 산출물, 검증 항목이면 Task 규모다. + - Task를 완성하기 위한 구현 세부면 subtask 규모다. + - 조사, 결정, 보류 질문이면 작업 컨텍스트/TODO 규모다. -- [ ] `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 전체에서 사용자만 결정할 항목이 더 이상 없으면 `구현 잠금`을 `해제`로 두고, 현재 요청과 직접 관련 없더라도 사용자 결정 항목이 남아 있으면 `잠금` 상태와 체크리스트를 유지한다. +3. **레벨별 탐색** + - Phase 후보를 먼저 찾는다. `current.md`의 활성 Phase를 우선 보되, target이 없거나 활성 범위 밖 가능성이 있으면 `ROADMAP.md`의 Phase 흐름도 본다. + - 선택한 Phase 안에서 Milestone 후보를 찾는다. 활성 Milestone을 우선 보되, 요청이 계획 Milestone 목표와 더 직접 맞으면 계획 Milestone도 후보로 둔다. + - 선택한 Milestone 안에서 Epic 후보를 찾는다. `필수 기능`의 Epic heading, 목표 설명, Task 묶음을 비교한다. + - 선택한 Epic 안에서 Task 후보를 찾는다. item-id, 문장 의미, 완료 기준, 관련 경로를 비교한다. + - archive 문서는 기본 탐색 대상이 아니다. 사용자가 과거 기록 비교를 명시했거나 완료 내용 확인이 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라 필요한 문서만 읽는다. + +4. **중복/업데이트 판정** + - 같은 id, 같은 제목, 같은 목표, 같은 관련 경로, 같은 완료 기준, 또는 같은 산출물을 다루면 동일/유사 후보로 본다. + - 동일 항목이면 새로 만들지 않고 기존 Phase/Milestone/Epic/Task를 업데이트한다. + - 기존 항목의 범위를 보강하는 내용이면 해당 항목의 설명, Task, 완료 기준, 작업 컨텍스트 중 알맞은 곳에 병합한다. + - 기존 항목과 충돌하거나 범위 제외를 건드리면 수정 전에 사용자에게 확인한다. + - 같은 레벨에 적절한 후보가 없을 때만 새 항목을 만든다. 새 항목도 판정한 규모보다 크게 만들지 않는다. + - 부모 레벨 후보는 있고 판정 규모의 항목만 없으면, 부모 아래에 판정 규모의 새 항목을 만든다. 부모 레벨도 없을 때만 필요한 부모 항목을 함께 만든다. + +## archive 정책 + +### Milestone archive + +- 대상 Milestone이 `[완료]` 또는 `[폐기]`인지, 또는 그렇게 바꿀 근거가 있는지 확인한다. +- 대상 파일을 `agent-ops/roadmap/phase//milestones/.md`에서 `agent-ops/roadmap/archive/phase//milestones/.md`로 이동한다. +- 활성 `PHASE.md`의 Milestone 흐름에는 `[완료]` 또는 `[폐기]` 항목을 남기고, 경로는 archive 경로로 바꾼다. +- `current.md`의 활성 Milestone에서는 제거한다. +- `ROADMAP.md`는 Phase 상태나 경로가 바뀌지 않으면 수정하지 않는다. +- 이동한 archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다. + +### Phase archive + +- Phase 전체가 `[완료]` 또는 `[폐기]`인지, 또는 그렇게 바꿀 근거가 있는지 확인한다. +- `agent-ops/roadmap/phase//PHASE.md`를 `agent-ops/roadmap/archive/phase//PHASE.md`로 이동한다. +- 해당 Phase의 하위 Milestone도 `archive/phase//milestones/` 아래로 이동한다. +- `ROADMAP.md`의 Phase 흐름에는 해당 Phase 항목을 남기고, 상태와 경로를 archive `PHASE.md`로 바꾼다. +- `current.md`의 활성 Phase와 활성 Milestone에서는 해당 Phase와 하위 Milestone을 제거한다. +- archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다. ## 실행 절차 1. **갱신 범위 결정** - - 요청에서 mode, target Milestone, new feature, placement, placement-unit을 추론한다. - - 요청이 Milestone 방향/범위 보완, 잠금 해제, 결정 필요 항목 정리, 또는 잠긴 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 문서를 읽지 않는다. + - 요청에서 mode, 대상 Phase/Milestone, placement, placement-unit을 추론한다. + - 구조 전환, 템플릿 보정, current 동기화는 `sync`로 본다. + - 완료/폐기 이동은 `archive`로 본다. + - 새 기능 배치, Epic/Task 추가는 `milestone` 또는 `phase`로 본다. + - "로드맵에 추가"처럼 target이 없는 신규 작업 요청은 `placement=auto`, `placement-unit=auto`, `new-feature=<요청 내용>`으로 본다. -2. **현재 로드맵 상태 파악** - - `ROADMAP.md`의 전체 목표, Phase 흐름, Milestone 목록, 아카이브 Milestone 요약을 확인한다. - - `current.md`의 활성 Milestone 창과 선택 규칙을 확인한다. - - `current.md`에 아카이브 경로가 있으면 해당 항목을 읽지 말고 제거 대상으로 기록한다. - - `ROADMAP.md`와 `current.md`가 표준 템플릿 섹션 순서와 형식을 따르는지 확인한다. - - 대상 또는 후보 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 범위 제외 항목을 확인한다. - - 대상 또는 후보 Milestone 문서의 `구현 잠금` 상태와 `결정 필요` 항목을 확인한다. - - `구현 잠금`이 없거나 잠긴 Milestone에 대한 작업, 구현, 구현 계획 요청이면 현재 요청에 직접 영향을 주는 사용자 결정이 남아 있는지 판단한다. 남은 결정이 없으면 잠금을 유지하더라도 표준선으로 요청한 작업을 이어갈 수 있고, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없는 경우에만 `구현 잠금` 상태를 `해제`로 갱신한다. - - 대상 Milestone 문서가 표준 템플릿 섹션 순서와 체크리스트 형식을 따르는지 확인한다. - - 대상 Milestone 문서의 `필수 기능` item-id 목록을 확인하고, 중복 또는 누락이 갱신 범위에 있으면 보정 대상으로 기록한다. - - 신규 작업과 이름, 산출물, 코드 경계, 완료 기준이 겹치는 기존 태스크가 있는지 확인한다. +2. **요청 정규화와 규모 판정** + - 요청에서 기능명, 목표, 관련 경로, 명시 anchor, 완료 기대, 제약을 추출한다. + - `phase`, `milestone`, `epic`, `task`, `subtask`, `context` 중 가장 작은 충분한 규모를 판정한다. + - 동일/유사 항목이 이미 있으면 신규 추가가 아니라 업데이트 후보로 기록한다. -3. **신규 작업 삽입 단위와 위치 판단** - - 추가 요청이면 placement, placement-unit, 작업 성격을 함께 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업, 작업 컨텍스트/TODO 중 어느 단위가 맞는지 결정한다. - - 사용자가 위치를 지정한 경우 `ROADMAP.md`에서 anchor Phase/Milestone을 확인하고, 필요한 경우 대상 Milestone 문서의 태스크 anchor까지 확인해 충돌 여부를 확인한다. - - 지정된 anchor가 없거나 여러 항목과 매칭되어 모호하면 임의 배치하지 말고 사용자에게 짧게 확인한다. - - 사용자가 순서 anchor를 지정했으면 같은 레벨의 앞/뒤 배치를 유지하고, 컨테이너 anchor를 지정했으면 컨테이너 안에서 작업 성격에 맞는 하위 단위를 선택한다. - - 위치 지정이 없으면 `ROADMAP.md`의 위아래 흐름, 현재 활성 Milestone, 선행되어야 할 작업, 후속 작업이 기대하는 산출물, 관련 코드/문서 경계, 기존 태스크와의 포함 관계를 기준으로 자동 배치한다. - - 자동 배치는 "가장 빨리 할 수 있는 곳"이 아니라 "의존성과 완료 기준이 자연스럽게 이어지는 곳"을 우선한다. - - 대상 Milestone이 잠겨 있으면 현재 요청에 직접 걸리는 사용자 판단은 `구현 잠금`의 `결정 필요` 체크리스트로 옮기고, 표준선으로 처리 가능한 새 항목은 capability/산출물/완료 기준 후보 또는 관련 기존 태스크의 하위 작업으로 배치한다. - - 기존 태스크를 완성하는 세부 구현이면 하위 작업으로 넣고, 기존 태스크와 같은 수준의 독립 완료 항목이면 같은 Milestone의 태스크로 넣는다. - - 기존 Milestone의 목표/범위를 넓히거나 완료 기준을 과도하게 키우는 작업이면 새 Milestone으로 분리한다. - - 사용자 지정 위치가 Phase 목표, Milestone 범위 제외, 명백한 선후 의존성과 충돌하면 수정 전에 충돌 내용을 알리고 방향을 확인한다. +3. **레벨별 후보 탐색** + - `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다. + - target이 명시된 경우 대상 Phase의 `PHASE.md`를 읽고 Milestone 흐름과 Phase 경계를 확인한다. + - target이 없거나 활성 창 밖 배치 가능성이 있으면 `ROADMAP.md`의 Phase 흐름을 확인하고, 관련성이 높은 Phase 문서를 읽는다. + - 대상 또는 후보 Milestone 문서의 목표, 범위, 필수 기능, 완료 기준, 범위 제외, 구현 잠금을 확인한다. + - Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다. + - `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다. + - 필요한 경우에만 `ROADMAP.md`를 읽어 전체 Phase 흐름을 확인한다. -4. **변경 내용 검증** - - 기능 완료 체크는 사용자 설명 또는 파일/테스트/커밋 등 확인 가능한 근거를 기준으로 한다. - - evidence 없이 완료 여부가 불확실하면 체크하지 않고 TODO 또는 확인 필요로 남긴다. - - 변경 요청이 전체 목표 또는 Phase 목표와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. +4. **변경 내용 작성** + - `ROADMAP.md`는 전체 목표, Phase 흐름, 로딩 정책이 바뀔 때만 수정한다. + - `current.md`는 활성 Phase/Milestone 창이 바뀔 때 수정한다. + - `PHASE.md`는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다. + - Milestone 문서는 목표, 상태, 구현 잠금, 범위, Epic/Task, 완료 기준, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다. + - 동일/유사 후보가 있으면 기존 항목을 업데이트하고 중복 항목을 만들지 않는다. + - 새 Milestone은 해당 Phase의 `milestones/` 아래에 만든다. + - 새 Epic은 `필수 기능` 아래 `### Epic: [epic-id] <이름>`으로 만든다. + - 새 Task는 관련 Epic 아래 `- [ ] [item-id] 설명`으로 만든다. + - 새 항목은 레벨별 탐색에서 적절한 기존 후보가 없을 때만 만든다. + - 완료 체크는 evidence가 있을 때만 `[x]`로 바꾼다. -5. **로드맵 파일 갱신** - - `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` 모드에서는 구현 세부를 무작정 채우지 말고, 사용자 요청에 필요한 방향/범위 보완, 표준선 기록, 또는 잠금 상태 갱신만 반영한다. - - `구현 잠금`을 갱신할 때는 `결정 필요` 항목이 남아 있는지 결과 보고에 남긴다. 이 갱신만으로 `필수 기능`이나 `완료 기준`을 완료 처리하지 않는다. - - 새 Milestone은 사용자 지정 또는 자동 판단 위치에 삽입하고, 기존 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/.md`로 이동하고, 아카이브 대상 경로가 이미 있으면 확장자 앞에 다음 숫자를 붙인다. - - 아카이브로 이동한 Milestone 문서는 이동 전 내용 그대로 보존하고, 최신 템플릿에 맞춘 재포맷이나 체크리스트 보정을 하지 않는다. +5. **검증** + - `current.md`의 활성 Phase/Milestone 경로가 실제 파일을 가리키는지 확인한다. + - `current.md`의 활성 항목이 archive 경로를 가리키지 않는지 확인한다. + - `ROADMAP.md`의 Phase 경로가 실제 `PHASE.md` 파일을 가리키는지 확인한다. + - 각 `PHASE.md`의 Milestone 경로가 실제 파일을 가리키는지 확인한다. + - 상태 표기가 표준값인지 확인한다. + - Epic heading과 Task id 형식이 맞는지 확인한다. + - 요청 규모가 판정되었고 결과 보고에 남았는지 확인한다. + - 동일/유사 기존 항목을 검색했고 신규/업데이트 판정이 결과 보고에 남았는지 확인한다. + - 자동 배치한 신규 작업이면 선택한 후보와 밀린 후보의 근거가 결과 보고에 포함되는지 확인한다. + - `git diff --check`로 공백 오류를 확인한다. -6. **로드맵 룰 라우팅 점검** - - `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`에는 중복 마일스톤 컨텍스트 로딩 섹션을 추가하지 않는다. - - 기존 프로젝트 규칙에 마일스톤 컨텍스트 로딩 섹션이 남아 있으면 프로젝트 고유 내용이 아닌지 확인하고, 공통 룰과 중복되는 내용은 제거 대상으로 보고한다. - -7. **결과 보고** +6. **결과 보고** - 수정한 파일 목록 + - 요청 규모 판정과 근거 + - Phase -> Milestone -> Epic -> Task 탐색 경로와 후보 + - 신규 추가인지 기존 항목 업데이트인지 - 변경된 Phase / Milestone / 상태 - - 신규 작업의 삽입 단위와 배치 위치, 자동 배치인 경우 판단 근거 - - ROADMAP/current/Milestone 문서 템플릿 보정 여부 - - 활성 Milestone 창 변경 사항 - - archive 모드이면 아카이브 경로와 `ROADMAP.md`에 남긴 요약 - - 체크하거나 추가/제거한 태스크 또는 하위 작업 + - 신규 작업의 삽입 단위와 배치 위치 + - 자동 배치한 경우 비교한 후보와 선택 근거 + - current.md 활성 창 변경 사항 + - archive 모드이면 이동 경로와 남긴 링크 - 확인 필요로 남긴 항목 -## 실행 결과 검증 - -- [ ] `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의 `구현 잠금` 섹션에 사용자만 결정할 수 있는 항목이 체크리스트로 남아 있는가 -- [ ] `구현 잠금`이 없거나 잠긴 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`에 로드맵 컨텍스트 로딩, 구현 잠금, 아카이브 제외 규칙이 유지되는가 -- 검증 실패 시: 불일치한 파일만 다시 읽고 해당 항목만 수정한다. - ## 출력 형식 ```markdown ## 업데이트 완료 - 모드: -- 수정 파일: <해당 항목만 나열> +- 수정 파일: - agent-ops/roadmap/ROADMAP.md - agent-ops/roadmap/current.md - - agent-ops/roadmap/milestones/.md - - agent-ops/roadmap/archive/YYYY/MM/.md (archive 모드) + - agent-ops/roadmap/phase//PHASE.md + - agent-ops/roadmap/phase//milestones/.md + - agent-ops/roadmap/archive/phase//... (archive 모드) ## 변경 사항 - Phase: <변경 없음 | 요약> -- 삽입 단위: +- Milestone: <변경 없음 | 요약> +- 삽입 단위: +- 규모 판정: - <근거> +- 탐색 경로: Milestone 후보 -> Epic 후보 -> Task 후보 | 해당 없음> +- 신규/업데이트 판정: <신규 생성 | 기존 항목 업데이트 | 변경 없음> - <동일/유사 후보 근거> - 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음> -- 템플릿 보정: +- 배치 후보: <자동 배치 시 1순위/2순위 후보와 선택/제외 근거 | 해당 없음> +- 템플릿 보정: - 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>; 결정 필요: <없음 | 항목 요약> -- 활성 Milestone: <변경 없음 | 추가/제거 요약> -- 아카이브: <변경 없음 | 이동 경로와 ROADMAP 요약> +- 활성 항목: <변경 없음 | Phase/Milestone 추가/제거 요약> +- 아카이브: <변경 없음 | 이동 경로와 남긴 링크> - 상태: <변경 없음 | 이전 -> 이후> -- 태스크: <추가/수정/완료/제거 요약> +- Epic/Task: <추가/수정/완료/제거 요약> ## TODO 항목 @@ -333,26 +276,15 @@ Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이 ## 금지 사항 - 로드맵 파일이 없는데 새 구조를 임의로 만들지 않는다. 이 경우 `create-roadmap`을 사용한다. -- evidence 없이 기능이나 Milestone을 완료 처리하지 않는다. +- evidence 없이 Phase, Milestone, Epic, Task를 완료 처리하지 않는다. - 전체 `ROADMAP.md`를 모든 작업의 필수 로딩 파일로 만들지 않는다. -- `ROADMAP.md`에 상세 작업 체크리스트를 남기지 않는다. +- `ROADMAP.md`에 Milestone 상세 작업 체크리스트를 남기지 않는다. - `current.md`에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다. - `current.md`에 `agent-ops/roadmap/archive/**` 경로를 남기지 않는다. -- 완료된 Milestone 기록을 삭제하지 않는다. -- 아카이브된 Milestone 문서를 명시 요청 없이 읽거나 최신 템플릿으로 재포맷하지 않는다. -- 아카이브된 Milestone을 `ROADMAP.md`의 활성 `Milestone 목록`에 링크로 계속 남기지 않는다. +- archive 문서를 명시 요청 없이 읽거나 최신 템플릿으로 재포맷하지 않는다. +- 완료된 Phase/Milestone 기록을 삭제하지 않는다. +- Epic과 Task를 별도 파일로 분리하지 않는다. - Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다. -- 기존 순번 파일명을 대규모 rename하지 않는다. -- 신규 작업을 근거 없이 항상 새 Milestone으로 만들거나 맨 앞/맨 뒤에 추가하지 않는다. -- 작업 성격과 기존 태스크 포함 관계를 확인하지 않고 모든 신규 작업을 같은 단위로 처리하지 않는다. -- `구현 잠금`이 없거나 잠긴 Milestone에 대해 현재 요청과 직접 관련된 `결정 필요` 항목을 확인하기 전에 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다. -- 현재 요청과 직접 관련 없는 미정 항목만 남아 있거나 표준선으로 처리 가능한 작업까지 잠금 상태라는 이유만으로 막지 않는다. - 사용자만 결정할 수 있는 항목이 남아 있는데 Milestone의 `구현 잠금`을 `해제`로 바꾸지 않는다. -- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없는 Milestone을 관성적으로 `잠금` 상태로 두지 않는다. -- 초기 Milestone을 구현 계획처럼 자세한 package/file/function 체크리스트로 채우지 않는다. -- 사용자가 지정한 앞/뒤/아래 anchor 또는 대상 Phase/Milestone 컨테이너를 무시하지 않는다. -- Milestone 목표와 범위 제외 항목을 무시하고 태스크 체크리스트만 갱신하지 않는다. -- 해야 할 작업을 `필수 기능` 체크리스트 밖의 설명 문장에 숨기지 않는다. -- 사용자가 명시하지 않은 기존 `필수 기능` item-id를 바꾸지 않는다. -- 갱신 대상 Milestone의 형식이 다르다는 이유로 기존 내용이나 완료 체크 근거를 삭제하지 않는다. -- 타겟 프로젝트에서 `agent-ops/rules/common/` 또는 `agent-ops/skills/common/`을 직접 수정하지 않는다. +- 사용자가 지정한 Phase/Milestone/Epic/Task anchor를 무시하지 않는다. +- 사용자가 명시하지 않은 기존 epic-id나 item-id를 바꾸지 않는다.