---
name: spec-driven-development
description: "Writes a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code. Invoke when starting a new project, feature, or significant change, or when user says /spec. | 在编写任何代码之前编写PRD，涵盖目标、命令、结构、代码风格、测试和边界。当开始新项目、功能或重大变更时，或用户说 /spec 时触发。"
metadata:
  {
    "builtin_skill_version": "1.0",
    "xingzierai":
      {
        "emoji": "📋",
        "requires": {}
      }
  }
---
# Spec-Driven Development

Write a Product Requirements Document (PRD) before writing any code. Spec first, code second.

## Overview

This skill enforces structured thinking before implementation. Every significant change starts with a spec that defines **what** we're building and **why**, not **how**. The spec becomes the source of truth for acceptance criteria and guards against scope creep.

## When to Use

**Activate this skill when:**
- User says `/spec` or asks to "define" or "plan" a feature
- Starting a new project or significant feature
- Encountering ambiguous requirements
- Before any code change touching more than one file
- When asked to build something that doesn't have a clear spec

**Do not activate for:**
- Trivial one-line fixes
- Bug fixes that don't change behavior
- Already well-specified tasks with acceptance criteria

## Process

### Step 1: Clarify the Goal

1. State the user's request in one sentence
2. Identify the **outcome** (what success looks like), not the **implementation**
3. List known constraints (tech stack, deadlines, compatibility)

### Step 2: Define the Scope

1. **In Scope**: What this feature explicitly includes
2. **Out of Scope**: What this feature explicitly excludes
3. **Boundary conditions**: Edge cases to consider

### Step 3: Write the PRD

Create a `SPEC.md` with these sections:

```markdown
# Feature Name

## 1. Overview
One paragraph describing the feature and its value.

## 2. User Stories
- As a [user type], I want [goal] so that [benefit]

## 3. Functional Requirements
- REQ-1: [Requirement description]
- REQ-2: [Requirement description]

## 4. Non-Functional Requirements
- Performance: [Constraints]
- Security: [Constraints]
- Compatibility: [Constraints]

## 5. API Design (if applicable)
- Endpoint: POST /api/feature
- Request: { ... }
- Response: { ... }

## 6. Data Model (if applicable)
- [Entity]: { fields }

## 7. Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## 8. Out of Scope
- Item 1
- Item 2
```

### Step 4: Review with User

1. Present the draft spec
2. Ask for confirmation or corrections
3. Iterate until user approves

### Step 5: Anchor the Spec

1. Save as `SPEC.md` in the project root or relevant directory
2. Reference it in all subsequent work
3. Any implementation change requires spec update

## Rationalizations

| Excuse | Rebuttal |
|--------|----------|
| "I'll figure it out as I code" | Code written without spec has no acceptance criteria. You'll never know when you're done. |
| "The user just wants it working" | "Working" is undefined without criteria. Spec prevents endless rework. |
| "It's just a small change" | Small changes still need boundaries. Spec prevents feature creep. |
| "I don't have time to write a spec" | Time spent on spec saves 10x time on rework. |

## Red Flags

- User or agent wants to "just start coding"
- No clear acceptance criteria before implementation
- Scope keeps expanding without spec update
- Implementation diverges from stated requirements

## Verification

**Evidence that spec-driven development is working:**

- [ ] `SPEC.md` file exists before any implementation code
- [ ] Spec has explicit acceptance criteria
- [ ] User has reviewed and approved the spec
- [ ] Implementation matches spec
- [ ] Any spec change is documented and communicated
