@simplysm/sd-claude 13.0.84 → 13.0.86

package/claude/skills/sd-plan-dev/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: sd-plan-dev
+description: 구현계획서를 기반으로 TDD 방식의 실제 구현을 수행. 사용자가 구현계획서 기반의 코드 구현을 요청할 때 사용
+argument-hint: "<plan 파일 경로> [--worktree]"
+---
+
+# sd-plan-dev: 구현 실행
+
+구현계획서(plan)를 기반으로 TDD 사이클(RED → GREEN → Refactor)을 실행하여 실제 구현을 수행한다.
+
+## 1. 인자 파싱
+
+`$ARGUMENTS`를 분석하여 plan과 옵션을 결정한다.
+
+### 1-1. plan 파일 경로
+
+`$ARGUMENTS`에 `.md`로 끝나는 경로가 포함된 경우:
+- 해당 파일을 Read한다
+
+### 1-2. 인자 없음
+
+`$ARGUMENTS`가 비어있으면 (옵션 플래그 제외):
+- 현재 대화 맥락에서 plan 내용을 파악한다
+- 대화에도 plan이 없으면 다음을 출력하고 종료한다:
+  > 구현계획서가 없습니다. 먼저 `/sd-plan`을 실행하여 계획을 수립하세요.
+
+### 1-3. `--worktree` 옵션
+
+`$ARGUMENTS`에 `--worktree`가 포함된 경우 worktree 모드를 활성화한다.
+- 기본값: 비활성 (현행 동작)
+- 활성 시: 2단계에서 worktree 격리 실행 전략을 적용한다
+
+## 2. 작업 파악 및 실행 전략
+
+plan에서 작업 목록을 파악하고 스케줄링을 결정한다.
+
+1. plan의 `## 작업 의존성` 섹션을 확인한다 (없으면 모든 작업을 독립으로 간주)
+2. 스케줄링을 결정한다:
+   - 작업 1개: 단일 실행
+   - 독립 작업 2개 이상: 병렬 실행
+   - 의존 작업: 의존 순서대로 순차 실행
+   - 혼합: 독립 작업끼리는 병렬, 의존 체인은 순차로 조합
+
+### `--worktree` 미사용 시
+
+결정된 스케줄링에 따라 실행한다:
+- 단일 작업: 바로 3단계(TDD 사이클)로 진행
+- 병렬 실행: Agent tool로 각 작업을 별도 subagent에 위임하여 동시에 TDD 사이클 수행
+- 순차 실행: 선행 작업 완료 후 후행 작업 시작
+
+### `--worktree` 사용 시
+
+결정된 스케줄링에 따라 `isolation: "worktree"` Agent tool로 실행한다:
+- 단일 작업: worktree subagent 1개 생성 → 완료 후 4단계(merge)
+- 병렬 실행: 각 작업별 worktree subagent 병렬 생성 → 모든 subagent 완료 후 4단계에서 순차 merge
+- 순차 실행: 첫 작업 worktree subagent 생성 → 완료 후 4단계에서 merge → 현재 branch(merge 완료된 상태)를 base로 다음 작업 worktree subagent 생성 → 반복
+
+**worktree 불가 제약**: subagent 테스트(`_test.md` 기반)가 필요한 작업은 worktree subagent 안에서 Agent tool을 사용할 수 없으므로 worktree 적용 불가. 해당 작업은 worktree 없이 3단계로 직접 수행한다.
+
+**혼합 케이스** (worktree 가능 + 불가 작업 공존): worktree 가능한 작업끼리 스케줄링에 따라 worktree subagent로 실행하고, worktree 불가 작업은 모든 worktree merge 완료 후 순차 단일 수행한다. 단, 의존성에 의해 순서가 정해진 경우 그 순서를 우선한다.
+
+## 3. TDD 사이클 실행
+
+각 작업에 대해 plan의 TDD 계획을 따라 실행한다.
+
+### RED Phase: 실패하는 테스트 작성 및 실행
+
+plan의 RED Phase에 명시된 테스트 전략에 따라 분기한다:
+
+**vitest 테스트인 경우:**
+- plan의 테스트 시나리오에 따라 vitest 테스트 파일을 작성한다
+- Bash로 `vitest run {테스트 파일}` 실행하여 실패를 확인한다
+
+**subagent 테스트인 경우 (LLM용 문서, 테스트 환경 없는 코드 등):**
+- plan의 테스트 시나리오에 따라 `_test.md` 파일을 작성한다
+  - plan 파일 기반: plan 파일과 동일 디렉토리. plan이 `{R번호}_plan.md`이면 `{R번호}_test.md`, `plan.md`이면 `test.md`
+  - 현재 대화 기반 (파일 경로 없음): plan에 참조 spec 경로가 있으면 해당 디렉토리에 저장. 없으면 `.tasks/` 하위에 새 디렉토리 생성
+  - 형식: 테스트별 입력/기대출력 쌍
+- Agent tool로 subagent를 생성하여 테스트를 실행하고 실패를 확인한다
+
+**테스트 생략인 경우:**
+- RED Phase를 건너뛰고 GREEN Phase로 바로 진행한다
+
+### GREEN Phase: 최소 구현
+
+plan의 GREEN Phase에 명시된 구현 계획에 따라 최소한의 구현을 수행한다 (YAGNI 원칙).
+- 구현 후 테스트를 재실행하여 통과를 확인한다
+- vitest: Bash로 재실행
+- subagent 테스트: Agent tool로 재실행
+- 테스트 생략인 경우: 구현만 수행
+
+### Refactor Phase
+
+`/simplify 다음 파일만 리뷰: {수정한 파일 목록}` 하여 품질을 개선한다.
+- 완료 후 테스트를 재실행하여 통과를 확인한다
+- 리팩터링으로 테스트가 깨지면 수정 후 재확인한다
+
+### Commit Phase
+
+TDD 사이클(RED → GREEN → Refactor) 완료 후 1회 commit한다.
+- 작업 하나 = commit 하나
+- `--worktree` 사용 여부와 관계없이 동일하게 적용한다
+
+## 4. worktree merge (`--worktree` 활성 시)
+
+worktree subagent 완료 후 반환된 branch를 순차적으로 merge한다.
+
+**정상 흐름:**
+1. `git merge {branch}` 실행
+2. merge 완료 후 worktree를 정리한다
+3. 성공 시 다음 branch merge (또는 5단계로 진행)
+
+**conflict 발생 시:**
+1. `git merge --abort` 실행하여 working directory를 깨끗한 상태로 복원
+2. conflict 발생한 worktree 경로와 branch명을 출력
+3. AskUserQuestion으로 "직접 merge하세요" 안내 + "완료" 옵션 제시
+4. 사용자가 "완료" 선택 시 worktree를 정리하고 다음 branch merge 계속
+
+## 5. 완료 안내
+
+모든 작업의 TDD 사이클이 완료되면 다음을 출력한다:
+- 전체 작업의 구현 결과 요약 (작업별 상태)

