Spec

Spec

Write a structured specification before any code. The spec is the shared source of truth — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

When to use

• Starting a new project, feature, or significant change.
• Requirements are ambiguous or only exist as a vague idea.
• The change touches multiple files or modules.
• User says "write spec", "create prd", "spec out", "to spec", "写需求文档", "写规格", or "需求文档".

Not for: single-line fixes, typos, or changes where requirements are unambiguous; changes needing design decisions only — use architecture for system design.

Steps

1. Surface assumptions. Before writing any spec content, list what you're assuming (tech stack, auth model, database, target environment). Ask the user to correct before proceeding. Don't silently fill ambiguous requirements.

2. Ask 3–5 clarifying questions where the prompt is ambiguous — problem/goal, core functionality, scope, success criteria. Offer lettered options (A/B/C/D) so the user can respond "1A, 2C, 3B" for quick iteration. Only ask what's actually ambiguous. If the conversation already resolved the ambiguities, skip questions and synthesize directly.

3. Write the spec using the template below. Reframe vague requirements as testable success criteria ("make the dashboard faster" → "LCP < 2.5s on 4G; initial load < 500ms"). For PRD structure, user-story format, Given/When/Then acceptance criteria, and INVEST — load references/prd-patterns.md. For success-criteria frameworks (North Star, AARRR, retention, A/B testing) — load references/metrics-frameworks.md. For feature prioritization (RICE, Kano, MoSCoW) — load references/prioritization.md.

4. Publish. Two layers:

   • docs/PRD.md — project-level requirements, concise (mermaid-heavy), on main. The shared source of truth for the whole project.
   • docs/vX.Y/prd.md — the current version's detailed PRD (user stories, full acceptance criteria, rules, boundaries), on the version branch. Falls back to docs/PRD.md alone for single-version projects. Commit both — they are living documents. Update when decisions or scope change; reference in PRs.

5. User review gate. Ask the user to review the written spec before any implementation. If they request changes, make them and re-verify. Only proceed once approved.

Spec template:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories with verifiable acceptance criteria.]

## Success Criteria
[Project-level "how we know it's done" metrics.]

## Project Structure
[Directory layout with descriptions — where source, tests, docs live.]

## Commands
[Build, test, lint, dev — full executable commands with flags.]

## Code Style
[One real code snippet showing conventions. Naming, formatting, key patterns.]

## Testing Strategy
[Framework, test locations, coverage expectations, which test levels for which concerns.]
Identify test seams — prefer existing seams, use the highest seam possible (the fewer seams across the codebase, the better).

## Boundaries
- Always: [run tests before commits, validate inputs, follow naming conventions]
- Ask first: [schema changes, new dependencies, CI config changes]
- Never: [commit secrets, edit vendor dirs, remove failing tests without approval]

## Non-Goals
[What this feature will NOT include. Makes scope trade-offs explicit.]

## Open Questions
[Unresolved items needing human input.]

Planning the implementation FROM this spec uses Claude Code's built-in plan mode (see engineering-principles §7) — no custom plan skill. The spec is plan mode's input.

Verify

• The spec file exists on disk and is committed to version control.
• It covers all sections: Objective, Success Criteria, Structure, Commands, Code Style, Testing, Boundaries, Non-Goals.
• Success criteria are specific and testable, not vague.
• Boundaries (Always / Ask first / Never) are defined.
• The user has reviewed and approved the spec.

Output: docs/PRD.md (project-level, concise, main) + docs/vX.Y/prd.md (version-level, detailed, version branch). Single-version projects fall back to docs/PRD.md alone.

References

• ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — discipline shared by every skill; §7 covers plan mode for implementation planning.
• ${CLAUDE_PLUGIN_ROOT}/references/product-principles.md — product discipline (need≠feature, outcomes over outputs, say no to good ideas, the real competitor is the workaround).
• references/prd-patterns.md — PRD structure, user stories, Given/When/Then acceptance criteria, INVEST, Non-Goals, success-criteria reframing, anti-patterns.
• references/prioritization.md — RICE, ICE, Kano, MoSCoW, Value×Feasibility matrix, true-need vs false-need filter.
• references/metrics-frameworks.md — North Star metric, AARRR funnel, retention curves, cohort analysis, Hook Model, A/B testing discipline, data-driven loop.