---
doc_type: requirement-example
description: 一份好的 requirement doc 长什么样——供 cs-req 起草时参考，也供项目成员扫一眼对齐风格
---

# requirement 文档示例

下面这份示例取自 CodeStable 自己的能力（修 bug 时的探索分析流），用来展示一份好的 requirement doc 的**语气、结构、颗粒度**。新项目做 onboarding 时随包落盘，之后写自己的 requirement 可以直接照着改。

---

## 写作要点速查

- **标题直接平铺**说这能力是什么，不玩比喻、不起花哨名字。
- **用户故事顶在最前面**，每条要能想象出一个具体处境。
- **为什么需要 / 怎么解决 各一段短的**，不上课、不展开。
- **边界用列表**，至少写一条"它不管什么"。
- **不写实现细节**——"通过 X 接口调用 Y 服务"这种挪到 architecture doc。
- **frontmatter 的 `pitch`** 要去技术化、一句话、读者没上下文也能看懂，以后当宣传词用。

---

## 示例正文

````markdown
---
doc_type: requirement
slug: issue-flow
pitch: 修 bug 时先让 AI 探索和分析，再动手改
status: current
last_reviewed: 2026-04-21
implemented_by:
  - arch-cs-issue
tags: [debug, ai-assist]
---

# 修 bug 时先探索和分析

## 用户故事

- 作为一个刚接手别人代码的人，我希望把报错直接丢给 AI，它告诉我根因在哪，而不是自己翻三个文件摸调用链。
- 作为一个被线上问题打断的开发，我希望 AI 帮我收窄嫌疑范围，而不是自己从 git log 一条条比对。
- 作为一个只记得"点那个按钮就白屏"的人，我希望 AI 反过来问我几个问题把现场补清楚，而不是让我自己想该给它什么信息。

## 为什么需要

修 bug 的难点不在改代码，在定位。线索通常零碎（一段报错、一个截图、一句口述），从这点信息摸到真正的根因，往往要先自己耗掉半小时。对不熟的模块、对新接手的人，这段成本更高。

## 怎么解决

先让 AI 读现场——日志、代码、git 历史——交叉验证之后讲清楚"哪里坏了、为什么坏、改动会影响什么"。人确认过再动手改，改完验证。

## 边界

- 不主动扫 bug，得你先感知到异常给它入口。
- 线索实在不够时它会反问你补现场，而不是瞎猜。
- 不处理"还没想清楚要做什么"——那是需求 / 设计的事。
````

---

## 反面样例（不要这样写）

这几种写法 AI 很容易默认写出来，都是典型"翻车"：

**语气像在上课**

> 本能力旨在通过智能化的探索与分析机制，为开发者提供高效的缺陷定位解决方案……

改成"修 bug 的难点不在改代码，在定位"。

**标题玩比喻**

> 让 AI 当你修 bug 时的第一个读者

改成"修 bug 时先探索和分析"。

**用户故事太抽象**

> 作为用户，我希望系统好用。

删掉。用户故事必须能想象出具体处境。

**把实现细节塞进来**

> 通过调用代码检索服务和 Git 日志分析模块，对报错日志进行上下文推理……

这是 architecture doc 的事，从 requirement 里删掉。