AI 辅助编程全生命周期

主题

spec.md ​

来自 cli/templates/level-3/

markdown
---
name: spec
description: >
  需求分析与产品定义。当有新想法、新功能需求或业务需求需要正式化时使用。
  通过苏格拉底提问挖掘真实需求，输出结构化的 spec.md，作为 /plan 的输入。
---

# 需求分析与产品定义

将模糊的想法转化为结构化、经过验证的产品规格文档 `spec.md`，作为后续技术设计（/plan）的输入。

## 步骤

### Step 1: 捕获原始想法

让用户以任何形式表达想法 — 一句话、一段描述、一个竞品参考。不要过早施加结构。

听完后用一句话复述确认：

> "如果我理解正确，你想要 [摘要]。是这样吗？"

### Step 2: 苏格拉底提问 — 挖掘真实需求

#### 5 Whys（追根溯源）

从表面需求开始连续追问"为什么"，直到找到根本问题：

用户："我们需要一个通知系统" → Why? "用户会错过重要更新" → Why? "他们不经常打开应用" → Why? "没有理由回来，除非有变化" → Why? "我们没有主动触达用户的机制" → 根本需求：主动触达系统（通知只是方案之一）


将根本问题呈现给用户，这常常会重新定义整个需求。

#### 6 维度探查（选 3-5 个最相关的问问题，分批进行，每批 2-3 个）

1. **澄清** — "你说的 [X] 具体指什么？能举个例子吗？"
2. **假设** — "我们在假设用户会 [Y]，如果不是呢？"
3. **证据** — "什么数据/反馈表明这是真实问题？影响多少用户？"
4. **视角** — "新用户和老用户体验会有什么不同？"
5. **影响** — "如果不做这个，代价是什么？做了之后有什么连锁反应？"
6. **元问题** — "我们在解决正确的问题吗？有什么能让这个需求变得不必要？"

### Step 3: 清晰度评分

对话结束后，对需求进行 100 分制评估：

Business Context /20 (问题清晰 /7, 目标用户 /7, 成功指标 /6) Functional Clarity /30 (核心功能 /10, 用户流程 /10, 边界情况 /10) Technical Specificity /25 (技术约束 /8, 集成点 /8, 性能需求 /9) Scope Definition /25 (In-scope /10, Out-of-scope /8, 优先级 /7) TOTAL /100


- **≥ 90**：进入 Step 4
- **70-89**：针对低分维度追问
- **< 70**：需要更多对话，回到 Step 2

向用户展示评分和具体差距，例如："你的需求得分 75/100，边界情况（4/10）和性能需求（3/9）需要补充。"

**评分达到 ≥ 90 后才继续。**

### Step 4: 策略探索

不要直接跳到产品定义。先探索 2-3 种实现策略：

策略 A: [名称 — 如"最小可行"] 核心方案：[做什么] 取舍：[得到什么 vs 放弃什么] 工作量：S/M/L/XL

策略 B: [名称 — 如"完整方案"] ...

策略 C: [名称 — 如"平台化"] ...


让用户选择、组合或提出新方向。

**何时跳过**：需求非常明确、方案空间很窄时（Bug 修复、合规要求、有明确规格的直接需求）。

### Step 5: 用户故事与验收标准

为每个核心功能编写用户故事和 Given/When/Then 验收标准：

