ql-link/linkrag-service/brief-generator

Brief Generator

目标

把原始需求整理成面向开发者的 brief.md。brief 只回答"为什么做、做什么、不做什么、业务怎么跑、涉及哪些模块、风险是什么"，不到代码实现层。

输出位置

.specs/<需求名>/brief.md
.specs/<需求名>/feature_info.md

若目录已存在 brief.md，先读旧版判断是修订还是覆盖，不允许无说明地重写关键结论。

必读

1. AGENTS.md
2. project_info.md
3. 与需求相关的 internals/api/ops 文档
4. 相关 Controller / Service / Entity / Mapper / 组件入口
5. 同业务域已有 brief / acceptance / technical_design（若存在）

brief 结构

# <需求名> Brief
 
## 1. 需求摘要
-做什么
-为什么做
-本次不做
 
## 2. 业务流程
### 2.1 主流程图（Mermaid）
### 2.2 流程详解（主链路 + 关键异常分支）
 
## 3. 核心模块与实现思路
按模块说明：位置、职责、复用能力、新增能力、上下游关系、关键决策。
 
## 4. 风险与不确定性
| 风险 / 问题 | 触发条件 | 影响 | 当前判断 / 应对方向 |
 
## 5. 待确认问题
仅迭代期保留；冻结时整章删除，或由用户确认保留非阻塞项。

工作流程

步骤 1：理解原始需求

提炼核心目标、范围、非目标，标出明显缺失的信息。保留用户原话中的关键约束，不要丢失细节。

步骤 2：读取项目上下文

按需求关键词最小化探索：读相关模块入口、已有同业务域产物、公共契约文档。不做完整代码审查，读到能支撑模块草图为止。

步骤 3：生成 brief 初稿

按模板 5 章生成。第 3 章核心模块要写透（位置、职责、复用、新增、关键决策），第 4 章风险落到具体场景，第 5 章把所有不确定的问题列出。

步骤 4：迭代收敛

进入用户审阅循环：

1. 展示初稿，优先聚焦"待确认问题"中最阻塞的 1 个问题追问用户。
2. 用户回答或提出修改后：

• 先读取当前 `brief.md`（不凭记忆）
• 把确认信息写回原章节（摘要/流程/模块/风险），不追加在末尾
• 把已确认的问题从"待确认问题"删除

1. 持续直到用户明确说"冻结"或"可以了"。

步骤 5：冻结

1. 删除"待确认问题"章节（若有未决非阻塞项，需用户确认后保留或删除）。
2. 更新 feature_info.md：状态改为 brief 已冻结。
3. 告知用户下一步：进入 acceptance-generator。

质量标准

合格的 brief.md 必须：

• 另一个开发者读完不追问就能进入下一阶段
• 每个核心模块都有"位置 + 职责 + 实现思路 + 关键决策"
• 业务流程覆盖主链路 + 关键异常
• 风险落到具体场景，不写"注意稳定性"等泛泛措辞
• 没有"按需处理"、"适当判断"、"相关逻辑"等模糊表达

不合格的信号：

• 模块章节只有 1–2 行，没有实现思路
• 流程描述跳跃，关键步骤缺失
• 风险表用通用措辞
• 出现接口字段、表结构、类名、方法签名等代码层细节