zhilv
7e491d4e60
添加 codestable/ 目录，包含项目架构文档、需求文档、 功能设计、问题追踪、参考文档、路线图及工具配置 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3.1 KiB
3.1 KiB
doc_type, description
| doc_type | description |
|---|---|
| requirement-example | 一份好的 requirement doc 长什么样——供 cs-req 起草时参考，也供项目成员扫一眼对齐风格 |
requirement 文档示例
下面这份示例取自 CodeStable 自己的能力（修 bug 时的探索分析流），用来展示一份好的 requirement doc 的语气、结构、颗粒度。新项目做 onboarding 时随包落盘，之后写自己的 requirement 可以直接照着改。
写作要点速查
- 标题直接平铺说这能力是什么，不玩比喻、不起花哨名字。
- 用户故事顶在最前面，每条要能想象出一个具体处境。
- 为什么需要 / 怎么解决 各一段短的，不上课、不展开。
- 边界用列表，至少写一条"它不管什么"。
- 不写实现细节——"通过 X 接口调用 Y 服务"这种挪到 architecture doc。
- frontmatter 的
pitch要去技术化、一句话、读者没上下文也能看懂，以后当宣传词用。
示例正文
---
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 里删掉。