Sdd doc scaffold

SDD 문서 뼈대 생성

빈 골격 문서를 단계별로 만들어 이후 분석과 설계의 틀을 고정한다. 이 Skill은 코드 조사나 실제 내용 작성을 수행하지 않는다.

• 등급 판정: references/task-grading.md
• 문서 관계와 템플릿: references/document-templates.md

골격 생성 뒤의 조사와 서술은 별도 Skill을 전제하지 않는다. 같은 에이전트 또는 후속 세션이 일반 작업으로 수행할 수 있다. 사람은 작업 등급, 생성 범위, Stage 완료를 확인하는 게이트 역할을 한다.

이 Skill에 포함된 references/는 실행 지침이다. reference를 읽는 것은 프로젝트 조사가 아니며 별도 사용자 확인을 요구하지 않는다. 단, 필요한 시점과 범위는 아래 절차를 따른다.

절대 규칙

1. 확정 전에는 파일을 만들지 않는다. 현재 Stage에서 생성할 파일 목록, 경로, 섹션 헤더, 주요 표 헤더, 문서 관계를 먼저 출력하고 사용자 확인 후에만 저장한다. 일부 항목만 확인했거나 전체 제안 승인인지 모호하면 다시 확인한다.
2. 확인받은 대상 외에는 생성하거나 수정하지 않는다. 저장소 전체 파일 목록이나 git 상태를 조사하지 않는다. 확인된 생성 예정 경로에 파일이 이미 있으면 덮어쓰지 말고 보고한 뒤 재사용 또는 수정 범위를 다시 확인받는다.
3. SDD 문서끼리는 반드시 연결한다. 아직 생성되지 않은 문서는 파일명만 적고 링크하지 않는다. 같은 Stage에서 함께 생성되는 문서는 링크할 수 있다.
4. 입력값과 분석 내용을 보충하기 위해 조사하지 않는다. 코드, 기존 문서, 저장소 파일 목록, git 상태와 로그에서 값을 추측하지 않는다. 사용자가 제공하지 않은 값은 묻는다. 확인된 생성 예정 경로의 존재 여부와 승인된 SDD 문서의 구조·링크·상태만 필요한 범위로 읽을 수 있다.
5. TODO 문구는 상수다. reference 템플릿의 > TODO: 문장과 표·목록의 TODO를 바꾸거나 실제 내용으로 채우지 않는다.
6. Stage를 건너뛰지 않는다. Stage 완료는 파일 존재나 TODO 교체 여부가 아니라 사용자의 명시적인 확인으로만 판정한다. 이전 Stage 완료 확인 전에는 다음 Stage 파일을 제안하거나 만들지 않는다.

역할과 완료 기준

구간	에이전트	사람
작업 시작	사용자 설명만으로 등급 후보를 제안한다.	등급을 확정한다.
Stage 골격	파일 목록, 구조, 관계를 제안하고 확인된 골격만 생성한다.	생성 범위를 확정한다.
내용 작성	이 Skill 밖의 일반 작업으로 코드 조사, 분석, 설계를 수행한다.	결과를 검토하고 Stage 완료를 확인한다.
다음 Stage	이전 Stage 완료 확인 후 다음 골격을 제안한다.	진행 여부를 결정한다.

Stage 3 진입은 Stage 1의 as-is 분석과 Stage 2의 to-be 설계 및 change plan이 작성되고 사용자 확인까지 끝났다는 뜻이다.

입력

먼저 등급 기준을 읽고, 코드나 저장소를 조사하지 않은 채 사용자 설명만으로 등급 후보를 제안해 확인받는다.

Trivial 또는 Small

SDD 전용 입력은 요구하지 않는다. 최소 기록에 필요한 내용만 확인한다.

Medium 이상

• 작업 등급: Trivial / Small / Medium / Large / Epic
• feature 슬러그: 폴더명에 사용할 kebab-case 문자열
• 작업 ID prefix: Stage 2부터 사용할 대문자 식별자
• 관련 코드 범위: 문서 관계 표에 적을 사용자 제공 경로 또는 설명
• 기준 ref: as-is를 고정할 commit hash, tag 또는 branch
• 작성일: 현재 날짜 또는 사용자가 지정한 날짜

관련 코드 범위와 기준 ref의 실재 여부는 확인하지 않는다.

Trivial과 Small의 최소 기록

Trivial 또는 Small이면 SDD 파일을 만들지 않는다. 다음 순서로 기존 작업 표면에 최소 기록을 남긴다.

1. 사용자가 지정한 Issue, Ticket 또는 PR 본문
2. 이미 사용하는 작업 관리 문서
3. 별도 위치가 없으면 채팅 출력

최소 기록을 위해 새 Markdown 파일을 만들지 않는다.

Trivial

## Trivial 작업 기록

- 변경 이유: {사용자가 제공한 내용 또는 확인 필요}
- diff 확인: {확인 기준 또는 확인 필요}

Small

## Small 작업 기록

- 변경 목적: {사용자가 제공한 내용 또는 확인 필요}
- 수정 대상: {사용자가 제공한 내용 또는 확인 필요}
- 수정 금지 영역: {사용자가 제공한 내용 또는 확인 필요}
- 검증 기준: {사용자가 제공한 내용 또는 확인 필요}

프롬프트에 없는 값은 조사하지 않고 확인 필요로 남기거나 사용자에게 묻는다.

Stage 재진입

이 Skill은 Stage마다 별도 세션에서 다시 호출될 수 있다.

재진입 시 다음을 확인한다.

