AI Coding Kit

主题

📄 本页由源文件 skills/dev-flow/references/drift-handling.md 自动投影生成（单一权威源）。请勿直接编辑本页。

需求漂移处理子流程 ​

来源：从 references/working-context.md 拆出（v1 创建 2026-05-19，独立文件 2026-05-19） 加载触发：仅在 references/doc-sync-rules.md §路由分流 命中「内部需求/方案漂移」分支时按需加载，普通创建/更新工作上下文场景不需要加载本文件。 反向引用：references/working-context.md、references/doc-sync-rules.md、SKILL.md、references/_index.md、../tech-doc/config/triggers.yaml

设计意图 ​

用户在 dev-flow 推进中常通过沟通获取澄清结论，这些「带外信息回流」必须强制刷新工作上下文，否则 AI 会基于过时上下文继续编码，导致已写代码与最新需求漂移。

与 references/doc-sync-rules.md 的关系 ​

doc-sync-rules 负责「外部文档变更」的同步（文档平台/Figma/protobuf），本子流程负责「内部上下文与已写产物」的对账。两者由 doc-sync-rules.md §路由分流 互相调度，单一权威源不重复。

触发条件 ​

由 references/doc-sync-rules.md §路由分流 路由进入，触发信号包括：

  • 用户消息命中 doc-sync-rules.md §B/C/D 触发关键词（沟通结果回流 / 需求方案否定 / 澄清式调整）
  • AI 在编码前自检发现工作上下文「需求/计划/范围」与最近 5 轮用户输入存在语义冲突

模式豁免：mode: micro-fix 时跳过本子流程（任务规模 ≤3 行改动，沟通澄清场景几乎为零，强制反而打扰）。

显式命令触发（推荐） ​

用户输入 dev:fix --drift [描述] 直接触发，跳过 §B/C/D 关键词匹配判定。AI 收到此命令后无需调用 doc-sync-rules.md §路由分流，直接加载本文件 §三 三步动作执行。

三步固定动作（禁止跳过） ​

步骤 1：静默对账（≤15 秒） ​

读取以下区块的当前内容，与用户最新输入做语义 diff：

对账对象区块名关注点
业务目标## 需求 / ## 需求理解（最终定稿）用户故事、不做边界
执行计划## 计划步骤清单、不做什么
影响范围## 范围文件清单、上下游影响
已写代码（仅 phase=coding/integration）## 编码进度细节已改文件 + 实际状态

步骤 2：输出「漂移摘要 + 决策选项」（强制交互） ​

输出格式（≤15 行，必须先表格再 ask_followup_question，遵循 AI 行为规范「交互式选项一致性规则」）：

markdown

## 🔄 检测到需求漂移

**变更点**：
- 原：{旧描述}
- 现：{新描述}