package/claude/skills/sd-readme/SKILL.md

@@ -1,166 +1,213 @@
 ---
 name: sd-readme
-description: Used when requesting "README documentation generation", "sd-readme", etc.
+description: LLM 인덱싱용 README.md 및 docs/ 생성. 사용자가 패키지의 README.md 생성이나 갱신을 요청할 때 사용
+argument-hint: "[패키지명... | root]"
 ---
 
-# SD Readme — Monorepo Package README Documentation Generator
+# sd-readme: LLM 인덱싱용 README 생성
 
-Automatically generates README.md documentation for each package in the monorepo. Applies Progressive Disclosure principles by choosing either a single README.md or a README.md + docs/*.md structure depending on the package size.
+프로젝트의 패키지에 대해 LLM 인덱싱에 최적화된 README.md 및 docs/ 문서를 생성하거나 업데이트한다.
 
-ARGUMENTS: Package name (optional). If specified, only that package is processed; if omitted, all packages are processed in parallel.
+## 1. 인자 파싱
 
-## Workflow
+`$ARGUMENTS`에서 대상 패키지를 결정한다.
+- `$ARGUMENTS`가 비어있으면 → `"private": true`가 아닌 모든 패키지를 대상으로 한다 + **루트 README도 생성한다**
+- `$ARGUMENTS`가 `root`이면 → **루트 README만** 단독 생성한다 (2~4단계를 건너뛰고 5단계로 바로 진행)
+- `$ARGUMENTS`에 패키지명이 있으면 → 해당 패키지만 대상으로 한다 (공백 구분으로 다수 가능, 루트 README는 생성하지 않음)
+  - 패키지명은 디렉토리명 (예: `core-common`), 또는 `package.json`의 `name` 필드 값 (예: `@simplysm/core-common`) 중 어느 것이든 매칭한다
+  - `root`와 패키지명을 혼합할 수 없다 (`root`는 단독으로만 사용)
 
-```mermaid
-flowchart TD
-    A[Parse arguments] --> B{Package name specified?}
-    B -- Yes --> C[Generate README.md]
-    B -- No --> D[Collect public package list]
-    D --> E[Run Agent per package in parallel]
-    E -- Each Agent --> C
-```
+## 2. 프로젝트 유형 감지
 
-### A. Parse Arguments
+다음 순서로 monorepo 워크스페이스를 감지한다. 하나라도 매칭되면 monorepo로 판단한다:
 
-Extract the package name from the ARGUMENTS passed when invoking the skill.
+1. **pnpm**: `pnpm-workspace.yaml` 파일이 존재하면 `packages` 필드에서 glob 패턴을 추출하여 패키지 디렉토리를 탐색한다
+2. **yarn/npm**: 루트 `package.json`의 `workspaces` 필드를 확인한다
+   - `workspaces`가 배열인 경우: 직접 glob 패턴 목록으로 사용
+   - `workspaces.packages`가 배열인 경우: yarn berry 형식
+3. **단일 패키지**: 위 어느 것도 해당하지 않으면 현재 프로젝트 자체를 대상으로 한다
 
-- **Package name specified** → Find the corresponding directory under `packages/` and proceed directly to **C. Generate README.md**.
-- **Package name not specified** → Proceed to **D. Collect public package list**.
+## 3. 대상 패키지 목록 수집
 
-### C. Generate README.md
+- **monorepo**: 2단계에서 감지한 glob 패턴으로 패키지 디렉토리를 탐색한다
+  - 각 디렉토리의 `package.json`을 확인하여 `"private": true`인 패키지는 제외한다
+  - 1단계에서 특정 패키지명이 지정되었으면 해당 패키지만 필터링한다
+- **단일 패키지**: 현재 프로젝트 루트를 유일한 대상으로 한다 (`"private": true`여도 처리한다 — 단일 패키지는 명시적으로 스킬을 호출한 것이므로)
 
-Perform the following for a single target package.
+## 4. 패키지별 README 생성/업데이트
 
-#### C-1. Analyze package.json
+각 패키지에 대해 Agent tool을 호출하여 분석부터 파일 작성까지 독립적으로 수행하게 한다. 대상이 여러 개이면 병렬로 호출한다.
 
-Read `packages/<name>/package.json`:
+각 subagent에 다음 지침을 전달한다:
 
-1. Check the `name` and `description` fields.
-2. If `"private": true`, **skip** this package.
-3. Identify the package entry point source code.
+### 4-1. 소스 코드 분석
 
-#### C-2. Analyze Source Code
+패키지를 분석한다:
+- `package.json`: name, description, dependencies, peerDependencies
+- `src/` 디렉토리 구조 및 export된 API
+- 주요 클래스/함수/타입의 시그니처와 용도
 
-1. Recursively read the entry point file and all exports to collect every public API.
-2. If JSDoc comments exist, use them as descriptions for each item.
+### 4-2. 생성/업데이트 모드 결정
 
-#### C-3. Determine Document Structure and Generate
+- `README.md`가 없으면 → **생성 모드**: 처음부터 작성
+- `README.md`가 있으면 → **업데이트 모드**: 기존 내용을 읽고, 현재 코드 상태와 비교하여 변경사항만 반영
 
-Examine the source code size and the number of logical categories, then **autonomously** decide which of the two structures below is appropriate:
+### 4-3. 분리 여부 판단 (LLM 자율)
 
-- **Single README.md**: When the package is small, has few APIs, and category classification is unnecessary
-- **README.md + docs/*.md**: When the package is large or has multiple logical categories
+- README.md 하나로 충분하다고 판단되면 → README.md에 모든 내용을 포함
+- 내용이 많아 분리가 필요하다고 판단되면 → README.md에 개요 + docs/ 링크, `docs/{category}.md`에 상세 내용
 
-If an existing README.md or docs/ directory exists, **modify only the changed parts** based on the existing content. If no existing documentation exists, create it from scratch.
-If the structure changes (B to A), delete the now-unnecessary `docs/` directory.
-Write in **English**.
+### 4-4. 파일 작성
 
-#### C-4. Manage package.json files Field
+**README.md 구조 (작은 패키지, docs/ 불필요 시):**
 
-When creating or deleting the `docs/` directory, update the `files` array in `package.json` accordingly:
+````markdown
+# {패키지명}
 
-- **When applying Structure B**: If the `files` array does not contain `"docs"`, add it.
-- **When applying Structure A**: If the `files` array contains `"docs"`, remove it.
+{패키지 설명 - 목적과 핵심 기능}
 
----
+## 설치
 
-##### Structure A: Single README.md (Small Packages)
+{설치 방법}
 
-Create the `packages/<name>/README.md` file:
+## 주요 기능
 
-```markdown
-# <package-name from package.json>
+### {기능 카테고리 1}
 
-> <description from package.json>
+{사용법, 주요 API 시그니처, 예제 코드}
 
-<Write a detailed description of the package's main features and purpose in English>
+### {기능 카테고리 2}
 
-## API Reference
+{사용법, 주요 API 시그니처, 예제 코드}
+````
 
-### <exportedName>
+**README.md 구조 (큰 패키지, docs/ 분리 시):**
 
-```typescript
-<export signature code>
-```
+````markdown
+# {패키지명}
 
-<Description of this API>
+{패키지 설명 - 목적과 핵심 기능}
 
----
+## 설치
 
-(... Repeat for all exported items ...)
+{설치 방법}
 
-## Usage Examples
+## 문서
 
-```typescript
-import { ... } from "<package-name>";
+| 카테고리 | 설명 |
+|---------|------|
+| [{카테고리1}](docs/{category1}.md) | {간단한 설명} |
+| [{카테고리2}](docs/{category2}.md) | {간단한 설명} |
 
-// Main usage example code
-```
-```
+## 빠른 시작
 
----
+{가장 기본적인 사용 예제}
+````
 
-##### Structure B: README.md + docs/*.md (Large Packages)
+**docs/{category}.md 구조:**
 
-**README.md** — Create the `packages/<name>/README.md` file:
+````markdown
+# {카테고리명}
 
-```markdown
-# <package-name from package.json>
+## {기능/API 1}
 
-> <description from package.json>
+{상세 설명, 시그니처, 사용 예제}
 
-<Write a detailed description of the package's main features and purpose in English>
+## {기능/API 2}
 
-## Documentation
+{상세 설명, 시그니처, 사용 예제}
+````
 
-| Category | Description |
-|----------|-------------|
-| [<Category1>](docs/<category1>.md) | <Category description and list of key items> |
-| [<Category2>](docs/<category2>.md) | <Category description and list of key items> |
-| ... | ... |
-```
+**내용 작성 원칙:**
+- LLM이 코드 작성 시 참조할 수 있도록 API 시그니처와 사용 예제를 포함한다
+- 사용법/가이드 + API 레퍼런스 하이브리드 형태로 작성한다
+- 점진적 공개: 개요 → 주요 사용법 → 상세 API 순
 
-**docs/*.md** — Create a `packages/<name>/docs/<category>.md` file for each category:
+## 5. 루트 README 생성/업데이트
 
-```markdown
-# <Category Name>
+**실행 조건**: 1단계에서 인자가 비어있거나 `root`인 경우에만 실행한다. 패키지명이 지정된 경우 이 단계를 건너뛴다.
 
-## <exportedName>
+### 5-1. 프로젝트 분석
 
-```typescript
-<export signature code>
-```
+4단계가 실행된 경우, 각 subagent가 분석한 패키지 정보(name, description, dependencies)를 재사용한다. 추가로 다음을 분석한다:
+- 루트 `package.json` (scripts, devDependencies), `pnpm-workspace.yaml` (또는 `workspaces` 설정), 빌드 설정 파일
+- 각 패키지의 `README.md` (존재하는 경우, 첫 섹션)
 
-<Description of this API>
+### 5-2. 생성/업데이트 모드 결정
 
----
+4-2와 동일한 방식으로 판단한다 (대상 경로만 루트 `README.md`로 변경).
 
-(... Repeat for all exported items in this category ...)
+### 5-3. 파일 작성
 
-## Usage Examples
+루트 README는 단일 파일로 작성한다 (docs/ 분리 없음).
 
-```typescript
-import { ... } from "<package-name>";
+**루트 README.md 구조:**
 
-// Main usage example code for this category
-```
-```
+````markdown
+# {프로젝트명}
 
-Determine category names and classifications autonomously, considering the source code directory structure, functional similarity, etc.
+{프로젝트 설명 - 목적, 핵심 특징}
 
----
+## 설계 철학
 
-### D. Collect Public Package List
+{프로젝트의 설계 원칙}
 
-Use Glob to search `packages/*/package.json`, excluding packages with `private: true`.
+## 패키지
 
----
+### {카테고리 1}
+
+| 패키지 | 타겟 | 설명 |
+|--------|------|------|
+| [{패키지명}]({경로}) | {타겟} | {설명} |
+
+## 시작하기
+
+### 사전 요구사항
+
+{필요한 환경}
+
+### 설치
+
+{설치 방법}
+
+### 개발
+
+{개발 명령어}
+
+### 빌드
+
+{빌드 명령어}
+
+### 테스트
+
+{테스트 명령어}
+
+## 아키텍처
+
+{의존성 레이어, 빌드 타겟 등}
+
+## 사용 예제
+
+{주요 패키지의 기본 사용 예제}
+
+## 라이선스
+
+{라이선스 정보}
+````
+
+**내용 작성 원칙:**
+- 각 패키지 README.md가 존재하면 해당 설명을 요약하여 패키지 목록 테이블에 반영한다
+- 패키지 README.md가 없으면 `package.json`의 description과 소스 코드 분석으로 설명을 작성한다
+- `package.json`의 scripts, 빌드 설정 파일을 참조하여 명령어 섹션을 작성한다
+- 패키지 간 의존 관계를 분석하여 아키텍처 섹션을 작성한다
+- LLM이 코드 작성 시 monorepo 전체 구조를 빠르게 파악할 수 있도록 작성한다
+
+## 6. 완료 안내
 
-### E. Run Agent Per Package in Parallel
+모든 패키지 처리가 완료되면 다음을 출력한다:
+- 생성/업데이트된 파일 목록
+- 각 파일의 생성/업데이트 여부
 
-For each remaining package, use the Agent tool to pass the following prompt **in parallel**:
-```
-/sd-readme <package-name>
-```
+## 7. 커밋
 
-Terminate once all subagents have completed.
+수정된 파일이 있으면 `/sd-commit`을 실행하여 자동 커밋한다.

package/claude/skills/sd-spec/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: sd-spec
+description: 사용자 요청과 코드베이스를 분석하여 요구분석서를 작성. 사용자가 요구분석/spec 작성을 요청할 때 사용
+argument-hint: "<topic>"
+---
+
+# sd-spec: 요구분석서 작성
+
+사용자 요청과 코드베이스를 분석하여 최대한 상세한 요구분석서(`_spec.md`)를 작성한다.
+
+## 1. topic 파싱
+
+`$ARGUMENTS`에서 topic을 추출한다.
+- `$ARGUMENTS`가 비어있으면 현재 대화 맥락에서 topic을 파악한다. 대화 맥락도 없으면 AskUserQuestion으로 topic을 요청한다
+- topic을 영문 kebab-case로 변환한다 (예: "ORM 마이그레이션" → `orm-migration`, "사용자 인증" → `user-auth`)
+- 특수문자(`#`, `/`, `\`, `(`, `)`, `.` 등)는 제거하거나 `-`로 치환한다 (예: "DB 연동 (v2.0)" → `db-connection-v2-0`)
+- 이미 kebab-case이면 그대로 사용한다
+
+## 2. 코드베이스 분석
+
+topic과 관련된 코드베이스를 분석한다.
+- Agent tool (subagent_type: Explore)을 활용하여 관련 파일, 패키지, 의존성을 탐색한다
+- 필요에 따라 Glob, Grep, Read 등을 직접 사용할 수도 있다
+- 분석 결과로 현재 상태, 관련 코드/패키지, 기존 구현 방식을 파악한다
+
+## 3. 반복적 명확화 질문
+
+코드베이스 분석과 사용자 요청을 종합하여 불명확한 점을 파악한다.
+불명확한 점이 있으면 다음 프로세스를 반복한다:
+
+1. 질문 대상에 대한 **자세한 설명을 텍스트로 먼저 출력**한다
+   - 선택지 각각의 장단점, 트레이드오프를 설명한다
+   - 현재 코드베이스의 맥락을 반영한 설명을 제공한다
+2. AskUserQuestion을 **1개만** 호출한다 (한번에 하나씩만 질문)
+3. 답변을 반영하여 추가 분석을 수행한다
+4. 불명확한 점이 더 있으면 1번으로 돌아간다
+
+충분한 정보가 모였다고 판단하면 질문을 종료하고 문서 작성으로 넘어간다.
+
+## 4. 요구분석서 작성
+
+### 기본 섹션 (항상 포함)
+
+다음 기본 섹션을 반드시 포함하여 작성한다:
+
+```markdown
+# 요구분석서: {topic 설명}
+
+## 개요
+
+기능의 목적과 배경을 기술한다.
+
+## 현재 상태
+
+코드베이스 분석 결과를 기술한다.
+- 관련 기존 코드/패키지
+- 현재 구현 방식
+- 관련 의존성
+
+## 요구사항
+
+### R1. {요구사항 제목}
+
+{상세 내용}
+
+### R2. {요구사항 제목}
+
+{상세 내용}
+
+## 영향 범위
+
+| 경로 | 변경 내용 |
+|------|----------|
+| {파일/패키지 경로} | {변경 설명} |
+```
+
+### R 번호 부여 기준
+
+- **기본은 단일 R이다.** 나눌 명확한 이유가 없으면 R1 하나로 작성한다
+- R을 나누는 것은 예외적 판단이다. "나눠야 하는가?"가 아니라 "나눌 수밖에 없는가?"로 판단한다
+- 하나의 R 항목은 하나의 `/sd-plan` 호출로 처리 가능한 크기여야 한다
+
+**R을 나눠야 하는 유일한 기준 — 다음 두 조건을 모두 만족할 때만 나눈다:**
+
+1. 서로 다른 패키지/레이어에 걸쳐 있어서 하나의 `/sd-plan`으로 다루면 범위가 과도하다
+2. 각 R이 단독으로 "테스트 → 구현 → 검증" 사이클을 완결할 수 있다
+
+**잘못된 분리 (흔한 실수):**
+
+```markdown
+### R1. 설정 데이터 모델 정의
+### R2. 설정 저장/불러오기 구현
+### R3. 설정 UI 컴포넌트 작성
+```
+
+→ 이 세 항목은 "설정 기능"이라는 하나의 구현 단위다. 모델만 만들어서는 검증할 수 없고, 저장 로직만으로도 의미가 없다. 하나로 합친다:
+
+```markdown
+### R1. 설정 기능 구현
+```
+
+**나눠야 하는 경우:**
+
+```markdown
+### R1. 사용자 인증 (회원가입, 로그인, 토큰 발급)
+### R2. 역할 기반 접근 제어 (권한 정의, 미들웨어, 라우트 가드)
+```
+
+→ 인증과 접근 제어는 각각 독립적으로 구현·검증 가능하고, 두 기능을 합치면 `/sd-plan` 하나로 다루기에 범위가 과도하다
+
+### 추가 섹션 (점진적 공개)
+
+요구사항의 특성을 판단하여 해당하는 참조 파일만 Read하고, 그 양식에 따라 추가 섹션을 작성한다.
+관련 없는 참조 파일은 읽지 않는다.
+
+| 요구사항 특성 | 참조 파일 |
+|-------------|----------|
+| UI/화면 관련 | `${CLAUDE_SKILL_DIR}/sections/ui.md` |
+| API/엔드포인트 관련 | `${CLAUDE_SKILL_DIR}/sections/api.md` |
+| DB/테이블/스키마 관련 | `${CLAUDE_SKILL_DIR}/sections/db.md` |
+| 프로세스/흐름 관련 | `${CLAUDE_SKILL_DIR}/sections/process.md` |
+| 아키텍처/패키지 구조 관련 | `${CLAUDE_SKILL_DIR}/sections/architecture.md` |
+
+여러 특성이 해당되면 여러 참조 파일을 읽고 각각의 추가 섹션을 모두 포함한다.
+
+## 5. 파일 저장
+
+- 디렉토리: `.tasks/{yyMMddHHmmss}_{topic}/`
+  - `yyMMddHHmmss`는 현재 시간 (Bash `date +%y%m%d%H%M%S`로 생성)
+  - `{topic}`은 1단계에서 변환한 kebab-case topic
+- 파일명: `spec.md`
+- 전체 경로: `.tasks/{yyMMddHHmmss}_{topic}/spec.md`
+- 디렉토리가 없으면 먼저 생성한다
+
+## 6. 완료 안내
+
+문서 작성이 완료되면 다음을 출력한다:
+- 완성된 문서의 파일 경로
+- 사용자에게 직접 문서를 확인할 것을 권장
+- 다음 단계 안내: "다음 단계로 `/sd-plan`을 실행하세요."

