zhilv
2a6732ffe7
Bug修复: - GetWorkList 使用了错误的 RecordType (RecordStudy→RecordWork) - AllRecord handler 返回错误的分页信息 (page硬编码1, pageSize用RecordsCount) - CourseParse creditNode nil panic (加nil检查) - WebSocket CheckOrigin 安全漏洞 (release模式限制为同源) - math/rand 可预测 (替换为 crypto/rand) - GetDiscussList 未实现 (补全实现, 移除重复路由) 其他: - 接入 CodeStable 工作流体系 (codestable/ 骨架 + AGENTS.md) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
89 lines
3.1 KiB
Markdown
89 lines
3.1 KiB
Markdown
---
|
||
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 里删掉。
|