```markdown
### Story [N]: [标题]
**As a** [用户], **I want to** [行为], **so that** [价值]
**Priority**: P0/P1/P2 | **Complexity**: S/M/L/XL

Acceptance Criteria:
Happy Path:
- [ ] Given [前提], when [操作], then [结果]

Validation:
- [ ] Given [无效输入], when [操作], then [具体错误处理]

Edge Cases:
- [ ] Given [边界条件], when [操作], then [行为]

要求：

  • 每条标准独立可测试
  • 包含具体数值（不是"快速"，而是"200ms 内响应"）
  • 覆盖正常路径、错误路径和边界情况

Step 6: 特性分解与数据/API 设计 ​

特性依赖图 ​

F1 [基础能力] ──→ F2 [核心功能] ──→ F4 [增强功能]
  └──→ F3 [辅助功能] ──→ F5 [集成]

数据模型（当涉及新数据实体时） ​

markdown
### Entity: [Name]
| Field | Type | Constraints | Required | Default |
|-------|------|-------------|:--------:|---------|
| id | UUID | PK, auto | Yes | gen_random_uuid() |
| ... | ... | ... | ... | ... |

API 概要（当涉及新 API 时） ​

markdown
| Method | Endpoint | Description | Auth | Request | Response |
|--------|----------|-------------|:----:|---------|----------|
| POST | /api/v1/... | ... | Yes | {...} | {...} |

Step 7: 多视角审查 ​

从三个视角审查，发现盲点：

  • 工程视角：技术可行性？最难的部分？有更简单的替代方案吗？
  • 用户视角：用户能理解这个功能吗？学习成本多高？
  • 业务视角：ROI 合理吗？和产品战略一致吗？

记录各视角的担忧，写入 spec.md 的风险章节。

Step 8: 生成 spec.md ​

使用下方模板生成 docs/spec.md（或 docs/[feature-name]-spec.md）。

Step 9: 等待确认 ​

IMPORTANT：

  • spec.md 输出后必须等待用户确认，不要自行开始技术设计。
  • 下一步引导用户使用 /plan 进行技术方案设计。

输出模板 ​

markdown
# Spec: [项目/功能名称]

## Clarity Score: [X]/100
| Dimension | Score | Notes |
|-----------|:-----:|-------|
| Business Context | /20 | |
| Functional Clarity | /30 | |
| Technical Specificity | /25 | |
| Scope Definition | /25 | |

## 1. Background & Root Problem

### Surface Request
[用户最初提出的需求]

### Root Problem
[通过 5 Whys 发现的根本问题]

### Why Now
[触发因素 — 事故、反馈、市场变化、战略调整]

## 2. Objectives
- **Primary**: [主要目标 — 具体可衡量]
- **Secondary**: [次要目标]
- **Anti-Goals**: [明确不做的事]

## 3. Target Users

| Attribute | Description |
|-----------|-------------|
| Who | [角色/画像] |
| Context | [使用场景] |
| Current workaround | [现在怎么解决] |
| Pain level | [痛点程度] |

## 4. Strategy Chosen
[选择的策略及原因，备选策略简述]

## 5. User Stories & Acceptance Criteria

### Story 1: [Title]
**As a** ..., **I want to** ..., **so that** ...
**Priority**: P0 | **Complexity**: M

**Acceptance Criteria**:
- [ ] Given ..., when ..., then ...
(Happy path + Validation + Edge cases)

## 6. Feature Breakdown & Dependencies

| ID | Feature | Priority | Complexity | Dependencies | Stories |
|----|---------|----------|------------|--------------|---------|
| F1 | ... | P0 | M | None | S1, S2 |

### Dependency Graph
F1 ──→ F2

## 7. Data Model
[Entity tables with constraints — only if new data entities are involved]

## 8. API Surface
[Method / Endpoint / Description / Auth / Request / Response — only if new APIs are involved]

## 9. UI/UX Notes
- Loading / Empty / Error states
- Responsive / Accessibility requirements

## 10. Risks & Concerns

### Engineering
- [Concern]: [Mitigation]

### User Experience
- [Concern]: [Mitigation]

### Business
- [Concern]: [Mitigation]

## 11. Out of Scope
- [Item] — Reason: [why]

## 12. Open Questions
- [ ] [Question] — Owner: [who]

## 13. Success Metrics
| Metric | Current | Target | How to Measure |
|--------|---------|--------|----------------|
| ... | ... | ... | ... |

Quality Gate ​

进入 /plan 前，以下条件必须满足：

  • [ ] Clarity Score ≥ 90
  • [ ] 根本问题已识别（非表面需求）
  • [ ] 至少 3 条用户故事，每条有 ≥ 3 个验收标准
  • [ ] Scope 边界明确（In-scope AND Out-of-scope）
  • [ ] 至少 2 个可衡量的成功指标
  • [ ] 多视角审查已完成
  • [ ] 用户已审阅并确认

Tips ​

  • 小功能不需要走这个流程 — 改动 < 3 文件的需求直接用 /plan
  • 用户抗拒提问时 — 提供默认值让对方确认："我先假设 X，你觉得不对再告诉我"
  • 需求文档已有时 — 可以跳过 Step 1-2，直接从 Step 3 评分开始

面向个人开发者的 AI 辅助编程工程化方案

基于 Claude Code 构建