diff --git a/README.md b/README.md index 7ef7594..c20a81b 100644 --- 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 ` | 폴더명, 상대경로, 절대경로 사용 가능 | +| 대상 프로젝트에서 framework로 변경 올리기 | `agent-ops/bin/sync.sh agentic-framework` | 일반 프로젝트에서 실행 | +| framework에서 대상 프로젝트로 내려받기 | `agent-ops/bin/sync.sh --pull agentic-framework` | 일반 프로젝트에서 실행 | +| 버전 patch 증가 계산 | `agent-ops/bin/bump-version.sh ` | 결과 버전만 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//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.md project/ /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//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 ` | 원본에서 특정 대상 프로젝트로 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` | 대상 프로젝트 적용 가이드 | ## 설계 효과 diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index 56cbaf0..dc85fa1 100644 --- 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` 스킬로 처리한다. diff --git a/agent-ops/skills/common/_templates/roadmap-milestone-template.md b/agent-ops/skills/common/_templates/roadmap-milestone-template.md index 486f404..f384194 100644 --- 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] <구현 세부가 아니라 이 Milestone에서 달성해야 할 capability 또는 산출물> ## 완료 기준 diff --git a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md index c5075fb..c0c4c78 100644 --- 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 문서 경로를 찾지 못한 경우에도 링크 항목을 생략하 ## 남은 작업 -- 확인됨: <항목> -- 추정됨: <항목> -- 확인 필요: <항목> +- 확인됨: [] <항목> +- 추정됨: [] <항목> +- 확인 필요: [] <항목> ## 읽은 주요 파일 diff --git a/agent-ops/skills/common/create-roadmap/SKILL.md b/agent-ops/skills/common/create-roadmap/SKILL.md index b5bf265..122a415 100644 --- 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/`을 타겟 프로젝트에서 직접 수정하지 않는다. diff --git a/agent-ops/skills/common/update-roadmap/SKILL.md b/agent-ops/skills/common/update-roadmap/SKILL.md index ed5323a..cdd89f5 100644 --- 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의 레벨을 먼저 확인한다. ` 아래`처럼 하위 위치가 명시되면 기존 태스크 하위 항목으로 넣고, ` 앞/뒤`면 같은 목록 레벨의 형제 항목으로 넣는다. +- 사용자가 item-id를 언급하면 해당 Milestone의 `필수 기능` 체크리스트에서 정확히 일치하는 item-id를 우선 매칭한다. 중복되거나 없으면 임의로 고르지 말고 확인한다. +- 여러 Milestone 후보에서 같은 item-id가 발견되면 item-id만으로 확정하지 말고 Milestone 이름이나 문서 경로를 확인한다. - 위치는 지정됐지만 단위가 명시되지 않은 경우, anchor 레벨과 작업 성격을 함께 보고 새 Milestone, 태스크, 하위 작업 중 하나를 선택한다. - 위치 지정이 ` 안` 또는 ` 안`처럼 컨테이너만 지정된 경우, 잠금 해제된 Milestone에서 작업 내용이 기존 태스크의 세부 구현이면 해당 컨테이너 안에서 가장 관련 있는 태스크 아래에 넣을 수 있다. 이 경우 결과 보고에 "위치는 지정된 컨테이너를 따랐고, 단위는 하위 작업으로 판단"처럼 남긴다. - 위치 지정이 ` 앞/뒤` 또는 ` 앞/뒤`처럼 순서 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/`을 직접 수정하지 않는다.