alt/agent-ops/skills/common/roadmap-sdd/SKILL.md

---
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 `구현 잠금`을 해제하고, 이후 Milestone 구현 계획이 따라야 할 설계 입력을 고정하는 하위 설계 게이트다.
`SDD: 필요` Milestone의 구현 계획은 승인된 SDD의 Acceptance Scenario와 Evidence Map에서 구현 범위, 검증, 완료 evidence를 역산해야 한다.

## 모드

- `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/
    <phase-slug>/
      <milestone-slug>/
        SDD.md
        USER_REVIEW.md
        user_review_0.log
  archive/
    sdd/
      <phase-slug>/
        <milestone-slug>/
          SDD.md
          user_review_*.log
```

- `USER_REVIEW.md`는 필요한 경우에만 존재한다.
- `user_review_N.log`는 해결된 사용자 리뷰 기록이다.
- 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd/<phase-slug>/<milestone-slug>/`로 이동한다.
- 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`로 보고하고, Milestone 구현 잠금 해제 대상으로 보지 않는다.
- SDD별 추가 설명은 `작업 컨텍스트` 또는 해당 표준 섹션 안에 넣고 임의 top-level 섹션을 늘리지 않는다.
- SDD 안에서 Milestone, Phase, 계약 문서, `USER_REVIEW.md`, 후속 SDD 같은 문서 포인터를 남길 때는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다.
- SDD 링크 target은 `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/` 디렉터리 기준 상대경로로 쓴다. 예: `[Milestone 문서](../../../phase/<phase-slug>/milestones/<milestone-slug>.md)`, `[PHASE.md](../../../phase/<phase-slug>/PHASE.md)`, `[USER_REVIEW.md](USER_REVIEW.md)`.
- 실제 생성/갱신한 SDD에는 `<phase-slug>`, `<milestone-slug>`, `<path>` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다.
- 코드 source path나 machine-readable identity는 raw 값이 필요하면 유지할 수 있다.

## 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 문서: [SDD.md](../../../sdd/<phase-slug>/<milestone-slug>/SDD.md)
- 잠금 해제 조건:
  - [ ] SDD 잠금이 해제되어 있다
  - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다
  - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  - [ ] Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증 가능하게 연결되어 있다
- 결정 필요: 없음
```

SDD가 불필요한 Milestone은 사유를 남긴다.

```md
- SDD: 불필요
- SDD 사유: 단일 repo 내부 변경이며 외부 계약, 상태 머신, provider mutation이 없다.
```

## SDD 잠금

SDD 문서는 자체 잠금을 가진다.

- `SDD 잠금: 잠금`이면 Milestone `구현 잠금` 해제 대상이 아니다.
- `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 `구현 잠금`에 해당 Milestone 파일 위치 기준 `SDD 문서` Markdown 링크와 잠금 해제 조건을 갱신한다.
5. 신규 Milestone 생성 또는 `[스케치] -> [계획]` 승격 흐름에서 호출된 경우, `classify`에서 멈추지 않고 같은 턴에 `create`까지 이어간다. 사용자만 결정할 항목이 없으면 승인 가능한 SDD로 만들고, 사용자 결정이 있으면 SDD 초안과 `USER_REVIEW.md`를 함께 만든다.

### 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/<phase-slug>/<milestone-slug>/SDD.md`를 만든다.
5. 사용자 결정이 필요한 항목이 있으면 `review-ready`를 수행한다. 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 둘 수 있다.
6. SDD가 `[승인됨]`이고 SDD 잠금이 `해제`이며 `USER_REVIEW.md`가 없으면 같은 흐름의 `update-roadmap` 갱신에서 Milestone `구현 잠금` 해제 후보로 반영한다.

### 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이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증될 수 있도록 scenario, task, evidence가 매핑되어 있는지 확인한다.
9. 모두 충족하면 `pass`로 보고한다.

### review-ready

1. `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md`를 읽는다.
2. 사용자만 결정할 항목만 추린다.
3. `agent-roadmap/sdd/<phase-slug>/<milestone-slug>/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/<phase-slug>/<milestone-slug>/`로 이동한다.
3. 활성 `PHASE.md` 또는 Milestone archive 링크와 SDD archive 경로가 어긋나지 않는지 확인한다.
4. `USER_REVIEW.md`가 남아 있으면 archive하지 말고 해결 필요로 보고한다.

## 출력 형식

```markdown
## SDD 결과

- mode: `<classify|create|update|check-gate|review-ready|resolve-review|archive>`
- milestone: <[Milestone 문서](agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md) | 해당 없음>
- sdd: <[SDD.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/SDD.md) | 없음>
- 결과: `<pass | blocked | not-required | created | updated | review-required | archived | invalid>`
- 잠금: `<해제 | 잠금 | 해당 없음>`
- 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md) | [user_review_N.log](agent-roadmap/sdd/<phase-slug>/<milestone-slug>/user_review_N.log)>
- 다음 단계: `<없음 | 사용자 리뷰 필요 | Milestone 구현 잠금 해제 가능 | SDD 작성 필요>`
```

## 금지 사항

- SDD 본문에 agent-contract 계약 원문을 복제하지 않는다.
- 사용자 결정이 필요한 항목을 chat 질문으로 바로 던지지 않는다. `USER_REVIEW.md`로 남긴다.
- 작은 작업에 SDD를 강제하지 않는다.
- `USER_REVIEW.md`가 남아 있는데 SDD 상태를 `[승인됨]`으로 두지 않는다.
- SDD gate가 막힌 Milestone의 구현 잠금을 해제하지 않는다.