mini-spec: Skill for Claude Code

Minimap

How a mini-spec project is laid out, so you can find your way around it — read it, search it, follow a clue from any layer to the others. This is the model, not the process. Load /minimap to navigate; load /mini-spec to maintain (it loads this skill underneath).

Design docs first — not code

When understanding a feature or planning a change, start with design/design.md and the relevant CRC cards/sequences before using code-exploration tools (grep, symbol search, reading source). Design docs are the project index — they show component relationships, responsibilities, and code-file mappings more efficiently than reading code. Drop into code-level tools only after the design docs have oriented you. And when the project keeps a root spec index (below), read that first of all — it maps every spec in one file, so you orient without grepping the specs/ tree.

The three levels

specs/                # Human intent — current state, in the user's own words
  migrations/         # In-flight migrations — temporary, moved on completion
    complete/         # Completed migrations, numbered in landing order
design/               # AI translation — requirements.md, crc-*, seq-*, ui-*, test-*, manifest-ui.md
docs/                 # user-manual.md, developer-guide.md
src/                  # Code with traceability comments

(src/ stands in for the project's code root, whatever it's named.)

Specs are the human's voice — what the system should do, in natural language, organized by feature area. Intent, not implementation. For libraries, API signatures live in specs because they are the contract. Most specs are per-feature (one spec, one capability). A second kind, summary specs, indexes existing behavior along a cross-cutting axis without adding behavior of its own (below).

Design is the AI's translation of specs into buildable structure. requirements.md extracts testable statements; CRC cards assign responsibilities to components; sequences show how components interact.