# Sdd Design > sdd-design - Skill: `sc30gsw/sdd-design-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add sc30gsw/sdd-design-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/sc30gsw/sdd-design-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: sc30gsw (https://skillmd.com/u/sc30gsw) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/sc30gsw/sdd-design-2 --- # sdd-design **Slash command**: `/sdd-design ` **Purpose**: Create `design.md` by delegating to the `/ecc:plan` skill for architecture and step planning, then merging output into the project's design template. --- ## Prerequisites - `.claude/specs//requirements.md` must exist (run `/sdd-requirements` first) - `.claude/specs//source-notion.md` may optionally be present for additional context --- ## Steps ### 1. Read spec inputs ``` .claude/specs//requirements.md (required) .claude/specs//source-notion.md (optional) ``` Extract: - All REQ-XXX IDs and their acceptance criteria - Non-functional requirements (performance, security, accessibility) - Scope boundaries (in-scope / out-of-scope) ### 2. Invoke `/ecc:plan` Call the `/ecc:plan` skill with the feature context derived from requirements.md. Prompt framing for `/ecc:plan`: ``` Feature: Context: Next.js 16 / React 19 / TypeScript frontend. - UI: Mantine 9 + Tailwind CSS - Server state: SWR via useAspidaSWR - Client state: Jotai atoms - URL state: nuqs - API client: aspida + up-fetch wrapped in features/*/api/ - Validation: Valibot schemas in features/*/schemas/ - Testing: Vitest + MSW (integration-first), Playwright (E2E) - Linting: oxlint (no interface, no relative imports, no default export outside pages/) Requirements summary: Produce: architecture decisions, file structure, component hierarchy, state management plan, API integration plan, test strategy. ``` **`--mode standard`**: Present the `/ecc:plan` output to the user. Allow the user to review, comment, and guide design interactively before proceeding. Incorporate feedback before scaffolding. **`--mode auto`**: Run `/plan` autonomously. Produce `design.md` directly, then append a plain-language "Auto-Design Summary" section at the top of the file for non-engineer reviewers to confirm before implementation starts. ### 3. Scaffold `design.md` from template Copy the template at `.claude/skills/sdd-design/templates/design.md` to: ``` .claude/specs//design.md ``` ### 4. Merge `/plan` output into design sections Fill every section of the template using the `/plan` output and your own analysis: | Template section | Source | | ----------------------- | --------------------------------------------------------------- | | Overview | requirements.md § Scope + /plan summary | | Architecture diagram | /plan architecture decisions → Mermaid | | File Structure Plan | /plan file list → mapped to features/ layout | | State Management | /plan decisions → cross-checked with state responsibility table | | API layer | /plan API plan → aspida endpoint patterns | | Component hierarchy | /plan component breakdown → Mermaid diagram | | Error handling strategy | /plan error handling + better-result patterns | | Test strategy | /plan test plan → cross-checked with Testing Trophy targets | ### 5. Add traceability links Every section must end with: ``` Satisfies: REQ-XXX, REQ-YYY ``` If a section satisfies no requirements directly, write: ``` Satisfies: ``` --- ## State Management Reference Use the following table from `.claude/rules/web/swr-jotai.md` when making state decisions: | State type | Tool | Location | | ------------ | ------------------ | --------------------------------------- | | Server state | SWR (useAspidaSWR) | `features/*/hooks/use-*.ts` | | Client state | Jotai | `features/*/stores/*.ts` | | URL state | nuqs | `features/*/hooks/use-*-query-state.ts` | | Form state | @mantine/form | `features/*/components/*-form.tsx` | **Do not duplicate server state in Jotai.** --- ## API Layer Reference Endpoint calls follow the aspida pattern from `.claude/rules/web/api-client-aspida.md`: ```typescript // GET /api/v1/resource apiClient.api.v1.resource.$get({ query: { page: 1 } }) // POST /api/v1/resource apiClient.api.v1.resource.$post({ body: { resource: {...} } }) // DELETE /api/v1/resource/:id apiClient.api.v1.resource._id(id).$delete() ``` Mutations must be wrapped in `Result.tryPromise` with `catch: toApiError` (alphabetical key order). --- ## Output ``` .claude/specs//design.md ``` --- ## Phase Gate **Next skill after design is always `sdd-tasks`, never `sdd-review-plan`.** `sdd-review-plan` requires `tasks.md` and runs only after `/sdd-tasks`. Use the same gate for the initial write and for any later revision to `design.md`. ### Initial completion ``` == PHASE COMPLETE: sdd-design == Artifact: .claude/specs//design.md Summary: - Architecture decisions recorded with Mermaid diagrams - File structure mapped to features/ layout - State management decisions documented per SWR/Jotai/nuqs table - API layer patterns specified using aspida conventions - All sections include Satisfies: REQ-XXX traceability links ⏸ WAITING FOR CONFIRMATION Next: CONFIRM sdd-tasks (run /sdd-tasks — task breakdown) Or: describe further design changes ``` ### After user-requested revisions When the user asks to change sections of an existing `design.md` (do not treat this as plan review): ``` == DESIGN REVISED == Artifact: .claude/specs//design.md（更新箇所: ） Summary: - ⏸ WAITING FOR CONFIRMATION Next (recommended): CONFIRM sdd-tasks → /sdd-tasks - Required if tasks.md is still empty or predates this revision - Re-run tasks when file structure / API / component plan changed materially Optional: CONFIRM sdd-review-plan → only after tasks.md exists AND user wants plan review without regenerating tasks Or: describe further design changes Do NOT recommend CONFIRM sdd-review-plan as the default next step after design-only work. ``` ### If `tasks.md` already exists If design changed materially and `tasks.md` was generated from the old design: 1. Tell the user tasks may be stale. 2. Recommend `CONFIRM sdd-tasks` to regenerate (or `/sdd-tasks ` after confirm). 3. Only after an up-to-date `tasks.md` exists, `CONFIRM sdd-review-plan` is valid.