# Specful Design

> Use when writing or updating a Specful Design: documenting how a subject of the system works, or connecting a Design to the Requirements it satisfies.

- Skill: `unkos-dev/specful-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add unkos-dev/specful-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unkos-dev/specful-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: unkos-dev (https://skillmd.com/u/unkos-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/unkos-dev/specful-design

---


# Writing a Specful Design

A Design describes how a subject of the system works now, written as though it has always worked this way. It is not a
Requirement (what the software must do) and not an ADR (why a decision was made); if the change is about what or why,
load `specful-requirement` or `specful-adr` instead. History and transitions never appear in the prose: a transition is
a plan, and what used to be true is Git history.

## Workflow

1. Start at `docs/specs/index.md` and follow the scope indexes to the subject's module. Read the neighbouring Designs
   and the Requirements they satisfy before writing.
2. Scaffold with `specful new design --title <TITLE> --scope <SCOPE>`. Never hand-allocate an identifier; the command
   owns the counter.
3. Complete the placeholders. Declare the Requirements the Design `satisfies` and cite governing ADRs through
   `governed-by`, naming only the ADR whose rationale this subject embodies, never a related or organising decision such
   as the decision to adopt a convention, and omit the field when that record does not exist in the profile. Describe
   the subject as it is, at the level a maintainer needs to change it safely; decision rationale belongs in an ADR, not
   here. More information is optional and is removed completely when it adds nothing; it never restates a `satisfies` or
   `governed-by` edge as a link, since `specful show` already renders those.
4. Run `specful index`, then `specful validate`; commit the regenerated views with the change.
5. Mechanical validation does not judge substantive quality. Use `specful-review` when the adopting repository requires
   substantive review or the user asks for it.

For the full Design profile and field-by-field guidance, see <https://unkos-dev.github.io/specful/>.