# Requirement Delivery

> 接到新需求、要从需求快速走到可交付时使用。先理清再动手,高效落地。

- Skill: `wade-devcode/requirement-delivery` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wade-devcode/requirement-delivery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wade-devcode/requirement-delivery/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Wade-DevCode (https://skillmd.com/u/wade-devcode)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/wade-devcode/requirement-delivery

---


# 接需求提效

## 何时用

- 接到一个新需求或任务，需要快速产出可运行、可演示的成果时。
- 需求描述模糊、验收标准不清晰，担心做完方向不对时。
- 任务较大，不知道从哪里切入、如何拆解时。
- 时间紧张，需要优先打通核心流程、把次要功能后置时。

## 核心规则

### 1. 先澄清再动手

**规则：** 接到需求后，先列出验收标准与边界条件；有模糊之处，先向对方确认，不猜着做。

**为什么：** AI 极容易把"我理解的需求"当成"真实需求"——用户说"做一个导出功能"，AI 默默实现了 CSV 导出，结果对方要的是 Excel；用户说"优化一下性能"，AI 大幅重构了数据结构，结果对方只是想加个分页。这类方向性错误往往要到交付时才暴露，前面所有工时全部作废。

**怎么做：**
- 收到需求后，先不写代码，而是写出 2-4 条验收标准，发给对方确认：
  ```
  我理解这个需求的验收标准是：
  1. 用户点击"导出"按钮后，下载一个 .xlsx 文件
  2. 文件包含当前筛选结果中的所有行，字段顺序与表格列顺序一致
  3. 导出超过 1 万行时有进度提示，不卡死页面
  以上理解是否正确？有没有我遗漏的场景？
  ```
- 列出不确定的边界条件，例如：空列表怎么处理？文件名格式是什么？权限校验在哪一层？
- 确认完成再开始写代码，不要"边做边猜、做完再问"。

---

### 2. 拆成可交付小块

**规则：** 把需求拆成独立可演示的小块；优先打通核心路径（MVP），次要功能后置。

**为什么：** AI 倾向于一口气把"完整方案"全部写完再交付——结果往往是：核心逻辑正确，但周边逻辑（错误处理、边界分支、UI 细节）有缺漏，整体跑不起来，联调阶段才发现问题。拆成小块后，每一块都能独立验证，早发现早修正，整体风险大幅降低。

**怎么做：**
- 拿到需求先画出任务树，识别哪条是核心路径：
  ```
  需求：用户可以通过邮箱注册账号

  核心路径（MVP，优先做）：
  - [ ] POST /api/register 接口，写入 users 表
  - [ ] 返回 JWT token，前端可以登录

  次要功能（MVP 通过后再加）：
  - [ ] 邮件验证流程
  - [ ] 密码强度校验提示
  - [ ] 注册成功欢迎邮件
  ```
- 每块完成后，能独立运行一个最小 demo 或通过一个测试，再进入下一块。
- 不在"核心路径还没跑通"时去完善次要功能。

---

### 3. 复用优先

**规则：** 动手前先找现成的库、模板、或项目内已有代码；不从零造轮子。

**为什么：** AI 在生成代码时有一种惯性——直接写一套新实现，哪怕项目里已经有一模一样的工具函数，或者一个知名库早就解决了这个问题。这不仅浪费时间，还会在代码库里留下重复逻辑，日后维护时产生不一致。

**怎么做：**
- 在写任何工具函数或模块前，先搜索项目内的已有代码：
  ```bash
  # 检查项目内是否已有日期格式化工具
  grep -r "formatDate\|format_date\|dateFormat" src/ --include="*.ts" -l
  ```
- 依赖外部功能时，先查标准库和主流 npm/PyPI 包，再考虑自己写：
  - 日期处理 → `date-fns` / `dayjs`，不自己写 `padZero`
  - HTTP 请求 → `axios` / `httpx`，不自己封装 `XMLHttpRequest`
  - 数据校验 → `zod` / `pydantic`，不自己写 `if typeof x !== 'string'` 链
- 复用项目内已有代码时，读懂它的接口约定再调用，不要复制粘贴后再魔改。

---

### 4. 边做边验证

**规则：** 每完成一块，立即用真实场景自测一遍；不把验证堆到最后。

**为什么：** AI 写完一大段代码后统一"跑一下看看"，是最危险的工作方式。一旦出错，错误来源可能在任何一块代码里，定位成本极高。更常见的情况是：每一块单独看起来都合理，但组合在一起时有隐含的状态依赖或接口不匹配，早测早改成本是后测的十分之一。

**怎么做：**
- 每完成一个函数或接口，立即写一个最小调用验证：
  ```python
  # 写完 parse_config() 后，立刻跑一遍：
  cfg = parse_config("tests/fixtures/sample.toml")
  assert cfg.host == "localhost"
  assert cfg.port == 5432
  print("parse_config OK")
  ```
- 后端接口写完，用 `curl` 或 Postman 打一个真实请求，不等前端联调才发现返回格式不对。
- 发现错误立即修，不要"先记着、做完再统一修"——堆积的 bug 会产生连锁效应。

---

### 5. 给完整交付物

**规则：** 交付时给出代码 + 简短使用说明 + 如何运行，让对方拿到就能直接用。

**为什么：** AI 经常只交付代码本身，对方收到后不知道怎么运行、依赖怎么装、入口在哪里。这种"最后一公里"问题会导致明明功能正确，但对方用不起来，来回沟通消耗双方时间。更严重的情况是：缺少关键的环境变量说明或初始化步骤，对方按自己的理解跑起来，结果踩了隐含的前置条件。

**怎么做：**
- 每次交付时附上一个最小可运行示例：
  ```python
  # 安装依赖
  pip install httpx pydantic

  # 运行
  python main.py --config config.toml

  # 预期输出
  Server started at http://localhost:8080
  ```
- 列出必要的环境变量或配置项（不要假设对方知道）：
  ```
  需要在 .env 中配置：
  DATABASE_URL=postgres://...
  JWT_SECRET=（任意随机字符串，本地开发用 dev-secret 即可）
  ```
- 如果有使用限制或已知问题，在交付说明中直接写出来，不要等对方踩坑后再解释。

---

## 正例 / 反例

### 反例：需求没问清就埋头写，方向全错

**场景：** 用户说"帮我加一个搜索功能"。

```
AI 直接开始写代码：
- 实现了全文检索（基于 ElasticSearch）
- 写了搜索结果高亮逻辑
- 加了搜索历史记录功能
- 两小时后交付

用户反馈：我只是想在下拉框里过滤一下列表，
          本地 filter() 就够了，不需要后端接口。
```

两小时工时归零，方向完全错误。

---

**正例：先列验收标准确认，再动手**

```
收到需求后，先回复：

我理解"搜索功能"的验收标准是：
1. 用户在输入框输入关键词，列表实时过滤显示匹配项
2. 匹配规则：名称字段包含关键词（大小写不敏感）
3. 数据来源：当前已加载到前端的列表，不需要额外请求后端

以上理解是否正确？还是需要后端全文检索？

--- 用户确认：对，就是前端过滤就够了 ---

确认后再写代码（10 分钟完成）：

const filtered = items.filter(item =>
  item.name.toLowerCase().includes(keyword.toLowerCase())
);
```

方向对了，实现反而更简单。

---

### 反例：一次性写完不测，最后全是 bug

```
AI 写完整个用户注册流程（500 行代码）后统一测试：

$ python manage.py test
ERROR: relation "users" does not exist        ← 忘了跑 migration
ERROR: JWT_SECRET not set                     ← 忘了说明环境变量
ERROR: send_email() 参数顺序写反了            ← 接口记错了
FAIL: password hash 验证失败                  ← 用了错误的 bcrypt 参数

4 个独立的错误，交织在一起，定位花了 1 小时。
```

---

**正例：拆成小块，边做边验**

```
拆分任务：

[块 1] 写入 users 表 + 单测
  → 跑通：INSERT 成功，id 返回正确  ✅

[块 2] 密码哈希
  → 跑通：bcrypt.hash / bcrypt.verify 验证一致  ✅

[块 3] 生成 JWT
  → 跑通：curl 拿到 token，jwt.io 解码字段正确  ✅

[块 4] 整合三块，接口联测
  → 一次跑通，因为每块已验证  ✅

整体完成时间反而更短，且每块都有可追溯的验证记录。
```

---

## 自查清单

- [ ] 动手前已列出验收标准，并得到对方确认（或明确记录了自己的假设）。
- [ ] 任务已拆成独立小块，核心路径（MVP）优先，次要功能后置。
- [ ] 动手前已搜索项目内是否有可复用的已有代码或工具函数。
- [ ] 每完成一块代码，已用真实输入跑过一遍，结果符合预期。
- [ ] 交付物包含代码、运行方式、必要的环境配置说明，对方拿到能直接跑起来。
- [ ] 已知的限制或潜在问题已在交付说明中写明，不等对方踩坑后再解释。
- [ ] 没有在核心路径未跑通的情况下去完善次要功能或"顺手优化"其他代码。