**影响范围**：
- 工作上下文区块：{## 需求 / ## 计划 / ## 范围 / ## 约束与决策} 中的 N 个需要刷新
- 已写代码：`{相对路径}` L{行号} 可能需要 {撤销 / 调整}
- 外部文档：{技术方案文档 / devlog} 是否需要更新正文（非仅追加备注）

| 选项 | 含义 |
| --- | --- |
| ① 全部按新需求刷新（推荐） | AI 同步刷新工作上下文 4 区块 + 标记旧决策 + 更新 文档平台 正文 + 列出已写代码回滚清单 |
| ② 仅记录到 ## 约束与决策 | 主区块暂不动，适合「待最终确认」场景 |
| ③ 我先回答 AI 的澄清问题再决定 | 进入交互式澄清问答 |
| ❌ 误判，继续原方案 | 取消本次漂移处理 |

步骤 3：执行刷新（用户选 ① 后） ​

强制执行项：

  1. ## 约束与决策 追加一行（带时间戳，复用既有删除线规范，详见 references/working-context.md § 字段说明 中「约束与决策」行）：
markdown

- 2026-05-19 14:30 [需求漂移] 与产品 IM 沟通后调整：~~原 X~~ → 现 Y。影响 ## 计划 §2 / ## 范围：`{相对路径}`
  1. 刷新主区块：
  • 旧内容用 ~~删除线~~ 包裹（不删除，保留可追溯性）
  • 新内容紧跟在删除线后追加
  • 区块顶部加一行 > 🔄 最近一次刷新：{YYYY-MM-DD HH:mm}（需求漂移）

2.1 重写「当前执行方案」唯一视图（强制，本子流程的核心动作） ​

设计意图：解决多次需求变更/迭代后，AI 在 ## 需求 / ## 计划 / ## 约束与决策 三处散落的最新结论中读错或遗漏，导致编码偏离最新需求的问题。每次漂移后必须把"当前要做什么"重新打包成一份完整视图，作为编码前的唯一权威源。

操作：在 ## 需求 章节末尾重写（而非追加）以下子区块——若已存在则整体替换，旧版搬入「历史版本」表格保留 1 行摘要：

markdown

### 当前执行方案（v{N}，定稿于 {YYYY-MM-DD HH:mm}，关联 CR-{X}{, CR-Y}）

> ⚠️ AI 编码前必读：本节是当前唯一权威源。如时间戳早于 `## 约束与决策` 最后一条 `[需求漂移]` 时间，需先重新走本子流程刷新本节。
> 版本号规则：`v{N} = change_requests 数组长度 + 1`（含本次新追加的 CR）。

#### 当前要做什么
- {改动点 1：完整描述，不依赖删除线历史}
- {改动点 2}
- …

#### 不做什么（边界）
- {边界 1}
- {边界 2}

#### 历史版本（每行 1 句摘要）
- v{N-1}（{date}）：{被替代的核心原因，≤30 字}
- v{N-2}（{date}）：{摘要}

重写要求：

  • ✅ "当前要做什么"必须完整描述当前最新方案，不允许写"在 v2 基础上去掉 X" 这类增量描述（防止 AI 跨会话读时还要回查 v2）
  • ✅ "不做什么"必须包含历史所有版本累计声明的边界（去重合并），不允许只写本次新增的边界
  • ✅ 版本号 v{N} 必须与本次步骤 3.5 即将追加的 CR 序号一致（CR-{N-1} 对应 v{N}，因为 v1 是无 CR 的初版）
  • ❌ 禁止跳过本步骤直接进入步骤 3 的其他动作；本子区块的存在性是步骤 3.5 完成的前置条件
  1. 同步刷新 .flow.recovery 四段式（见 references/active-flows.md §恢复指令）：
yaml
recovery:
yesterday: "需求调整：X→Y，已刷新工作上下文，待对已写代码做回滚评估"
next_action: "{下一个具体动作}"
current_plan_summary: "v{N}：{当前完整方案 1 句话摘要 ≤80 字，与刚刚步骤 3.2.1 重写的『当前执行方案 v{N}』中『当前要做什么』首句保持一致}"
pending: ["{遗留待确认问题}"]

⚠️ 必须刷新 current_plan_summary：本字段是跨会话恢复时 AI 编码前必读的「当前方案唯一摘要」。 漂移流程走完只更新 yesterday/next_action/pending 而漏改 current_plan_summary → 下次恢复时 AI 仍按旧方案编码（同形偏失）。

  1. 生成已写代码回滚清单（仅 phase ∈ {coding, integration} 时）：
  • 在 ## 编码进度细节 表格中标记影响的文件「状态: 待回滚」
  • 询问用户是 AI 自动回滚还是用户手动处理（强制交互，不可静默回滚）

步骤 3.5：记录 CR 条目（drift 处理完成后自动执行） ​

本步骤在步骤 3 的强制执行项完成后自动执行，无需用户操作。

将以下信息追加到工作上下文 YAML front matter 的 change_requests 数组：

yaml

- id: "CR-{序号}"            # 从 1 开始递增（基于当前 change_requests 数组长度 +1）
description: "{漂移摘要中的「变更点-现」}"
type: "{scope|code|ui}"    # AI 根据变更内容判断
level: "{minor|major|critical}"  # AI 基于影响范围评估
detected_at: "step-{当前步骤}"
detected_time: "{ISO 8601 当前时间}"
status: "in_progress"
impact: "{漂移摘要中的「影响范围」}"
resolution: ""             # 步骤 5.5 AI 自动标记 done 时填写

判断标准：

  • type: scope：新增/删除功能点、改变业务边界
  • type: code：实现方式变更（API/算法/数据结构）
  • type: ui：界面/交互变更
  • level: minor：影响 ≤2 个文件，不改变 API 契约
  • level: major：影响 ≥3 个文件或改变 API 契约
  • level: critical：跨项目影响或需要重新评审

与步骤 5.5 的联动：步骤 5.5（L1 审查通过后），AI 自动检测本轮 git diff 是否包含 CR description 涉及的文件修改，命中则标记 status: done + 填写 resolution。

🔐 门控校验（步骤 3.5 完成后自动执行） ​

物理事实校验，不依赖 AI 承诺。

执行：bash ~/.codebuddy/skills/dev-flow/scripts/lints/doc-sync-lint.sh <flow-name> --mode drift

校验项：

  • 工作上下文 change_requests 数组长度 > drift 开始前（CR 已追加）
  • 最新 CR 的 detected_time 为今天（非残留旧条目）
  • ## 约束与决策 区块含今天日期的 [需求漂移] 行（约束已记录）

失败 → 🔴 阻断，回退到步骤 3.5 重做。

步骤 4：同步下游文档（必要步骤，不可跳过） ​

工作上下文已刷新为「当前执行方案 v{N}」。 本步骤将变更传播到全部下游文档（文档平台 / devlog / plan.md / report.yaml）。

执行方式：以 caller=from-drift 加载 references/in-flow-sync.md， 执行文档同步管道（H.0 / H.2 / H.3+ / plan.md / artifacts / working-context + 🔐 门控）。

与独立调用 dev:sync 的差异：

  • H.0 CR 登记：工作上下文已有本次 CR（步骤 3.5 创建），扫 git diff 无新增 → 自动跳过
  • H.3+ 文档平台：git diff 为空（尚未编码）→ 降级为工作上下文 + 文档平台 两方对账（见 closeout-flow.md H.3+ 边界条件表）

由本步骤承接下来的原 §3.4 职责：

  • 文档平台 正文全量更新 → 由 H.3+ 的 文档平台 对账逻辑处理
  • 确认清单（字段/流程图/接口/测试建议）→ H.3+ 对账报告覆盖

容错：dev:sync 中个别文档就绪检查失败（如 文档平台 无权限）不阻断本步骤， 仅记入同步报告的「未就绪文档」列表。

步骤 5：输出最终汇总 ​

drifts 的最终步骤，整合所有产出。

markdown
✅ 需求漂移处理完成

- **工作上下文**：已刷新为「当前执行方案 v{N}」+ CR-{N} 已登记
- **下游文档**：dev:sync 已完成，状态见上方同步报告
- **编码回滚**：{无 / 已列出清单}
- **下一步**：{继续编码 / 等待用户确认回滚}

反模式（违反即拒收） ​

  • ❌ 直接覆盖 ## 需求 而不保留删除线 → 破坏可追溯性
  • ❌ 只刷新 ## 需求 不更新 .flow.recovery → 跨会话恢复时仍会拿到旧值
  • ❌ 默默刷新不交互 → 违反「需求理解优先」红线（开发规范-红线 §核心原则 1）
  • ❌ phase: research 时也强制生成回滚清单 → 此阶段尚未编码，无回滚对象
  • ❌ 命中触发词后未先做静默对账，直接跳到选项交互 → 用户无法判断变更点是否真实

与既有机制的对照表 ​

既有机制关系说明
## 约束与决策 删除线规范（见 references/working-context.md § 字段说明 中「约束与决策」行）复用本子流程是其触发器之一，不重复定义格式
references/doc-sync-rules.md §路由分流互补一个管外部文档，一个管内部上下文，由路由分流互相调度
references/iteration-fix.md 重大复杂度正交iteration-fix 是「提测/上线后」的修复路径，本子流程是「开发中」的澄清回流
### 恢复指令 三段式（见 references/active-flows.md §恢复指令）同步漂移刷新后必须同步更新 yesterday/next_action/pending
AI 行为规范「长对话收尾自动沉淀触发器」互补长对话兜底；本子流程是关键词即时触发

基于「单一权威源」哲学构建 —— 文档由源文件投影生成

AI Coding Kit