spec-writing（规范编写）

Spec Writing v3.0

Generate comprehensive project specifications with SPEC.md as the core file and optional supplements for reference material.

Core Principle

SPEC.md is always the complete spec. SPEC/ files are optional lookup supplements.

SPEC.md               # Always created, always self-sufficient
CLAUDE.md             # Generated with spec references

SPEC/                 # Optional, created when user agrees
├── api-reference.md  # Lookup: endpoint schemas, request/response
├── sdk-patterns.md   # Lookup: external SDK usage patterns
└── data-models.md    # Lookup: complex entity schemas

Key distinction:

• SPEC.md = Things you READ (narrative, decisions, requirements)
• **SPEC/*.md** = Things you LOOK UP (schemas, SDK patterns, external API details)

Single Adaptive Flow

One interview flow replaces previous Quick/SPEC/DEEP modes:

Interview starts
    ↓
Build SPEC.md progressively
    ↓
Hit reference-heavy topic? ──→ Ask: "Create SPEC/[topic].md for lookup?"
    ↓                                    ↓
Continue interview                  User decides (yes/no)
    ↓
Generate SPEC.md + CLAUDE.md
    ↓
If user said yes → Generate SPEC/[topic].md files

Interview Workflow

Phase 1: Vision & Problem

• Problem statement
• Target users
• Success criteria

Phase 2: Requirements

• MVP features (must-have)
• Out of scope (explicit)
• User flows

Phase 3: Architecture

• System type detection
• Architecture pattern (present 2-3 alternatives with tradeoffs)
• Tech stack with recommendations

Phase 4: Tech Stack Details

• Frontend (if applicable)
• Backend (if applicable)
• Database (if applicable)
• Use multiple choice with recommendations

Phase 5: Design & Security

• Visual design (if frontend)
• Authentication approach
• Constraints & compliance

Supplement Prompts (Mid-Interview)

When hitting reference-heavy topics, ask:

"Your API has 15 endpoints with detailed schemas. Should I: - A) Keep it inline in SPEC.md (shorter reference section) - B) Create SPEC/api-reference.md as a separate lookup file"

Create supplements only for:

• Reference material - Stuff you look up, not read through
• External dependencies - SDK docs, library patterns, third-party APIs

Opinionated Recommendations

Lead with recommended options, allow override:

Which package manager?

- A) bun (Recommended) - Fastest, built-in test runner, drop-in npm replacement
- B) pnpm - Fast, strict dependency resolution, good for monorepos
- C) npm - Universal compatibility, no setup needed
- D) yarn - If team already uses it

Principles:

1. Lead with recommended option + brief rationale
2. Context-aware (desktop app? acknowledge Tauri vs Electron tradeoffs)
3. Acknowledge "it depends" cases (team familiarity, existing codebase)
4. Stay current with ecosystem changes

SPEC.md Structure

# [Project Name]

## Overview
Problem, solution, target users, success criteria.

## Product Requirements
Core features (MVP), future scope, out of scope, user flows.

## Technical Architecture
Tech stack (with rationale), system design diagram, data models, API endpoints.

## System Maps
- Architecture diagram (ASCII)
- Data model relations
- User flow diagrams
- Wireframes (key screens)

## Design System
(If frontend) Colors, typography, components, accessibility.

## File Structure
Project directory layout.

## Development Phases
Phased implementation plan with checkboxes.

## Open Questions
Decisions to make during development.

---

## References
(If supplements exist) Trigger-based links to SPEC/ files.

Connecting SPEC.md to Supplements

When supplements exist, reference them with triggers:

Inline (in relevant sections):

## API Design

**Endpoints overview:**
- `POST /auth/login` - User authentication
- `GET /projects` - List user projects

→ When implementing endpoints, reference `SPEC/api-reference.md` for full request/response schemas.

References section (bottom):

---

## References

→ When implementing API endpoints: `SPEC/api-reference.md`
→ When using Anthropic SDK: `SPEC/sdk-patterns.md`

CLAUDE.md Generation

Agent-optimized pointer file:

# [Project Name]

[One-line description]

## Spec Reference

Primary spec: `SPEC.md`

→ When implementing API endpoints: `SPEC/api-reference.md`
→ When using [SDK/Library]: `SPEC/sdk-patterns.md`

## Key Constraints

- [Critical constraint 1 - surfaced from spec]
- [Critical constraint 2]
- [Out of scope reminder]

## Commands

- `[package-manager] run dev` - Start development
- `[package-manager] run test` - Run tests
- `[package-manager] run build` - Production build

## Current Status

→ Check `SPEC.md` → Development Phases section

Principles:

• Surface critical constraints directly (prevent missed context)
• Trigger-based supplement references
• Short - pointer, not duplication
• Status points to SPEC.md (single source)

Context7 Integration

After tech choices, fetch relevant documentation:

1. resolve-library-id for each technology
2. query-docs for setup guides and patterns
3. Include insights in relevant spec files

Best Practices

Interview Conduct

• Multiple choice: Use AskUserQuestion options, not open-ended text
• 2-3 alternatives: For key decisions, show options with tradeoffs
• YAGNI: Ruthlessly simplify - "Do we really need this for MVP?"
• Supplements on demand: Only offer when content is truly reference-heavy

Output Quality

• Be specific and actionable
• Include code examples for data models
• Reference Context7 documentation
• Keep scope realistic for MVP
• Include system maps (architecture, data relations, user flows)

Reference Files

Templates

• references/output-template.md - SPEC.md structure
• templates/index.template.md
• templates/overview.template.md
• templates/architecture.template.md
• templates/frontend.template.md
• templates/backend.template.md
• templates/design-system.template.md
• templates/api-reference.template.md
• templates/cli-reference.template.md
• templates/data-models.template.md
• templates/security.template.md

References

• references/interview-questions.md - Question bank with recommendations
• references/spec-folder-template.md - Supplement structure guide

Examples

• examples/web-app-spec.md
• examples/cli-spec.md
• examples/api-spec.md
• examples/library-spec.md

Related Commands

• /spec - Generate project specification
• /feature - Generate feature specification
• /design - Generate design system specification
• /sync - Sync spec with codebase changes (git-aware)

Integration with Other Skills

feature-dev

After creating specs, use feature-dev agents:

1. code-explorer - Analyze existing patterns
2. code-architect - Design implementation
3. code-reviewer - Review implementation

frontend-design

Use design specs to implement components following the specification.