@chenguangyao/devflow-kit 0.1.43

package/skills/requirement-analysis/references/scope-negotiation.md

@@ -0,0 +1,162 @@
+# requirement-analysis / scope-negotiation
+
+Scope 的加 / 减 / 改优先级,决策树 + 话术 + 审计留档方式。
+
+---
+
+## 为什么 scope 谈判专门出一份
+
+- requirement-analysis 阶段用户很容易说"再加一个"或"先把 X 挪出去";不处理好会导致:
+  - 加:无限 scope creep,工期失控
+  - 减:核心路径被抽,AC 空洞
+  - 改优先级:F-01 变 F-03,test 和 plan 全部重新映射
+- 决策要**显式**,不要默默改;要**留审计**,不要事后扯皮
+
+---
+
+## 决策树(用户提出要"加一个")
+
+```
+用户:再加一个 <新功能>
+
+Q: 这个新功能还在 proposal.md 的 Problem 范围内吗?
+├─ 是
+│   Q: 加进来后 Recommended level 是否要升?
+│   ├─ 升(L2 → L3)
+│   │   → 提醒用户:"加进来会让复杂度升 L3,deadline 和工作量重估。确认要加吗?"
+│   │      ├─ 确认 → 加到 §3 + 更新 §1 业务背景 + 更新 state.level + 重估 proposal
+│   │      └─ 放弃 → 标记 Out of scope + 记在 §9 Open issues
+│   └─ 不升
+│       → 加到 §3,F-<next-id>,补 AC
+└─ 否(超出 proposal.md 的 Problem)
+    → 拒绝加入本次 requirement
+    → 建议:"这是个新方向,要不要另开一个 slug?(devflow new <new-slug>)"
+    → 在 §9 Risks 里记:"stakeholder X 提议 Y,建议下个迭代做,无 JIRA 跟进风险"
+```
+
+## 决策树(用户提出要"减一个" / "下次做")
+
+```
+用户:F-03 本次先不做,下个迭代
+
+Q: F-03 是否是 P0(proposal 的 Success criteria 依赖它)?
+├─ 是 → 拒绝减
+│   → 话术:"F-03 是 Success criteria 的 #2 的核心,减掉后 Success 无法验收"
+│   → 引导:"要不改 Success criteria?(需要 stakeholder 同意)"
+└─ 否 → 允许减
+    → 动作:
+      1. F-03 从 §3 移到 §9 Risks(标注原因)
+      2. 同时扫 §8 边界是否引用 F-03,同步清理
+      3. 如果有对应 refs(PRD 里写了) → 在 requirement.md 顶部加 note "本次仅实现 F-01/F-02,F-03 移下期"
+      4. 审计:state.audit[] 加条目 type=scope_reduce
+```
+
+## 决策树(用户提出改优先级)
+
+```
+用户:把 F-02 提到 P0
+
+Q: 升/降的依据?
+├─ 业务紧急度变化 → 允许
+│   → 更新 F-02 优先级,重排 §3
+│   → 如果涉及 AC 收紧 → 同步 Round 1 Q&A 新增一行记录原因
+│   └─ 记 audit
+└─ 无明确依据(只是"感觉重要") → 追问
+    → 话术:"这个改动会影响 plan / test,有没有新信息让你觉得它该升?"
+```
+
+---
+
+## Scope 冻结时机
+
+| Phase | Scope 状态 |
+| --- | --- |
+| brainstorm | 液态(随时调整 proposal) |
+| requirement Round 1 | 半液态(可增删改) |
+| requirement Round 2 | 固态(只改实现相关的澄清,业务 scope 冻结) |
+| design / plan / apply | 冻结(任何改动要**回退到 requirement** 修改) |
+| code-review | 冻结 + 任何变更视为 **Path A**(见 code-review escalation-playbook) |
+| verify 及以后 | 冻结 + 任何变更 **下期处理** |
+
+**关键**:Round 2 之后想加 scope → orchestrator 应阻止,除非用户明确走"回退到 Round 1 + 审计"流程。
+
+---
+
+## 审计留档
+
+每次 scope 变更必须在 `§6 Round 1 Q&A` 或 `§7 Round 2 Q&A` 加一行:
+
+| # | 问题 / 触发 | 回答 / 决策 | 影响 |
+| --- | --- | --- | --- |
+| Q10 | 用户:本次要不要加 F-04 导出功能? | 决定:加,Recommended level 不变 | §3 +F-04, §8 +边界 |
+
+同时在 `state.json.audit[]` 记:
+
+```json
+{
+  "type": "scope_change",
+  "action": "add | reduce | reprioritize",
+  "target": "F-04",
+  "reason": "...",
+  "requestedBy": "user",
+  "at": "<ISO>"
+}
+```
+
+---
+
+## 谈判话术模板
+
+### 拒绝加(超出 Problem 范围)
+
+> "听起来是个好想法。不过它和当前 slug 的 Problem('批量发券')目标不同 —— 它更像'优惠券发放历史查询'。
+>
+> 建议:
+> 1. 如果是下个迭代做 → 我在 §9 Risks 里记一条,后续运营来提就有依据。
+> 2. 如果现在就要做 → 另开一个 slug(`devflow new query-coupon-grant`),两边并行。
+>
+> 你倾向哪个?"
+
+### 拒绝减(P0 功能)
+
+> "F-02 是 Problem 的核心 —— Success criteria 的第 2 条'成功率 ≥ 单发水平'必须靠 F-02(逐条风控)才能保证。
+>
+> 如果 F-02 本次不做,Success criteria 需要调整(比如接受'批量场景下成功率 ≥ 95%'),这需要 stakeholder 确认。
+>
+> 要不要先找 @张三 确认?"
+
+### 引导"降级为 Open issue"
+
+> "听起来 F-04 的价值不是立刻就要。考虑:
+> - 记在 §9 Open issues,本次不做,但留一个位置
+> - 如果之后优先级上来,另开 slug
+>
+> 比硬塞进当前 requirement 好 —— 塞进来会让 deadline 失控,AC 也不好立即评估。"
+
+### 升 Level 提醒
+
+> "加进 F-04 后,Recommended level 从 L2 升到 L3(原因:跨服务 + 新增分布式锁场景)。
+>
+> L3 意味着:
+> - tech-spec 要写 ≥2 alternatives + 完整灰度方案
+> - test-spec 要加 e2e + 性能基线
+> - verify 要加 perf 报告
+>
+> 工作量大约 +3 天。接受这个权衡吗?"
+
+---
+
+## 常见谈判陷阱
+
+| 陷阱 | 对策 |
+| --- | --- |
+| "就加一点点,不影响" | 每次加都说"一点点";累积 3 次就变 L3。用"3 条累积规则":累计加 3 次就要强制升 level 重估 |
+| 把 decision 推回给你("你觉得呢") | brainstorm-style 反问,给 2 个选项让用户选 |
+| Scope creep 到 phase 后期才暴露 | Round 2 结束前要求用户"通读一次 requirement.md 并确认",生成 sign-off 记录 |
+| 用"下期做"作为搪塞 | 建议:不是模糊的"下期",而是 "SCRUM-XXX issue + deadline"(没 issue 就开一个) |
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 提了加 / 减 / 改优先级要判断和留档。本文给:决策树 + 话术模板 + 审计格式 + 常见陷阱。requirement-analysis 阶段遇到 scope 谈判时直接套决策树。

