toki/proto-socket
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
proto-socket/agent-ops/skills/common/roadmap-sdd/SKILL.md

12 KiB
Raw Blame History

name version description
roadmap-sdd 1.0.0 로드맵 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 경로로 이동할 준비 상태인지 확인한다.

구조

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은 구현 잠금에 아래 필드를 둔다.

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

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

- 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하지 말고 해결 필요로 보고한다.

출력 형식

## 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의 구현 잠금을 해제하지 않는다.