update roadmap related files and documentation

2026-05-24 06:40:58 +09:00 · 2026-05-24 06:40:58 +09:00 · 0a5085818d
commit 0a5085818d
parent 89c037585e
6 changed files with 128 additions and 12 deletions
--- a/README.md
+++ b/README.md
@ -4,10 +4,45 @@ AI 에이전트가 매 작업마다 필요한 컨텍스트만 읽도록 `agent-o

 핵심은 하나의 거대한 규칙 파일을 항상 읽는 방식이 아니라, 진입 규칙에서 프로젝트 규칙, 도메인 규칙, 스킬, 로드맵 문서를 필요한 순간에만 연결하는 것입니다.

+## 현재 상태
+
+이 저장소는 `agent-ops/` 공통 파일의 원본 저장소입니다. 루트의 `.agent-ops-source` 마커가 있으므로 공통 규칙, 공통 스킬, 동기화 스크립트는 이 저장소에서 수정하고 다른 프로젝트로 배포합니다.
+
+현재 프레임워크 버전은 `agent-ops/.version`에 기록되며, 이 README를 갱신한 시점의 버전은 `1.1.29`입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다.
+
+## 빠른 시작
+
+대상 프로젝트에 공통 scaffold를 직접 배치하려면 이 저장소 루트에서 아래 명령을 실행합니다.
+
+```bash
+bash agent-ops/bin/init-agent-ops.sh /path/to/target-project
+```
+
+프로젝트 분석을 포함한 초기 세팅은 에이전트에게 정확한 스킬 경로를 지정해 요청합니다. 초기 세팅 전에는 진입 파일이 없을 수 있으므로 스킬 파일 경로를 직접 안내하는 편이 안전합니다.
+
+```text
+agent-ops/skills/common/init-agent-ops/SKILL.md 를 읽고 실행해줘.
+```
+
+스킬 실행 후에는 생성된 `agent-ops/rules/project/rules.md`와 `agent-ops/rules/project/domain/*/rules.md`를 프로젝트에 맞게 확인하고 보완합니다.
+
+## 주요 명령
+
+| 목적 | 명령 | 비고 |
+|------|------|------|
+| 공통 scaffold 배치 | `bash agent-ops/bin/init-agent-ops.sh /path/to/target-project` | source 저장소에서 대상 프로젝트로 공통 파일과 진입 파일을 배치 |
+| 전체 sibling 프로젝트로 push 동기화 | `agent-ops/bin/sync.sh` | `agentic-framework`에서 실행하면 상위 폴더의 agent-ops 적용 프로젝트 전체에 반영 |
+| 특정 프로젝트로 push 동기화 | `agent-ops/bin/sync.sh <target>` | 폴더명, 상대경로, 절대경로 사용 가능 |
+| 대상 프로젝트에서 framework로 변경 올리기 | `agent-ops/bin/sync.sh agentic-framework` | 일반 프로젝트에서 실행 |
+| framework에서 대상 프로젝트로 내려받기 | `agent-ops/bin/sync.sh --pull agentic-framework` | 일반 프로젝트에서 실행 |
+| 버전 patch 증가 계산 | `agent-ops/bin/bump-version.sh <major.minor.patch>` | 결과 버전만 stdout으로 출력 |
+
 ## 구조

 ```text
 agent-ops/
+  GUIDE.md
+  .version
  bin/
    entry-files.sh
    init-agent-ops.sh
@ -16,6 +51,9 @@ agent-ops/
  rules/
    common/
      rules.md
+      rules-roadmap.md
+      _templates/
+        domain-rule-template.md
    project/
      rules.md
      domain/<domain-name>/rules.md
@ -24,6 +62,11 @@ agent-ops/
  skills/
    common/
      router.md
+      _templates/
+        skill-template.md
+        roadmap-template.md
+        roadmap-current-template.md
+        roadmap-milestone-template.md
      <skill-name>/SKILL.md
    project/
      <skill-name>/SKILL.md
@ -35,12 +78,28 @@ agent-ops/

 `agent-ops/roadmap/`은 `create-roadmap` 실행 시 생성됩니다.

+## 진입 파일
+
+`agent-ops/bin/entry-files.sh`가 초기화와 동기화에서 사용하는 진입 파일 목록의 단일 기준입니다.
+
+| 에이전트 | 파일 |
+|----------|------|
+| Gemini | `GEMINI.md` |
+| Claude | `CLAUDE.md` |
+| Kilo Code / OpenCode | `AGENTS.md` |
+| Cursor | `.cursorrules` |
+| Cline | `.clinerules` |
+
+각 진입 파일은 `agent-ops/rules/common/rules.md`의 복사본입니다. 동기화 시 대상 프로젝트의 기존 진입 파일 내용은 공통 규칙 내용으로 다시 적용됩니다.
+
 ## 컨텍스트 로딩

 에이전트 진입 파일(`CLAUDE.md`, `AGENTS.md`, `GEMINI.md` 등)은 `agent-ops/rules/common/rules.md`의 복사본입니다.

 세션이 시작되면 에이전트는 프로젝트별 규칙인 `agent-ops/rules/project/rules.md`와 개인 규칙인 `agent-ops/rules/private/rules.md`를 1회 읽습니다. 파일이 없으면 무시합니다.

+프로젝트에 `agent-ops/roadmap/`이 있으면 세션 최초 1회 `agent-ops/rules/common/rules-roadmap.md`도 읽습니다.
+
 작업이 특정 코드 영역을 변경하면 `rules/project/rules.md`의 도메인 매핑을 기준으로 해당 `rules/project/domain/<domain>/rules.md`만 읽습니다.

 스킬성 요청은 사용자가 명시적으로 요청했을 때 `agent-ops/skills/common/router.md`를 읽고, 매핑된 `SKILL.md` 하나를 실행합니다. 일반 작업마다 router와 모든 스킬을 자동으로 읽지 않습니다.
@ -85,18 +144,48 @@ Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `

 간단히는 아래 흐름입니다.

-1. 이 레포의 `agent-ops/` 폴더를 대상 프로젝트 루트에 복사합니다.
+1. 이 레포의 `agent-ops/` 폴더를 대상 프로젝트 루트에 복사하거나 `init-agent-ops.sh`로 초기화합니다.
 2. 에이전트에게 `agent-ops/skills/common/init-agent-ops/SKILL.md` 실행을 요청합니다.
 3. 생성된 `rules/project/rules.md`와 도메인 규칙을 확인하고 보완합니다.
 4. 반복 작업은 공통 스킬 또는 프로젝트 스킬로 정의합니다.
 5. 공통 파일 변경은 agentic-framework에서 관리하고 `sync-push` / `sync-pull`로 동기화합니다.

+초기화 스크립트는 `agent-task/archive/**`를 에이전트가 기본적으로 읽지 않도록 각 도구별 ignore 또는 permission 파일도 함께 보강합니다.
+
+## 동기화 흐름
+
+`agent-ops/bin/sync.sh`는 현재 프로젝트가 `.agent-ops-source`를 가진 원본인지 여부에 따라 방향을 결정합니다.
+
+| 실행 위치 | 명령 | 방향 |
+|-----------|------|------|
+| `agentic-framework` | `agent-ops/bin/sync.sh` | 원본에서 sibling 프로젝트 전체로 push |
+| `agentic-framework` | `agent-ops/bin/sync.sh <target>` | 원본에서 특정 대상 프로젝트로 push |
+| 일반 프로젝트 | `agent-ops/bin/sync.sh` | 현재 프로젝트의 공통 변경을 sibling `agentic-framework`로 push |
+| 일반 프로젝트 | `agent-ops/bin/sync.sh --pull agentic-framework` | `agentic-framework` 공통 파일을 현재 프로젝트로 pull |
+
+push 대상은 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, 그리고 `entry-files.sh`에 정의된 진입 파일로 제한됩니다.
+
 ## 관리 원칙

 - 공통 파일은 agentic-framework에서 수정합니다.
 - 대상 프로젝트에서는 `rules/project/`, `rules/private/`, `skills/project/`를 프로젝트에 맞게 수정합니다.
 - `agent-ops/rules/common/`, `agent-ops/skills/common/`, `agent-ops/bin/`은 공통 관리 영역입니다.
 - 공통 파일 변경 후에는 `agent-ops/.version`을 함께 관리하고 동기화합니다.
+- `agent-ops/rules/private/`는 개인 규칙 영역이며 대상 프로젝트의 `.gitignore`에 추가됩니다.
+
+## 작업 맥락
+
+AI 에이전트가 이 저장소를 이어서 작업할 때는 아래 경로를 먼저 확인하면 됩니다.
+
+| 경로 | 역할 |
+|------|------|
+| `agent-ops/rules/common/rules.md` | 모든 에이전트 진입 파일의 원본 |
+| `agent-ops/rules/common/rules-roadmap.md` | 로드맵 사용 프로젝트의 추가 공통 규칙 |
+| `agent-ops/skills/common/router.md` | 요청 키워드와 공통 스킬 매핑 |
+| `agent-ops/skills/common/*/SKILL.md` | 반복 작업별 실행 절차 |
+| `agent-ops/bin/entry-files.sh` | 진입 파일 목록의 단일 기준 |
+| `agent-ops/bin/sync.sh` | 공통 파일 push/pull 동기화 구현 |
+| `agent-ops/GUIDE.md` | 대상 프로젝트 적용 가이드 |

 ## 설계 효과

--- a/agent-ops/rules/common/rules-roadmap.md
+++ b/agent-ops/rules/common/rules-roadmap.md
@ -21,6 +21,14 @@
 - 단순 "진행", "구현", "계획 작성" 요청은 잠금을 해제하지 않는다.
 - 잠금 해제는 사용자가 Milestone 구체화 업데이트 또는 잠금 해제를 명시한 경우에만 검토한다.

+## 필수 기능 item-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는 명시적 요청 없이 바꾸지 않는다.
+
 ## 작업 지점 분석

 - 현재 작업 지점이나 남은 작업 분석 요청은 `analyze-roadmap-position` 스킬로 처리한다.
--- a/agent-ops/skills/common/_templates/roadmap-milestone-template.md
+++ b/agent-ops/skills/common/_templates/roadmap-milestone-template.md
@ -30,7 +30,8 @@

 ## 필수 기능

- [ ] <구현 세부가 아니라 이 Milestone에서 달성해야 할 capability 또는 산출물>
+<!-- 필수 기능 항목은 `- [ ] [item-id] 설명` 형식을 사용한다. item-id는 공백 없는 짧은 ASCII 영문/숫자 segment 1~4개로 작성하고 segment 구분자는 -_+= 만 사용한다. 전체 길이는 32자 이하를 권장한다. 해당 Milestone 안에서만 유일하면 되고, 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. -->
+- [ ] [item-id] <구현 세부가 아니라 이 Milestone에서 달성해야 할 capability 또는 산출물>

 ## 완료 기준

--- a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md
+++ b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md
@ -1,6 +1,6 @@
 ---
 name: analyze-roadmap-position
-version: 1.1.1
+version: 1.2.0
 description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확인 요청에 대해 활성 Milestone과 코드 상태를 함께 읽어 현재 작업 지점, Milestone 문서 링크, 남은 일을 추정하는 읽기 전용 스킬"
 ---

@ -10,6 +10,7 @@ description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확

 현재 브랜치, 변경 파일, 코드 구조, 활성 Milestone 문서를 함께 분석해 지금 작업이 어느 Milestone에 걸쳐 있는지와 남은 작업 후보를 보고한다.
 결과에는 추정한 Milestone의 문서 링크를 항상 함께 출력한다.
+Milestone의 `필수 기능` 항목에 item-id가 있으면 남은 작업과 판단 근거에 함께 표시해 사용자가 짧은 id로 후속 지시를 할 수 있게 한다.
 `current.md`만 보고 현재 작업 위치를 단정하지 않고, 실제 코드 상태와 요청 내용을 근거로 판단한다.

 ## 언제 호출할지
@ -48,6 +49,8 @@ description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확

 3. **Milestone 매칭**
   - 활성 Milestone의 목표, 범위, 완료 기준, 범위 제외 항목과 변경 파일/요청 내용을 비교한다.
+   - 활성 Milestone의 `필수 기능` 체크리스트를 확인하고, 관련 항목에 item-id가 있으면 판단 근거와 남은 작업에 item-id를 함께 기록한다.
+   - 여러 Milestone 후보에서 같은 item-id가 보이면 item-id만으로 위치를 확정하지 말고 Milestone 이름과 문서 링크를 함께 제시한다.
   - 활성 Milestone의 `구현 잠금` 섹션과 상태를 함께 확인한다. 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획 전에 Milestone 구체화 업데이트가 필요하다고 보고한다.
   - 하나의 Milestone에 명확히 속하면 단일 후보로 보고한다.
   - 둘 이상의 Milestone에 걸치면 복수 후보로 보고하고, 어떤 파일이나 기능이 어느 Milestone에 닿는지 나눈다.
@ -78,6 +81,7 @@ Milestone 문서 경로를 찾지 못한 경우에도 링크 항목을 생략하
 - [ ] 활성 Milestone 문서의 목표와 범위 제외 항목을 확인했는가
 - [ ] 활성 Milestone 문서의 `구현 잠금` 섹션 존재 여부와 상태를 확인했는가
 - [ ] 추정 Milestone마다 문서 링크를 출력했는가
+- [ ] 관련 `필수 기능` 항목에 item-id가 있으면 결과에 함께 표시했는가
 - [ ] 변경 파일 또는 사용자 요청과 Milestone 판단 근거가 연결되어 있는가
 - [ ] 남은 작업을 `확인됨`, `추정됨`, `확인 필요`로 구분했는가
 - [ ] 로드맵 파일을 수정하지 않았는가
@ -103,9 +107,9 @@ Milestone 문서 경로를 찾지 못한 경우에도 링크 항목을 생략하

 ## 남은 작업

- 확인됨: <항목>
- 추정됨: <항목>
- 확인 필요: <항목>
+- 확인됨: [<item-id>] <항목>
+- 추정됨: [<item-id>] <항목>
+- 확인 필요: [<item-id 또는 신규 id 필요>] <항목>

 ## 읽은 주요 파일

--- a/agent-ops/skills/common/create-roadmap/SKILL.md
+++ b/agent-ops/skills/common/create-roadmap/SKILL.md
@ -1,6 +1,6 @@
 ---
 name: create-roadmap
-version: 1.5.1
+version: 1.6.0
 description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase, 구현 구체화 잠금이 있는 순번 없는 Milestone 문서, 활성 Milestone 창을 처음 생성하는 공통 스킬
 ---

@ -58,6 +58,9 @@ agent-ops/
 - 새 Milestone은 사용자가 구현 구체화와 잠금 해제를 명시하지 않는 한 `구현 잠금` 상태를 `잠금`으로 둔다.
 - `구현 잠금`에는 이 문서가 방향성/범위 정의인지, 구현 가능한 수준인지, 잠금 해제 조건과 잠금 중 금지 사항을 적는다.
 - `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 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를 판단하는 제품/운영/문서 수준의 확인 항목으로 제한한다.
 - `완료 기준`은 검증 가능한 조건의 체크리스트로 작성한다.
 - `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.
@ -125,7 +128,7 @@ agent-ops/
   - 각 Milestone 문서는 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따른다.
   - 각 Milestone 문서에 `구현 잠금` 섹션을 포함한다.
   - 사용자가 해당 Milestone의 구현 구체화와 잠금 해제를 명시적으로 승인하지 않았으면 `구현 잠금` 상태는 `잠금`으로 작성한다.
-   - `필수 기능`과 그 하위 항목은 capability 또는 산출물 수준의 `- [ ]` 체크리스트로 작성한다.
+   - `필수 기능`과 그 하위 항목은 capability 또는 산출물 수준의 `- [ ] [item-id] 설명` 체크리스트로 작성한다.
   - 완료 근거가 확인된 항목만 `- [x]`로 표시하고, 근거가 없으면 체크하지 않는다.
   - `완료 기준`도 검증 가능한 조건의 `- [ ]` 체크리스트로 작성한다.
   - 미래 Milestone은 확정된 방향과 capability만 `필수 기능`에 넣고, 불확실한 구현 세부는 `작업 컨텍스트`의 확인 필요 항목으로 둔다.
@ -152,6 +155,7 @@ agent-ops/
 - [ ] 각 Milestone 문서가 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따르는가
 - [ ] 각 Milestone 문서에 `구현 잠금` 섹션이 있고, 구현 구체화가 없으면 상태가 `잠금`인가
 - [ ] 각 Milestone 문서의 `필수 기능`과 `완료 기준`이 체크리스트 형식인가
+- [ ] 각 Milestone 문서의 `필수 기능` 체크리스트 항목이 `- [ ] [item-id] 설명` 형식이고 item-id가 해당 Milestone 안에서 유일한가
 - [ ] `ROADMAP.md`에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가
 - [ ] 로딩 정책에 `구현 잠금`이 없거나 잠긴 Milestone의 구현/계획 시작 금지 규칙이 포함되었는가
 - [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `rules-roadmap.md`를 읽도록 라우팅하는가
@ -190,6 +194,6 @@ agent-ops/
 - Milestone 문서에서 `구현 잠금` 섹션을 생략하지 않는다.
 - 사용자의 명시적 구현 구체화/잠금 해제 승인 없이 새 Milestone을 `해제` 상태로 만들지 않는다.
 - Milestone을 구현 계획처럼 package/file/function 단위로 과도하게 구체화하지 않는다.
- 해야 할 capability 또는 산출물을 일반 불릿이나 설명 문장에 숨기지 않는다. `필수 기능` 또는 그 하위 항목의 체크리스트로 작성한다.
+- 해야 할 capability 또는 산출물을 일반 불릿이나 설명 문장에 숨기지 않는다. `필수 기능` 또는 그 하위 항목의 item-id가 있는 체크리스트로 작성한다.
 - 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다.
 - `agent-ops/rules/common/`이나 `agent-ops/skills/common/`을 타겟 프로젝트에서 직접 수정하지 않는다.
--- a/agent-ops/skills/common/update-roadmap/SKILL.md
+++ b/agent-ops/skills/common/update-roadmap/SKILL.md
@ -1,6 +1,6 @@
 ---
 name: update-roadmap
-version: 1.7.1
+version: 1.8.0
 description: 기존 전체 목표, Phase, 구현 구체화 잠금이 있는 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 신규 작업의 삽입 위치와 단위를 사용자 지정 또는 자동 판단으로 배치하며 current.md의 활성 Milestone 창을 동기화하는 공통 스킬
 ---

@ -88,6 +88,9 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 이 Milestone은 구현 계획이 아니라 범위/방향성 게이트다. 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
 - `구현 잠금`을 `해제`하려면 사용자가 Milestone 구체화 업데이트 또는 잠금 해제를 명시해야 하며, 책임 경계, API/프로토콜, 검증 기준, 선행 조건이 문서에 반영되어야 한다.
 - `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 유지한다.