• 현재 진행할 Stage
• 이전 Stage가 완료됐다는 사용자의 명시적인 확인
• Stage 2라면 초기 골격 생성 전인지, 개별 change plan 생성 단계인지
• Stage 2 개별 change plan 단계라면 사용자가 확인한 작업 ID

사용자의 진술을 완료 판정의 기준으로 삼는다. 파일 상태로 완료를 추측하지 않는다.

선언된 SDD 문서 경로는 사용자가 직접 제공했거나 이전 생성 제안에서 확인받은 정확한 파일 경로다. 경로를 새로 발견하기 위한 디렉터리 목록 조사는 하지 않는다.

사용자가 구조 검증을 요청하거나 허용한 경우에만 선언된 SDD 문서를 읽어 존재와 링크 상태를 확인한다. 코드나 git을 읽어 분석 내용을 보충하지 않는다.

템플릿 reference 게이트

Medium 이상이면 현재 Stage를 확정한 뒤 문서 템플릿의 다음 부분만 읽는다. 현재 Stage 섹션은 해당 ## Stage N 제목부터 다음 ## Stage 제목 직전까지다.

1. 공통 규칙
2. 현재 Stage 섹션

reference를 읽기 전에는 파일 구조를 제안하거나 생성하지 않는다. reference를 읽을 수 없으면 기억으로 템플릿을 재구성하지 말고 중단한다.

관계 표, 섹션, 표 헤더, TODO 문구는 reference에서 그대로 가져온다. 생성 제안에는 읽은 reference 경로와 Stage 섹션을 출력한다.

생성 단계

한 번에 전체 문서를 만들지 않는다. 각 Stage에서 골격을 생성한 뒤 멈추고 실제 내용 작성과 사용자 완료 확인을 기다린다.

Stage 1 - 현행 파악

docs/{feature}-sdd/
  README.md
  01-as-is-flow.md

골격 생성 후 일반 에이전트 작업으로 관련 코드를 조사하고 01-as-is-flow.md의 실제 내용을 작성한다. 사용자가 as-is 분석 완료를 확인하기 전에는 Stage 2를 시작하지 않는다.

Stage 2 - 목표 정의

먼저 다음 파일을 제안한다.

docs/{feature}-sdd/
  02-to-be-mapping.md
  change-plans/
    README.md

일반 에이전트 작업으로 TO-BE 매핑을 작성하고 변경 필요 또는 신규 필요 항목마다 작업 ID를 확정한다. 개별 change plan은 같은 Stage에 재진입해 확정된 ID에 대해서만 제안한다.

docs/{feature}-sdd/
  change-plans/
    {PREFIX}-{NN}.md

사용자가 TO-BE 매핑과 모든 change plan의 설계 완료를 확인하기 전에는 Stage 3을 시작하지 않는다.

Stage 3 - 실행 추적

Stage 3에 진입하면 분석과 설계는 완료된 상태다. 확정된 작업 ID에 대해서만 다음 파일을 제안한다.

docs/{feature}-sdd/
  backlog/
    {PREFIX}-{NN}.md
  implementation-backlog.md

골격 생성 후 일반 에이전트 작업으로 change plan을 구현 가능한 Todo와 선행 조건으로 분해한다. 사용자가 실행 백로그 완료를 확인하면 SDD 준비 단계를 종료한다.

실행 절차

1. 등급 기준을 읽고 작업 설명만으로 등급 후보를 제안해 사용자 확인을 받는다.
2. Trivial 또는 Small이면 최소 기록을 출력하고 파일을 만들지 않은 채 멈춘다.
3. Medium 이상이면 현재 Stage와 이전 Stage 완료 확인 여부를 확인한다.
4. 문서 템플릿 reference의 공통 규칙과 현재 Stage 섹션을 읽는다.
5. 현재 Stage에 필요한 입력값을 확인한다. 없는 값은 조사하지 않고 묻는다.
6. 참조한 템플릿, 생성·갱신 예정 파일, 섹션·표 헤더, 문서 관계를 출력한다.
7. 사용자 확인을 받는다.
8. 확인된 생성 경로의 존재 여부를 확인한다. 기존 파일은 덮어쓰지 않고 보고한다. 존재하지 않는 파일만 템플릿으로 만들고, 확인된 기존 SDD 문서만 링크와 상태 갱신을 위해 수정한다.
9. 이번 실행에서 생성하거나 수정한 파일만 읽어 상대 링크와 생성 범위를 검증한다.
10. 실제 내용 작성에 필요한 후속 작업과 현재 Stage 완료 조건을 알리고 멈춘다.

출력 형식

## 입력값
{등급, feature, ID prefix, 관련 코드 범위, 기준 ref, 작성일}

## 현재 Stage
{Stage와 이전 Stage 완료 확인 여부}

## 참조한 템플릿
references/document-templates.md - Stage {N}

## 생성 예정 파일
{파일 목록}

## 갱신 예정 파일
{링크와 상태 갱신이 필요한 기존 SDD 문서 또는 없음}

## 문서별 구조
{파일명, 섹션 헤더, 주요 표 헤더}

## 문서 관계
{선행/후속 연결}

## 확인 필요
{사용자가 결정해야 할 값}

금지

• 사용자 확인 전 파일 생성 또는 수정
• 확인 목록 밖의 파일 생성 또는 수정
• reference를 읽지 않고 템플릿 재구성
• 템플릿 TODO를 실제 분석이나 설계 내용으로 채우기
• 코드, git, 기존 문서를 조사해 입력값이나 분석 내용 보충하기
• 존재하지 않는 파일에 링크하기
• 작업 ID를 임의로 만들기
• 사용자 완료 확인 없이 다음 Stage로 진행하기