package/skills/security-hardening/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: devflow-security-hardening
+description: |
+  devflow-kit 安全加固专项 skill。当改动涉及 L3、安全/支付/隐私/鉴权/回调/文件上传/外部依赖/日志脱敏/OSS/SLS/YAPI token 时触发。
+  接入 code-review 与 verify,补充安全 checklist、敏感信息检查、依赖漏洞、权限绕过、注入、SSRF、XSS、回调验签和日志脱敏证据。
+when_to_use: |
+  L3 默认使用;任何支付、隐私、权限、鉴权、外部回调、文件上传、SQL/NoSQL、OSS/SLS、token/cookie/password、依赖漏洞任务都必须使用。
+---
+
+# security-hardening
+
+安全加固专项 skill。它不把 devflow 变成安全扫描器,但要求高风险改动在 review/verify 中有明确安全结论。
+
+## 触发条件
+
+- L3。
+- 支付、签约、资金、隐私、会员、权限、登录、鉴权。
+- 外部回调、Webhook、redirect、returnUrl、callback。
+- 文件上传、OSS、SLS、对象存储、日志检索。
+- SQL、NoSQL、模板渲染、HTML 富文本。
+- token、cookie、password、secret、accessKey。
+- 依赖漏洞修复。
+
+## 接入点
+
+| phase | 行为 |
+| --- | --- |
+| requirement-analysis | 标出安全/隐私/合规约束和 owner |
+| tech-spec | 写鉴权、验签、脱敏、权限边界、回滚策略 |
+| code-review | 使用 `references/checklist.md` 做安全 review |
+| verify | 按风险补 `test-report.md#security` subsection 或写入 `#self-test` |
+| deliver | 确认报告和 PR 描述不含敏感信息 |
+
+## 最低检查
+
+1. 敏感信息不得进入仓库、日志、报告、PR 描述。
+2. 外部输入必须校验和限制。
+3. 回调/redirect/returnUrl 必须有白名单或签名策略。
+4. 权限检查不能只在前端做。
+5. SQL/NoSQL/模板/命令执行不得拼接未信任输入。
+6. 文件上传必须限制类型、大小、路径和访问权限。
+7. 依赖漏洞修复必须记录漏洞来源和验证。
+
+详细清单见 `references/checklist.md`。
+
+## 输出要求
+
+- `review.md` 中有 security 结论。
+- `verify.md` 中记录安全验证是否完成。
+- 若接受风险,必须写明风险 owner 和原因。
+- 任何安全 bypass 必须有 `--reason` 审计记录或明确人工签收。
+
+## 反模式
+
+- 只说"没有安全问题",没有检查项。
+- 为了调试把 token/cookie/request body 全量写进日志。
+- 回调只校验参数存在,不校验来源或签名。
+- OSS 对象默认公开。
+- 依赖漏洞修复后不跑回归。
+