package/claude/skills/sd-spec/sections/api.md

@@ -0,0 +1,85 @@
+# API 관련 추가 섹션
+
+요구사항에 API/엔드포인트가 포함된 경우, 기본 섹션에 아래 양식을 추가한다.
+
+## 엔드포인트 목록
+
+API 엔드포인트를 정의한다.
+
+**양식:**
+```markdown
+## 엔드포인트 목록
+
+| 메서드 | 경로 | 설명 | 인증 |
+|-------|------|------|------|
+| {GET/POST/PUT/DELETE} | {/api/...} | {설명} | {Y/N} |
+```
+
+**예시:**
+```markdown
+## 엔드포인트 목록
+
+| 메서드 | 경로 | 설명 | 인증 |
+|-------|------|------|------|
+| GET | /api/users | 사용자 목록 조회 | Y |
+| GET | /api/users/:id | 사용자 상세 조회 | Y |
+| POST | /api/users | 사용자 생성 | Y (admin) |
+| PUT | /api/users/:id | 사용자 수정 | Y |
+| DELETE | /api/users/:id | 사용자 삭제 | Y (admin) |
+```
+
+## 요청/응답 스키마
+
+각 엔드포인트의 요청 및 응답 형식을 정의한다.
+
+**양식:**
+````markdown
+## 요청/응답 스키마
+
+### {메서드} {경로}
+
+**요청:**
+| 필드 | 타입 | 필수 | 설명 |
+|------|------|------|------|
+| {필드명} | {string/number/boolean/...} | {Y/N} | {설명} |
+
+**응답:**
+```json
+{
+  "field": "type — 설명"
+}
+```
+````
+
+**예시:**
+````markdown
+## 요청/응답 스키마
+
+### POST /api/users
+
+**요청:**
+| 필드 | 타입 | 필수 | 설명 |
+|------|------|------|------|
+| name | string | Y | 사용자 이름 |
+| email | string | Y | 이메일 주소 |
+| role | string | N | 역할 (기본값: "user") |
+
+**응답 (201):**
+```json
+{
+  "id": "number — 생성된 사용자 ID",
+  "name": "string — 사용자 이름",
+  "email": "string — 이메일 주소",
+  "role": "string — 역할",
+  "createdAt": "string — ISO 8601 생성일시"
+}
+```
+
+**에러 응답 (400):**
+```json
+{
+  "error": "string — 에러 메시지",
+  "details": "object — 필드별 검증 에러"
+}
+```
+````