+- `필수 기능`의 각 체크리스트 항목은 `- [ ] [item-id] 설명` 형식을 사용한다. item-id는 사람이 타이핑하고 LLM이 참조하기 쉬운 공백 없는 짧은 ASCII 토큰으로 작성한다.
+- item-id는 영문/숫자 segment 1~4개로 작성하고, segment 구분자는 `-`, `_`, `+`, `=`만 사용한다. 가능하면 1~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
+- item-id의 유일성 범위는 해당 Milestone 문서 안으로 제한하며, 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. 기존 item-id는 사용자가 명시적으로 바꾸라고 하지 않는 한 보존하고, 새 항목에는 소문자 영문 중심의 의미 있는 id를 만든다.
 - `완료 기준`은 검증 가능한 조건의 체크리스트로 유지한다.
 - 일반 불릿이나 설명 문장에 숨어 있는 capability/산출물은 성격을 판단해 `필수 기능` 체크리스트 또는 기존 항목의 하위 체크리스트로 옮긴다.
 - `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 유지하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.
@ -100,7 +103,7 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
 - 기존 프로젝트에 이미 순번 파일명이 있으면 대규모 rename을 하지 말고, 갱신 범위에 포함된 새 항목부터 순번 없는 형식을 적용한다.
 - 새 작업은 습관적으로 새 Milestone으로 만들거나 목록 맨 앞/뒤에 붙이지 않는다.
- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
+- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 기존 태스크 item-id, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
 - 사용자가 위치를 지정하지 않으면 `ROADMAP.md`의 Phase 흐름, 기존 Milestone 목표, 기존 필수 기능/태스크, 선후 의존성, 활성 Milestone 창, 완료 기준을 보고 가장 자연스러운 위치를 자동으로 판단한다.
 - 자동 배치한 경우 결과 보고에 선택한 삽입 단위, Phase/Milestone/태스크 위치, 판단 근거를 짧게 남긴다.

@ -119,6 +122,8 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - 잠긴 Milestone 안에 새 작업을 추가할 때는 구현 태스크가 아니라 capability, 결정 안건, 선행 조건, 완료 기준 후보로 작성한다.
 - `구현 잠금`이 없거나 잠긴 Milestone에 대해 사용자가 "진행", "구현", "계획 작성"을 요청하면 로드맵을 우회하지 않는다. 먼저 Milestone 문서 구체화 업데이트와 잠금 해제를 요청한다.
 - 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다. `<anchor-task> 아래`처럼 하위 위치가 명시되면 기존 태스크 하위 항목으로 넣고, `<anchor-task> 앞/뒤`면 같은 목록 레벨의 형제 항목으로 넣는다.
+- 사용자가 item-id를 언급하면 해당 Milestone의 `필수 기능` 체크리스트에서 정확히 일치하는 item-id를 우선 매칭한다. 중복되거나 없으면 임의로 고르지 말고 확인한다.
+- 여러 Milestone 후보에서 같은 item-id가 발견되면 item-id만으로 확정하지 말고 Milestone 이름이나 문서 경로를 확인한다.
 - 위치는 지정됐지만 단위가 명시되지 않은 경우, anchor 레벨과 작업 성격을 함께 보고 새 Milestone, 태스크, 하위 작업 중 하나를 선택한다.
 - 위치 지정이 `<phase-name> 안` 또는 `<milestone-name> 안`처럼 컨테이너만 지정된 경우, 잠금 해제된 Milestone에서 작업 내용이 기존 태스크의 세부 구현이면 해당 컨테이너 안에서 가장 관련 있는 태스크 아래에 넣을 수 있다. 이 경우 결과 보고에 "위치는 지정된 컨테이너를 따랐고, 단위는 하위 작업으로 판단"처럼 남긴다.
 - 위치 지정이 `<anchor-milestone> 앞/뒤` 또는 `<anchor-task> 앞/뒤`처럼 순서 anchor인 경우, 같은 레벨의 앞/뒤 배치를 유지한다. 작업 성격상 다른 레벨이 더 적절해 보여도 조용히 재배치하지 말고 사용자에게 확인한다.
@ -166,6 +171,7 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
   - 대상 또는 후보 Milestone 문서의 `구현 잠금` 상태와 해제 조건을 확인한다.
   - `구현 잠금`이 없거나 잠긴 Milestone에 대한 구현, 구현 계획, 세부 API/파일 구조 확정 요청이면 수정으로 진행하지 않고 잠금 상태와 필요한 구체화 업데이트를 사용자에게 보고한다.
   - 대상 Milestone 문서가 표준 템플릿 섹션 순서와 체크리스트 형식을 따르는지 확인한다.
+   - 대상 Milestone 문서의 `필수 기능` item-id 목록을 확인하고, 중복 또는 누락이 갱신 범위에 있으면 보정 대상으로 기록한다.
   - 신규 작업과 이름, 산출물, 코드 경계, 완료 기준이 겹치는 기존 태스크가 있는지 확인한다.

 3. **신규 작업 삽입 단위와 위치 판단**
@ -201,7 +207,9 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
   - 새 Milestone은 사용자가 구현 구체화와 잠금 해제를 명시하지 않는 한 `구현 잠금` 상태를 `잠금`으로 작성한다.
   - 기존 Milestone에 새 태스크를 넣는 경우 `필수 기능` 체크리스트에 사용자 지정 또는 자동 판단 위치로 삽입하고, 근거 없이 목록 맨 앞이나 맨 뒤에 붙이지 않는다.
   - 잠금 해제된 Milestone에서 기존 태스크의 하위 작업으로 넣는 경우 부모 태스크 아래의 하위 체크리스트로 작성하고, 부모 태스크의 의미가 바뀌면 부모 문장도 필요한 만큼만 보완한다.
-   - 기존 `필수 기능`이 일반 불릿이면 상태 근거를 보존해 `- [ ]` 또는 `- [x]` 체크리스트로 변환한다.
+   - 새로 추가하거나 형식 보정 범위에 포함된 `필수 기능` 항목은 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 형식으로 작성한다.
+   - 기존 `필수 기능`이 일반 불릿이면 상태 근거를 보존해 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 체크리스트로 변환한다.
+   - 기존 `필수 기능` 체크리스트에 item-id가 있으면 사용자가 명시적으로 바꾸라고 하지 않는 한 유지한다. item-id가 없는 항목을 갱신 범위에서 보정할 때는 해당 Milestone 안에서 중복되지 않는 id를 붙인다.
   - 기존 `완료 기준`이 일반 불릿이면 검증 조건 단위의 체크리스트로 변환한다.
   - 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다.
   - 완료된 Milestone의 기록은 삭제하지 않고 상태만 변경한다.
@ -232,6 +240,7 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - [ ] `구현 잠금`이 없거나 잠긴 Milestone에 구현 태스크, `agent-task` 계획, 세부 API/파일 구조 확정을 추가하지 않았는가
 - [ ] 잠금 해제한 경우 사용자 승인 또는 구체화 근거를 결과 보고에 남겼는가
 - [ ] 갱신 대상 Milestone 문서의 `필수 기능`과 `완료 기준`이 체크리스트 형식인가
+- [ ] 갱신 대상 Milestone 문서의 `필수 기능` 체크리스트 항목이 `- [ ] [item-id] 설명` 형식이고 item-id가 해당 Milestone 안에서 유일한가
 - [ ] 신규 작업이 사용자 지정 위치를 따랐거나, 위치 미지정 시 자동 배치 근거가 남아 있는가
 - [ ] 신규 작업의 삽입 단위가 작업 성격과 기존 태스크 포함 관계에 맞는가
 - [ ] 자동 배치 위치가 Phase/Milestone 목표, 범위 제외 항목, 선후 의존성과 충돌하지 않는가
@ -286,5 +295,6 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - 사용자가 지정한 앞/뒤/아래 anchor 또는 대상 Phase/Milestone 컨테이너를 무시하지 않는다.
 - Milestone 목표와 범위 제외 항목을 무시하고 태스크 체크리스트만 갱신하지 않는다.
 - 해야 할 작업을 `필수 기능` 체크리스트 밖의 설명 문장에 숨기지 않는다.
+- 사용자가 명시하지 않은 기존 `필수 기능` item-id를 바꾸지 않는다.
 - 갱신 대상 Milestone의 형식이 다르다는 이유로 기존 내용이나 완료 체크 근거를 삭제하지 않는다.
 - 타겟 프로젝트에서 `agent-ops/rules/common/` 또는 `agent-ops/skills/common/`을 직접 수정하지 않는다.