package/skills/security-hardening/references/checklist.md

@@ -0,0 +1,42 @@
+# security hardening checklist
+
+## 敏感信息
+
+- token、cookie、password、secret、accessKey 不进代码、报告、日志、PR 描述。
+- provider 凭证使用 `${env:VAR}`。
+- 日志中的手机号、身份证号、邮箱、地址做脱敏。
+
+## 鉴权 / 权限
+
+- 后端接口有权限校验。
+- 用户只能访问自己的资源或授权资源。
+- 管理端操作有角色/租户/组织边界。
+- IDOR 风险已检查。
+
+## 输入校验
+
+- SQL / NoSQL / shell / 模板不拼接未信任输入。
+- 文件上传限制类型、大小、扩展名、MIME、存储路径。
+- URL、redirect、callback 有白名单。
+- SSRF 风险已检查。
+
+## 回调 / 支付 / 签约
+
+- 回调验签。
+- 幂等处理。
+- 重放攻击防护。
+- 金额、渠道、订单状态不信任前端。
+- 异步状态有对账或补偿。
+
+## 前端安全
+
+- 用户输入不直接 `v-html` / `dangerouslySetInnerHTML`。
+- URL 参数不直接拼接跳转。
+- 敏感字段不放 localStorage,除非已有安全约定。
+
+## 依赖
+
+- 漏洞来源记录(CVE/Snyk/Dependabot/内部扫描)。
+- 升级影响已验证。
+- major/minor 风险有回滚说明。
+

