메뉴
当用户提出新需求、口头想法、初步框架，或要求"写个 brief / 需求理解 / 业务分析 / 先理清楚需求"时激活；输出面向开发者的 brief.md，覆盖需求摘要、业务流程、涉及模块与影响面（含概念数据模型，但不到物理 schema 与 how）、风险、待确认问题五章；支持开发者审阅后通过对话迭代修订，直到开发者确认冻结，作为后续 acceptance.feature 生成的输入。若用户已基于 brief.md 提出修改、补充、疑问、回答待确认项，继续用本 skill 做迭代收敛。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | brief-generator |
| description | 当用户提出新需求、口头想法、初步框架，或要求"写个 brief / 需求理解 / 业务分析 / 先理清楚需求"时激活；输出面向开发者的 brief.md，覆盖需求摘要、业务流程、涉及模块与影响面（含概念数据模型，但不到物理 schema 与 how）、风险、待确认问题五章；支持开发者审阅后通过对话迭代修订，直到开发者确认冻结，作为后续 acceptance.feature 生成的输入。若用户已基于 brief.md 提出修改、补充、疑问、回答待确认项，继续用本 skill 做迭代收敛。 |
| when_to_use | 在 flow-router 判为 L2/L3 后，或用户直接要求'写个 brief / 写个需求理解 / 搞清楚业务 / 看看影响哪些模块'时激活，把需求收敛成 brief.md。若用户只是抛出一个尚未分诊的改代码诉求（车道未定），应先经 flow-router 判级——判为 L1 的小改动不进本 skill，直接转 implementation-execution。若用户已拿到 brief.md 初稿继续回答待确认问题、补充范围、修正流程、要求继续完善，也继续使用本 skill。若用户已有冻结 brief 并明确要求'生成 acceptance / 生成验收 / 生成 Gherkin / 生成测试场景'，转 acceptance-generator。 |
本 skill 把开发者的初始需求转化为一份面向另一个开发者的 brief.md。
brief.md 的目标读者是团队成员（包括未来的自己）。读完后应能在脑子里跑通这次需求：
它回答"做什么、边界在哪、影响哪些模块、还有什么没定"，供开发者签字确认需求成立且圈定；它不回答"怎么实现"——how 归 technical-design。
它不是：
technical-design关于数据结构（强制）：凡涉及数据表变更（新增表、增/删/改列、改列语义）或对外消息契约（MQ 消息、关键事件 payload）的需求，brief 必须把变更确定到列级 / 字段级——列出新增表的列清单、改了哪张表的哪些列（含列的业务语义与大致类型）、新增消息的字段清单（字段、必填、来源、用途）。这是界定需求范围与确认数据契约的核心，不下放到
technical-design。仍归
technical-design+ alembic 的，只是更细的物理实现细节：列的精确长度、索引、唯一约束、默认值、外键、迁移顺序与回滚、字段校验规则、类名 / 方法签名。一句话："动哪张表的哪些列、收发什么消息的哪些字段"在 brief 定死；"这些列在库里具体怎么建、怎么迁"留给 TD。
它的核心特性是可迭代。Agent 首次生成后，开发者审阅、提出疑问或修改意见，Agent 把修订写回原章节（而非追加在末尾），反复直到开发者明确说"冻结"。冻结后删除"待确认问题"章节，进入 acceptance-generator。
brief.md 提出修改、补充、疑问acceptance-generatortechnical-designtechnical-design（L3）。technical-design，brief 第 3 章追加一个"最小实现思路"附录，够开发者直接编码即可；复杂到要写方法级方案时，说明该升 L3 走 TD，而非把 brief 撑大。technical-design + alembic。固定为：
.specs/<feature-name>/brief.md
要求：
.specs/ 整目录已 git-ignored，是 feature 临时工作目录；详见 .specs/README.md。.specs/ 目录约定一致。state.yaml（取代旧的手维护 feature_info.md）：
python scripts/acceptance/flow-guard.py init <feature-name> --lane <L2|L3>
phase、各 artifact 的 frozen、verified 等阶段不变量；人类可读的产物清单 / 推荐阅读顺序写入其 notes 字段。不再手维护 feature_info.md。brief.md，先读旧版判断是修订还是覆盖，不允许无说明地重写关键结论。# [需求名] Brief
## 1. 需求摘要
- **做什么**：[1-3 句话描述本次需求要解决的核心问题]
- **为什么做**：[业务动机、问题来源、上游诉求]
- **本次不做**：[明确排除的范围，避免后续扩展]
## 2. 业务流程
### 2.1 主流程图
```mermaid
flowchart TD
A["触发"] --> B["处理"]
B --> C{"判断"}
C -->|是| D["成功路径"]
C -->|否| E["异常处理"]
流程图只画主链路 + 关键异常分支，不要把所有细节塞进图里。
对图中每个关键节点展开：
异常分支单独成段，说明触发条件、影响范围、当前处理策略。
按模块列出，每个模块独立一段。只到影响面与可行性层（how 归 technical-design）。每段回答：
technical-design。关于决策的归属：改变范围 / 用户拿到什么的决策留在本章（未定则进待确认）；纯实现取舍（如异步 vs 同步、MQ vs 轮询的技术选型）下沉
technical-design。
（仅 L2）最小实现思路：L2 不走 TD，本章末追加一段够开发者直接编码的实现要点（复用什么、新增什么链路、状态/数据如何流动）。但仍不写物理 schema / 类名 / 方法签名；复杂到要写方法级方案，说明该升 L3。
| 风险 / 问题 | 触发条件 | 影响 | 当前判断 / 应对方向 |
|---|---|---|---|
| [具体场景] | [何时发生] | [对谁、对什么] | [当前思路或"待确认"] |
不写"需要注意稳定性"、"可能有性能问题"这种泛泛的话。每条要落到具体场景。
仅在迭代期使用。所有问题收敛后，整章删除，不进入冻结版。
| 编号 | 问题 | 为什么影响判断 | 阻塞级别 |
|---|---|---|---|
| Q1 | [具体问题] | [影响哪个流程 / 模块 / 决策] | 阻塞 / 影响范围 / 可后置 |
## 6. 工作流程
### 步骤 1：理解原始需求
- 保留用户原话的关键信息
- 用 1-3 句整理成开发者能理解的描述
- 提炼核心目标、范围、非目标
- 标出明显缺失的信息
### 步骤 2：读取项目上下文
按需求关键词，最小化探索：
- README、已有同业务域的 brief / technical_design
- 相关模块目录、入口文件、状态枚举、消息契约
- 公共契约（`docs/api/**`、`docs/internals/naming_conventions.md` 等）
不做完整代码审查，**只读到能支撑模块草图为止**。不要把"读到了什么文件"写成独立章节，转化为对模块归属、复用边界的具体判断。
### 步骤 3：生成 brief 初稿
按模板 5 章生成。原则：
- 第 2 章业务流程要覆盖主链路 + 关键异常
- 第 3 章核心模块要写透实现思路（位置、职责、复用、新增、决策）
- 第 4 章风险写具体场景
- 第 5 章把所有不确定的、影响后续决策的问题列出
### 步骤 4：迭代收敛
进入开发者审阅—Agent 修订循环：
1. 把初稿展示给用户。
2. 默认聚焦"待确认问题"中 1 个最阻塞的问题向用户提问；同时罗列完整待确认清单。
3. 用户回答 / 提出修改 / 指出错误后：
- **读取当前 brief.md**（不要凭记忆）
- 把确认信息**回写到正文对应章节**（摘要 / 流程 / 模块 / 风险）
- 把已确认的问题从"待确认问题"删除
- 如果用户回答引入新问题或与旧结论冲突，把冲突加入"待确认问题"并标注来源
4. 不在文档中保留"问答记录"、"迭代记录"等过程章节。
5. 持续直到：
- 用户明确说"冻结" / "OK 这版可以" / "进入下一阶段"
- 或所有阻塞性问题已收敛
### 步骤 5：冻结
冻结时：
1. 删除"待确认问题"章节（如果还有非阻塞性的，需用户确认后保留或删除）
2. 回写 `state.yaml`：把 `artifacts.brief.frozen` 置为 `true`，`phase` 推进到 `acceptance`。冻结是被记录、被校验的显式动作——下游 `acceptance-generator` 会用 `flow-guard.py` 校验本字段。
3. 告知用户下一步：进入 `acceptance-generator` 生成 acceptance.feature
## 7. 输出质量标准
合格的 `brief.md` 必须做到：
- 另一个开发者读完不需要追问就能进入下一阶段
- 业务流程能在脑子里跑通，含关键异常
- 每个模块都有"位置 + 职责 + 复用/新增 + 触碰契约 + 关键数据结构 + 不确定性"
- **涉及数据表 / 对外消息契约变更的，已给出列级 / 字段级清单**（动哪张表的哪些列、收发什么消息的哪些字段）——这是冻结的硬门槛
- 风险落到具体场景，不是泛泛的"注意稳定性"
- 没有任何模糊措辞（"按需"、"适当"、"完善"、"相关逻辑"）
- 不含 skill 内部机制说明、状态元信息、问答过程记录
不合格的信号：
- 篇幅过短，模块章节只有 1-2 行
- 流程描述跳跃，关键步骤缺失
- 模块章节只写"做 X"，没写"在哪里、复用还是新增、触碰哪些契约、有无不确定"
- **涉及表变更 / 消息契约却只写概念级、没落到列级 / 字段级清单**（缺这一项不得冻结）
- 越界写了纯物理实现细节（索引 / 唯一约束 / 默认值 / 外键 / 迁移顺序 / 回滚）、类名、方法签名等 how（列级变更清单与 L2 最小实现思路除外）
- 风险表用泛泛措辞
- 出现"用户体验"、"系统应正确处理"等无法验证的描述
## 8. 与其他 skill 的衔接
- **进入前**：`flow-router` 判为 L2/L3，或用户直接要求写 brief（L1 小改动不进本 skill，由 flow-router 直转 implementation-execution）
- **车道差异**：L3 的第 3 章到影响面 + 表/消息列级契约（更细物理实现由 TD 承接）；L2 跳过 `technical-design`，第 3 章含"最小实现思路"附录，冻结后直接进编码
- **冻结后**：转入 `acceptance-generator` 生成 Gherkin 验收契约
- **不允许**：未经冻结直接跳到 `technical-design`；涉及表/消息变更却没在 brief 定到列级 / 字段级就冻结；在 brief 阶段写纯物理实现细节（索引/约束/迁移顺序）或类名/方法签名等代码层 how（列级变更清单与 L2 最小实现思路除外）
契约治理三件套的「值层」。核对同一个物理契约值（MQ topic/group、OSS bucket、消息字段名/别名、内部 HTTP 路径等）在 .env/.env.example/代码生效点/Java 对端多处是否逐字相等，找出配置漂移与死值，防止消息收不到/文件取不到。本 skill 只比对「同一个值在多处是否一致」，不判断结构/语义是否破坏对端（那是结构层，转 contract-guard），也不改文档。
指导 LLM 如何使用 toLink-Rag 项目的 MQ 消息中台进行消息收发、定义新消息类型以及处理多厂商适配逻辑。
当用户认为当前模块代码实现完毕，且当前分支应为 dev，需要从 dev 基于当前修改创建规范分支、提交并发起合并到 dev 的 GitHub PR 时使用；也用于发布收口，即直接创建 dev -> master 的 release PR，不新建 release 分支。适用于“从 dev 新建分支”“把当前修改提 PR”“实现完成创建 feature/refactor 分支并 PR”“发布新版本”“dev 合并 master”等交付收口场景。本 skill 是交付链终点，并在建分支/提 PR 前执行收口门槛：测试未过、契约文档失同步、acceptance 未提升者拒绝收口。
当用户要求把需求、功能、技术方案、架构改造、故障复盘、项目治理实践或实现过程写成博客/技术文章时必须使用；尤其适用于“写一篇博客”“生成技术博客”“把这个需求写成文章”“根据这个功能写博客”“把项目实现讲清楚”等请求。使用时要基于用户给出的需求和 toLink-Rag 当前仓库的真实代码、文档、契约、配置与测试证据完成分析，默认输出 Markdown 到 `.specs/blog/《博客名称》.md`。文章须采用「少量
把项目里已有的内部组件（如 MQ 中台、解析 pipeline、缓存层、对象存储）抽象成一份「项目自有 skill」，让 AI 每次接入都自动复用该组件的架构边界与约定。读组件真实代码，提炼「架构定位 / 职责边界 / 已落地清单 / 扩展点 / 红线」五要素，按统一原型生成 SKILL.md，登记到 .ai/skills/README.md 注册表并跑校验。
当用户要提 issue、登记 bug、记录新需求时使用；自动识别所属项目，生成结构化 issue 内容，先在 Linear 建主记录、再在 GitHub 建镜像，并双向回链。用户说"提个 issue""记一下这个 bug""把这个需求登记一下""同步到 Linear 和 GitHub""别再依赖 Linear 自动同步"时都应触发，即使没有明确说出"Linear"或"GitHub"。