--- name: roadmap-sdd version: 1.0.0 description: 로드맵 Milestone에 녹아 있는 SDD 설계 게이트를 판정, 생성, 갱신, 사용자 리뷰 대기, 잠금 해제, archive 처리할 때 사용한다. 사용자가 SDD, spec gate, 설계 게이트, SDD 필요 여부, SDD 승인 준비, SDD 사용자 리뷰, SDD 잠금 해제, SDD archive를 요청하거나, 큰 Milestone의 구현 잠금이 SDD 필요 상태일 때 사용한다. --- # Roadmap SDD ## 목적 큰 Milestone에서 로드맵만으로 부족한 계약, 상태 전이, 수용 시나리오, 검증 근거를 `agent-roadmap/sdd/` 아래에 기록한다. SDD는 로드맵과 분리된 별도 운영물이 아니라 Milestone `구현 잠금`을 해제하기 위한 하위 설계 게이트다. ## 모드 - `classify`: Milestone 또는 신규 작업 설명이 SDD 대상인지 판정한다. - `create`: SDD 초안을 만든다. - `update`: 기존 SDD를 갱신한다. - `check-gate`: SDD 잠금, 사용자 리뷰, Acceptance Scenario, Evidence Map 연결성을 확인한다. - `review-ready`: 사용자 결정이 필요한 항목을 `USER_REVIEW.md`로 만든다. - `resolve-review`: 사용자의 답변을 SDD에 반영하고 `USER_REVIEW.md`를 `user_review_N.log`로 보낸다. - `archive`: Milestone archive와 함께 SDD를 archive 경로로 이동할 준비 상태인지 확인한다. ## 구조 ```text agent-roadmap/ sdd/ / / SDD.md USER_REVIEW.md user_review_0.log archive/ sdd/ / / SDD.md user_review_*.log ``` - `USER_REVIEW.md`는 필요한 경우에만 존재한다. - `user_review_N.log`는 해결된 사용자 리뷰 기록이다. - 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd///`로 이동한다. - SDD 경로는 같은 Milestone의 slug를 그대로 사용한다. 별도 SDD slug를 만들지 않는다. ## 표준 형식 - `SDD.md`는 반드시 `agent-ops/skills/common/_templates/roadmap-sdd-template.md`의 top-level 섹션을 같은 순서로 사용한다. - `Source of Truth`, `State Machine`, `Acceptance Scenarios`, `Evidence Map` 표는 템플릿의 컬럼을 유지한다. - 값이 아직 없으면 섹션을 삭제하지 말고 `없음`, `확인 필요`, 또는 잠금 항목으로 남긴다. - `update`는 기존 SDD의 내용을 갱신하더라도 표준 섹션과 순서를 유지한다. 누락된 표준 섹션이 있으면 먼저 복원한 뒤 변경을 반영한다. - `check-gate`는 표준 섹션이나 필수 표 컬럼이 누락된 SDD를 `invalid`로 보고하고, plan gate 통과 대상으로 보지 않는다. - SDD별 추가 설명은 `작업 컨텍스트` 또는 해당 표준 섹션 안에 넣고 임의 top-level 섹션을 늘리지 않는다. ## SDD 대상 판정 아래 중 하나라도 해당하면 `SDD: 필요`로 판정한다. - cross-repo 계약 또는 프로젝트 간 source of truth가 있다. - Plane, Jira, Mattermost 같은 외부 provider 상태를 변경한다. - lifecycle, state machine, 사용자 승인 gate, archive 자동화, work item sync에 영향을 준다. - idempotency, retry, identity map, revision 보존이 필요하다. - API, proto, config, env, DB/schema, 이벤트 계약을 바꾼다. - field smoke, 원격 runner, 사용자 소유 환경이 완료 근거의 일부다. - 실패 처리 방식이 제품 판단, 보안, 비용, 권한, 데이터 보존에 영향을 준다. 아래에만 해당하면 `SDD: 불필요`로 판정한다. - 단일 repo 내부의 작고 국소적인 리팩터링이다. - 문서 정리, 테스트 보강, 작은 UI 보강이다. - Milestone Task의 `검증:`과 일반 plan/code-review 루프만으로 완료 판단이 충분하다. - 기존 SDD 또는 agent-contract를 그대로 소비하고 새 설계 결정이 없다. ## Milestone 연결 SDD가 필요한 Milestone은 `구현 잠금`에 아래 필드를 둔다. ```md - 상태: 잠금 - SDD: 필요 - SDD 문서: `agent-roadmap/sdd///SDD.md` - 잠금 해제 조건: - [ ] SDD 잠금이 해제되어 있다 - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다 - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다 - [ ] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다 - 결정 필요: 없음 ``` SDD가 불필요한 Milestone은 사유를 남긴다. ```md - SDD: 불필요 - SDD 사유: 단일 repo 내부 변경이며 외부 계약, 상태 머신, provider mutation이 없다. ``` ## SDD 잠금 SDD 문서는 자체 잠금을 가진다. - `SDD 잠금: 잠금`이면 `plan`은 구현 계획을 만들지 않는다. - `USER_REVIEW.md`가 존재하면 사용자 답변 전까지 SDD 잠금을 해제하지 않는다. - 사용자 결정이 필요 없는 기술 세부는 agent가 코드, 규칙, 기존 계약을 근거로 채우고 잠금 항목으로 만들지 않는다. - 모든 잠금 항목이 해결되고 사용자 리뷰가 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 둔다. - SDD 잠금이 해제되어야 Milestone `구현 잠금`도 해제 후보가 된다. 사용자 리뷰가 필요한 항목: - source of truth 선택 - 상태 전이 의미 변경 - 사용자 승인, 검토, 폐기 흐름 변경 - 외부 provider 쓰기 동작 추가 - cross-repo 책임 경계 변경 - scope 확대/축소 - 보안, 비용, 데이터 보존, 권한 영향 - 실패 시 처리 정책이 제품 판단인 경우 사용자 리뷰가 필요 없는 항목: - 기존 코드/문서/rule에서 답이 명확한 세부 - 기존 agent-contract를 그대로 따르는 인터페이스 - 일반 파일 구조, 테스트 명령, Evidence Map 작성 - 구현자가 plan/code-review 루프에서 검증할 수 있는 기술 선택 ## 실행 절차 ### classify 1. 관련 Milestone 또는 신규 작업 설명을 읽는다. 2. SDD 대상 판정 기준을 적용한다. 3. 결과를 `필요`, `불필요`, `불명확` 중 하나로 보고한다. 4. `필요`이면 Milestone `구현 잠금`에 SDD 경로와 잠금 해제 조건을 남기도록 안내하거나 갱신한다. ### create 1. `agent-ops/skills/common/_templates/roadmap-sdd-template.md`를 읽는다. 2. 대상 Milestone의 목표, 범위, 기능 Task, 범위 제외, 구현 잠금을 읽는다. 3. 필요하면 `agent-contract/index.md`를 읽고 매칭 계약 원문을 링크한다. 계약 본문을 SDD에 복제하지 않는다. 4. 표준 템플릿의 top-level 섹션, 섹션 순서, 필수 표 컬럼을 유지해 `agent-roadmap/sdd///SDD.md`를 만든다. 5. 사용자 결정이 필요한 항목이 있으면 `review-ready`를 수행한다. 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 둘 수 있다. ### update 1. 기존 SDD와 Milestone을 읽는다. 2. 변경 요청이 문제, source of truth, 상태 전이, interface, scenario, evidence 중 어디에 해당하는지 판정한다. 3. 표준 섹션 또는 필수 표 컬럼이 누락되어 있으면 먼저 복원한다. 4. 사용자 결정이 필요한 변경이면 SDD 잠금을 `잠금`으로 두고 `USER_REVIEW.md`를 갱신한다. 5. 기술 세부 보강이면 SDD 본문과 Evidence Map만 갱신한다. ### check-gate 1. Milestone `구현 잠금`의 `SDD` 필드를 확인한다. 2. `SDD: 불필요`이면 `not-required`로 보고한다. 3. `SDD: 필요`인데 SDD 문서가 없으면 `blocked`로 보고한다. 4. SDD가 표준 top-level 섹션 또는 필수 표 컬럼을 갖추지 못했으면 `invalid`로 보고한다. 5. SDD 상태가 `[승인됨]`이 아니거나 `SDD 잠금`이 `잠금`이면 `blocked`로 보고한다. 6. `USER_REVIEW.md`가 있으면 `blocked`로 보고한다. 7. Acceptance Scenario가 Milestone 기능 Task id와 연결되어 있는지 확인한다. 8. Evidence Map이 plan의 `Spec Targets`에 고정되고 완료 시 `Spec Completion`으로 검증될 수 있도록 scenario, task, evidence가 매핑되어 있는지 확인한다. 9. 모두 충족하면 `pass`로 보고한다. ### review-ready 1. `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md`를 읽는다. 2. 사용자만 결정할 항목만 추린다. 3. `agent-roadmap/sdd///USER_REVIEW.md`를 만든다. 4. SDD의 `SDD 잠금`을 `잠금`으로 둔다. 5. 채팅으로 즉시 선택지를 묻지 않고 파일 경로와 필요한 결정만 보고한다. ### resolve-review 1. `USER_REVIEW.md`와 SDD를 읽는다. 2. 사용자의 답변을 관련 SDD 섹션과 `사용자 리뷰 이력`에 반영한다. 3. `USER_REVIEW.md`를 `user_review_N.log`로 이동한다. 4. 남은 잠금 항목이 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 바꾼다. 5. SDD gate가 pass이면 Milestone `구현 잠금`을 해제할 수 있다고 보고한다. 직접 해제는 요청 또는 runtime/update-roadmap 흐름에 따른다. ### archive 1. Milestone이 `[완료]` 또는 `[폐기]`인지 확인한다. 2. 활성 SDD 디렉터리가 있으면 `agent-roadmap/archive/sdd///`로 이동한다. 3. 활성 `PHASE.md` 또는 Milestone archive 링크와 SDD archive 경로가 어긋나지 않는지 확인한다. 4. `USER_REVIEW.md`가 남아 있으면 archive하지 말고 해결 필요로 보고한다. ## 출력 형식 ```markdown ## SDD 결과 - mode: `` - milestone: `` - sdd: `` - 결과: `` - 잠금: `<해제 | 잠금 | 해당 없음>` - 사용자 리뷰: `<없음 | USER_REVIEW.md | user_review_N.log>` - 다음 단계: `<없음 | 사용자 리뷰 필요 | Milestone 구현 잠금 해제 가능 | SDD 작성 필요>` ``` ## 금지 사항 - SDD 본문에 agent-contract 계약 원문을 복제하지 않는다. - 사용자 결정이 필요한 항목을 chat 질문으로 바로 던지지 않는다. `USER_REVIEW.md`로 남긴다. - 작은 작업에 SDD를 강제하지 않는다. - `USER_REVIEW.md`가 남아 있는데 SDD 상태를 `[승인됨]`으로 두지 않는다. - SDD gate가 막힌 Milestone에 대해 구현 plan을 만들지 않는다.