package/skills/tech-spec/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: devflow-tech-spec
+description: |
+  devflow-kit design 阶段把签收的 `requirement.md` 翻译成**可实施**的 `design.md`(技术方案)。当本次改动会改变"系统能
+  做什么"时,还要写 `delta/<capability>.md` 存下本次的规格增量 —— archive 阶段按 frontmatter
+  `capability: <域>/<能力名>` 合入对应 `devflow/specs/<域>/spec.md`（按业务域分目录）。
+  触发时机:`devflow design [--with-tests] [--with-spec]` 或 `/df:design`;也在
+  code-review 发现 design 级缺陷(Path B)时由 `devflow tech-spec --revise` 重入本 skill 产出
+  design.v2。绝对禁止越过本 skill 直接 plan / apply。
+when_to_use: |
+  requirement 的硬闸全部满足后。L1 可产精简版 design;L2 走标准 11 段;L3 必须含 ≥2
+  alternatives + 完整灰度 / 回滚章节。
+---
+
+# tech-spec
+
+写下"**怎么做**"。上游 `requirement.md` 回答"做什么 / 为谁做 / 怎样算做完";本 skill 回答:
+**系统里哪些组件要动、要怎么动、为什么这么动(alternatives 取舍)、出问题怎么兜底**。
+
+## Step 0：自动查询知识库（必须，在写 design.md 之前）
+
+> 先查 KB 中的历史决策（ADR）、服务契约、已知方案，避免重复设计已解决的问题。
+
+```bash
+# 按本次涉及的能力域查询
+devflow knowledge query "<本次技术改动的核心词，如：order-initializer factory member-type>"
+```
+
+**查询结果处理：**
+- **命中 `架构决策`（历史 ADR）**：在 design.md §备选方案中引用，说明是否沿用或偏离原决策及理由
+- **命中 `接口契约`（服务契约）**：在 design.md 契约定义中引用，确保新契约与历史保持兼容
+- **命中 `服务说明`（服务描述）**：在 design.md 架构影响中引用
+- **命中 `运行手册` / `事故复盘`**：在 design.md 错误处理中引用历史事故教训
+- **无命中**：正常继续
+
+## 前置检查
+
+| 输入 | 必需 | 缺失时 |
+| --- | --- | --- |
+| `requirement.md` 且硬闸通过(每条 F-ID 有 AC、边界 ≥ 4 条、Round 1/2 完成) | 是 | orchestrator 回退到 requirement |
+| Round 2 的"代码侦察结论" | 是(L2/L3);L1 可宽 | 先补侦察再进 |
+| `state.level` | 是 | 缺则按 L2 展开 |
+| 项目 detect(语言 / 框架) | 否(有更佳) | 用于挑选 architectural patterns |
+
+## 产物
+
+编辑 `devflow/changes/<slug>/design.md`。若有规格增量,显式使用 `devflow design --with-spec` 或手动创建 `delta/<capability>.md`。
+
+### design.md 格式规范（对齐 arb 技术方案.md）
+
+```markdown
+# 技术方案：<标题>
+
+> 结构化需求：`devflow/changes/<slug>/requirement.md` | JIRA/URL: <引用>
+
+---
+
+## 一、功能拆解
+
+| 序号 | 功能点 | 改动类型 | 说明 |
+|------|--------|---------|------|
+| C1 | <能力名> | 新增/修改/删除 | <文件 + 核心改动一句话> |
+| C2 | ... | ... | ... |
+
+> C-ID 与 requirement.md 的 F-ID 对应关系：C1→F1, C2→F2（多对多时注明）
+
+---
+
+## 二、技术实现
+
+### C1：<能力名>
+
+**改动文件**：`path/to/file.go`
+
+```go
+// 核心改动示意（伪代码或关键片段）
+```
+
+**实现步骤**：
+1. ...
+2. ...
+
+**契约**（如有接口变更）：
+- Request: `{ field: type, ... }`
+- Response: `{ field: type, ... }`
+
+---
+
+### C2：<能力名>
+
+...（同上结构）
+
+---
+
+## 三、数据层（如有 DDL 变更）
+
+```sql
+-- DDL（幂等，可重入）
+ALTER TABLE xxx ADD COLUMN yyy ...;
+```
+
+---
+
+## 四、关键流程
+
+```
+用户 → 接口入口 → ServiceA → ServiceB → DB
+                          ↘ 异常路径 → 返回错误码
+```
+
+若存在 API 契约变化，必须说明是否同步 YAPI / OpenAPI；若存在跨服务调用、回调、跳转、异步链路，必须设计调用链一致性验证方式，并列出 traceId / requestId / 关键日志检索点(SLS/OSS)。
+
+---
+
+## 五、错误处理 / 事务边界
+
+| 场景 | 处理方式 | 错误码 |
+|------|---------|--------|
+| ... | ... | ... |
+
+---
+
+## 六、兼容性 / 灰度 / 回滚（L2/L3 必填）
+
+- 灰度策略：...
+- 回滚方案：...
+
+---
+
+## 七、备选方案（L2 ≥1，L3 ≥2）
+
+| 方案 | 优点 | 缺点 | 结论 |
+|------|------|------|------|
+| A（选定） | ... | ... | 采用 |
+| B | ... | ... | 放弃，原因：... |
+```
+
+**段落按级别要求：**
+
+| 段 | L1 | L2 | L3 |
+| --- | --- | --- | --- |
+| 一、功能拆解（C-ID 表） | 必 | 必 | 必 |
+| 二、技术实现（每 C-ID 一节） | 必 | 必 | 必 |
+| 三、数据层 | 有变必 | 必 | 必(含容量评估) |
+| 四、关键流程 | 简 | 必 | 必(sequence diagram) |
+| 五、错误处理 / 事务 | 必 | 必 | 必(完整事务边界) |
+| 六、兼容性 / 灰度 / 回滚 | 简 | 必 | 必(灰度步骤 + 回滚预案) |
+| 七、备选方案 | 可略 | 必 ≥1 | 必 ≥2 + trade-off 表 |
+
+完整字段语义、正反例见 [`references/design-template.md`](references/design-template.md)。
+
+## 按语言自动加载 cheatsheet(全语言)
+
+通用模板是架构 / 契约 / 事务 / 灰度的语言无关骨架。每门语言有自己的"工程落地习语",挑 1-2 份一起读:
+
+### 挑选规则(与 code-review 一致)
+
+1. 读 `devflow/config.json` 的 `detect.language`
+2. 看当次改动涉及哪些语言(多语言一起做的 monorepo,每种语言各挑一份)
+3. 同语言内按下表选具体 cheatsheet:
+
+| detect.language | 信号 | 挑选 |
+| --- | --- | --- |
+| `java` | `pom.xml` 含 `spring-boot` + `mybatis` / `*Mapper.xml` | `java-spring-mybatis.md` |
+| `java` | 含 `spring-data-jpa` / `@Entity` 广用 | `java-spring-mybatis.md` 的 §1/§4/§5/§6/§7(跳 §2/§3) |
+| `go` | 任意 | `go.md` |
+| `python` | 任意 | `python.md` |
+| `node` | 含 `vue` | `vue.md` |
+| 其他 | — | 仅用通用模板 + 在 design.md 开头 note `language-cheatsheet: missing` |
+
+详细 cheatsheet 内容与 code-review skill 共享:[`../code-review/references/language-cheatsheets/`](../code-review/references/language-cheatsheets/)。tech-spec 阶段挑同样的 1-2 份一起读,但关注点不同 —— code-review 是"审查时要扫的踩坑习语",tech-spec 是"设计时要提前规避的框架特性"。
+
+## 关键方法论:决策 vs 记账
+
+design.md 不是"代码说明书",它是**决策文档**。字段多不多,不如**决策清不清**。
+
+每个关键设计点要回答:
+
+1. **选了什么**(1 句话)
+2. **为什么选它**(对比 ≥1 备选,说 trade-off)
+3. **什么情况下这个决策会反向**(降级 / 回滚触发条件)
+
+例子见 `references/decision-records.md`,含 ADR-lite 模板(适合 design.md 内嵌使用,也适合抽出来独立存档)。
+
+## 实现细节收敛协议（减少设计后追问）
+
+> **HARD RULE**：tech-spec 阶段必须尽量把实现细节自己收敛掉，不能在 design 完成后把大量代码实现问题甩给用户。
+
+### 谁来决定
+
+| 问题类型 | 谁决定 | 处理方式 |
+| --- | --- | --- |
+| 业务语义 / 验收口径 / 对外承诺 | 用户 / PO | 回 requirement-analysis，一次性批量问清 |
+| 合规、安全、资金、不可逆数据迁移 | 用户 / owner | BLOCKED 或回 requirement-analysis，不能默认 |
+| 外部系统是否支持、接口 owner 是否承诺 | 用户 / owner | 作为 P0 open issue，不能假设 |
+| 代码落点、缓存键、调用链、状态字段、参数透传、渠道枚举、复用哪个 helper | agent | 通过代码侦察 + KB + 现有模式自行选择 |
+| 多个实现都可行且业务效果一致 | agent | 选最贴近现有模式的一种，在 design.md 写 assumption + rejected alternative |
+
+### 默认决策顺序
+
+遇到实现细节不明确时，按以下顺序自动收敛：
+
+1. **沿用现有代码路径**：优先复用当前服务已经使用的 service/helper/factory/channel 字段。
+2. **保持外部契约最小变化**：能后端补齐就不新增前端参数；能兼容旧参数就不 breaking。
+3. **缓存/幂等优先可恢复**：本地缓存 key、幂等 key、状态字段必须能从已有返回或 DB 重新推导。
+4. **多渠道以真实返回为准**：如 `bf/jd`、`pay_channel`、签约码等渠道分支，优先读现有响应字段和枚举，不要求用户再解释代码细节。
+5. **不确定但风险低**：写入 design.md 的 `Assumptions`，并在 tests.md 加验证用例。
+6. **不确定且会改变业务承诺**：停止，回 requirement-analysis 批量提问。
+
+### design.md 必须显式记录
+
+每个实现决策点至少写清：
+
+```markdown
+**Decision**: 采用 <方案>。
+**Evidence**: 代码位置 / KB / 既有模式。
+**Assumption**: <如果有，写明可被测试验证的假设>。
+**Fallback**: 假设不成立时怎么降级 / 回滚 / 改为备选。
+```
+
+### 禁止行为
+
+- 禁止在 design 完成后再问用户"这个字段从哪里取 / 这个渠道走哪个分支 / 要不要查缓存"这类实现细节。
+- 禁止输出"实现时再确认"、"后续开发时判断"、"需要用户补充技术细节"。
+- 禁止带着未决实现问题进入 `test-spec` / `plan`；若确实无法自行收敛，必须回到 requirement-analysis，并一次性列出所有会影响业务承诺的问题。
+
+## 契约设计(§5)
+
+契约是**外部承诺**,改了就要考虑兼容。原则:
+
+- 只 **加字段**(客户端忽略未知字段),不删不改语义
+- 新字段在 DTO 层 **默认可空**,降低迁移负担
+- Breaking change 一律新版本(v2 / breakingVersion header),不要就地改
+- 错误码集中管理,不要散在各 Controller
+
+契约设计的完整方法论(REST / GraphQL / gRPC / 事件)、字段设计原则、版本化策略见 [`references/api-contract-design.md`](references/api-contract-design.md)。
+
+### 契约消费者影响矩阵（必须）
+
+> **HARD RULE**：任何契约变化都必须写"提供方 + 消费方"双向设计。只写后端接口怎么改、不写前端/调用方/轮询页怎么适配，design 不算完成。
+
+必须覆盖：
+
+| 契约变化 | 提供方改动 | 消费方/页面/任务 | 旧依赖 | 新设计 | 兼容/迁移 |
+| --- | --- | --- | --- | --- | --- |
+| `returnUrl` 不再带订单号参数 | 后端生成无参回跳 URL | 前端签约结果/轮询页 | 从 query 读取订单号轮询 | 改为从本地缓存 / 后端状态接口 / bfState 查询 | 老链接兼容读取 query；新链路走新策略 |
+
+设计要求：
+
+- 对每个 request/response/URL/query/status/enum 变化，列出所有已发现消费者。
+- 前端项目同时改动时，必须设计页面状态来源、刷新/回退、无参数直达、老链接兼容。
+- 轮询页必须说明轮询 key 从哪里来；如果 URL 不再携带参数，必须有替代来源（本地缓存、后端状态接口、一次性 state token 等）。
+- 如果消费者不在本次 scope，必须说明为什么不受影响，或回 requirement-analysis 补项目确认。
+- 对无法确认的消费者，不允许写"实现时再看"；必须继续代码侦察或 BLOCKED。
+
+## 事务 / 并发 / 一致性(§8)
+
+最容易出 P0 的地方。常见决策:
+
+| 场景 | 推荐模式 | 备注 |
+| --- | --- | --- |
+| 单库单事务 | `@Transactional`(本地事务) | 默认选择;注意传播行为 |
+| 分布式 / 跨服务 | Saga + 补偿 / TCC / 最终一致 | 设计"补偿/回滚"操作 |
+| 读多写少 + 一致性弱 | 主从读 + 延迟容忍 | 明确 RPO/RTO |
+| 幂等接口 | 唯一键 + Upsert / nonce | 必须设计重复请求的返回值 |
+| 乐观锁 | `version` 列 + CAS | 适合低冲突 |
+| 分布式锁 | Redis/zk 锁 + 超时 | 注意锁放手的兜底(TTL) |
+
+具体 pattern 的决策矩阵与踩坑点见 [`references/transaction-patterns.md`](references/transaction-patterns.md)。
+
+## 灰度 / 回滚(§10)
+
+**硬规则**:L2/L3 的 design.md 必须有可操作的灰度步骤和回滚预案。不允许"上线后观察"这种笼统说法。
+
+完整模板(Feature flag / 灰度阶段 / 指标对照 / 回滚脚本 / 数据迁移双写)见 [`references/rollout-and-rollback.md`](references/rollout-and-rollback.md)。
+
+## Spec Delta（OpenSpec 格式，按需）
+
+> `delta/` 不再默认生成。只有当本次 change 改变系统长期能力、接口契约或业务规则时，才运行 `devflow design --with-spec` 生成 `delta/sample-capability.md`，或手动创建 `delta/<capability>.md`。
+> agent 在写完 design.md 后，若确认有规格增量，**必须**：
+> 1. 修改 frontmatter `capability: <域>/<能力名>`（例：`coupon/grant`、`order/create`）
+> 2. 重命名文件为 `<能力名>.md`（便于阅读）
+> 3. 按 OpenSpec 格式填充真实内容
+> 纯 bugfix / 内部重构 / 测试补充可不生成 delta，并在完成状态里写 `deltaFiles: "none"`。
+>
+> 落盘路径 = `devflow/specs/<域>/spec.md`，同一业务域的多个 Requirement 合并到同一个 spec。
+> 纯 bug fix 且确认无 capability 变更时，删除 sample 文件并在 design.md 注明理由；
+> 但不允许留着空的 sample 文件不处理。
+
+**格式要求（OpenSpec Requirements 风格）**：
+
+```markdown
+## ADDED Requirements
+
+### Requirement: <业务能力名>
+
+系统 SHALL <描述该业务能力对外承诺>。
+
+1. 系统 MUST <约束 1>
+2. 系统 MUST <约束 2>
+3. 系统 SHOULD <约束 3>
+
+#### Scenario: <场景名>
+- **WHEN** <触发条件>
+- **THEN** 系统 MUST <结果>
+- **AND** <补充断言>
+
+## MODIFIED Requirements
+### Requirement: <既有业务能力名>   <!-- heading 必须与 spec 中一字不差 -->
+- ~~旧约束~~
+- 新约束
+
+## REMOVED Requirements
+### Requirement: <废弃业务能力名>
+下线原因 / 时间
+
+## REJECTED Alternatives
+### 备选方案名
+**否决原因**：...
+```
+
+**为什么用 OpenSpec Requirements 风格**：
+
+- `SHALL/MUST/SHOULD` 明确系统承诺，方便评审和验收
+- `Scenario` 直接映射测试用例，比接口字段流水账更接近业务能力
+- 按业务域写入 `specs/<域>/spec.md`，同域能力不会散落成多个文件
+- `REJECTED Alternatives` 保留重要取舍，防止未来重蹈覆辙
+
+详细格式规范见 [`references/spec-delta-conventions.md`](references/spec-delta-conventions.md)（Scenario 写法、接口契约补充写法、heading 对齐规则）。
+
+archive 阶段 `devflow archive` 会自动合入规格真源：workspace 的 `changes/delta/` 与各服务局部 delta 最终合入对应项目仓的 `<repo>/devflow/specs/<域>/spec.md`。`specs/` 不放 workspace；workspace 只保存本次需求过程文件和归档快照。**knowledge deposit 统一写入当前需求 workspace 的 `knowledge/`**，不需要再手动跑。
+
+## 硬闸(Done Criteria)
+
+| # | 闸门 | L1 | L2 | L3 |
+| --- | --- | --- | --- | --- |
+| 1 | 所有 F-ID 在 §4 有对应改动点 | ✓ | ✓ | ✓ |
+| 2 | 所有契约变更在 §5 有条目 | ✓ | ✓ | ✓ |
+| 3 | DDL 幂等 + 可回滚 | ✓ | ✓ | ✓ |
+| 4 | 关键流程 happy + 1 failure path 画出来 | ✓ | ✓ | ✓ |
+| 5 | ≥1 alternative + trade-off 书面化 | — | ✓ | ≥2 |
+| 6 | 灰度 + 回滚步骤可执行 | 简 | ✓ | ✓ |
+| 7 | §9 至少 1 个关键指标 + 告警阈值 | — | ✓ | ✓ |
+| 8 | 所有实现决策点已收敛，或以 Assumption + Fallback 记录并有测试覆盖 | ✓ | ✓ | ✓ |
+| 9 | 不存在"待用户补充实现细节"类 Open issue | ✓ | ✓ | ✓ |
+| 10 | 契约变化已完成消费者影响矩阵，前端/调用方/轮询页适配方案明确 | ✓ | ✓ | ✓ |
+
+未达标 → 继续写;都达标 → 输出 DONE,交给 `plan`(L1) 或 `test-spec`(L2/L3)。
+
+## 反模式(高频翻车点)
+
+- **"实现时再想"**:design.md 空洞到下游没法拆 plan。打回让 reviewer 把决策点逐条列出来问。
+- **把 requirement 抄一遍当 design**:design 是 HOW,不是 WHAT;如果你在 design 写"用户可以 X"就错了 —— 那是 requirement 的事。
+- **Alternatives 全部写"想过但是放弃了"**:alternatives 要有**具体对比维度**(性能 / 开发量 / 风险),不是装样子。
+- **契约改 breaking 不升版**:改现有接口字段语义 → 必须 v2 或显式 breaking 版本号;否则客户端灾难。
+- **只看提供方不看消费者**:例如 `returnUrl` 不再带参数，却没重设计前端签约轮询页。任何 URL/query/response/status 变化都必须追踪消费者和页面状态来源。
+- **DDL 写成一次性脚本**:必须 `IF NOT EXISTS / IF EXISTS`,否则重跑失败。
+- **没写事务边界**:哪些 步骤在一个事务、哪些是独立事务 / 最终一致,必须画清楚;不写 → apply 阶段临时拍。
+- **把实现细节留给用户补**:如"缓存怎么查 / 渠道怎么判 / 签约码哪里取 / returnUrl 带不带参数"。这些默认由 agent 读代码收敛；只有业务承诺变化才回 requirement-analysis。
+- **灰度写成"先放 1% 再放量"一句话**:具体是按 userId hash?按机房?按版本?多久观测?必须明确。
+- **§10 没有回滚预案**:没回滚 = 不敢上线。
+- **Spec delta 的 heading 自创**:`### <heading>` 必须与 `devflow/specs/<capability>.md` 的既有 heading **逐字对齐**,否则 archive 会冲突。
+
+## 完成状态协议
+
+```
+---STATUS---
+result: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+outputs:
+  - devflow/changes/<slug>/design.md
+  - devflow/changes/<slug>/tests.md               # 仅 L3 或 --with-tests
+  - devflow/changes/<slug>/delta/<capability>.md  # 仅 --with-spec 或确认有能力变更
+alternativesConsidered: N
+hasRollbackPlan: true | false
+deltaFiles: ["<capability>.md"] | "none (pure bug-fix, no capability change)"
+nextAction: devflow test-spec (--with-tests/L3) | devflow plan
+---END_STATUS---
+```
+
+## 参考
+
+- [`references/design-template.md`](references/design-template.md) — 11 段完整模板 + 字段语义 + 正反例 + 完整示例
+- [`references/decision-records.md`](references/decision-records.md) — ADR-lite(Architecture Decision Record)模板与写法
+- [`references/api-contract-design.md`](references/api-contract-design.md) — REST/GraphQL/gRPC/事件契约设计原则 + 版本化策略
+- [`references/transaction-patterns.md`](references/transaction-patterns.md) — 事务 / 并发 / 一致性的决策矩阵与坑
+- [`references/rollout-and-rollback.md`](references/rollout-and-rollback.md) — 灰度 / 回滚 / 双写的完整模板
+- [`references/spec-delta-conventions.md`](references/spec-delta-conventions.md) — OpenSpec delta 标记、heading 对齐、冲突预防
+- [`../code-review/references/language-cheatsheets/`](../code-review/references/language-cheatsheets/) — 按语言挑 1-2 份(与 code-review 共享,避免重复维护)