开发工作流

分层加载架构：本文件为精简基线（~130 行），只保留 AI 做触发判断和流程入口所需的最小规则集。 详细规范按需加载：遇到复杂场景时 read_file("references/skill-full.md") 获取完整版本。

触发规则（速查）

完整触发规则 → .compiled/triggers.md（按需加载）/ references/skill-full.md「触发规则」章节

2026-06-01 改版：dev-flow 仅支持显式命令触发 + 活跃流程相关时恢复，不再基于关键词主观判断自动触发。

触发判定（普通对话 → dev-flow）

优先级：用户显式命令 > 活跃流程恢复（相关时） > 普通对话（含开发意图建议）

强执行规则：

• 一旦显式命令触发 dev-flow，严格执行完整流程，不得以"任务简单"为由跳步
• AI 严禁基于关键词主观判断自动触发；命中开发意图关键词时，必须在回复中提示 dev-flow 命令并等待用户决策
• 用户未用命令但要求改代码（如「直接改」） → 不进入 dev-flow，但仍须遵守 开发规范-红线.mdc 的 12 条红线和简化质量检查（详见 ~/.codebuddy/skills/dev-flow/references/no-dev-flow-mode.md）

流程内信号（仅 dev-flow 已激活时生效，不属触发规则）

以下信号仅在 dev-flow 已激活的流程内生效，普通对话中说这些词不会触发任何行为。

命令速查

完整命令说明 → .compiled/commands.md（按需加载）

必要节点 AI 主动弹框提醒（dev:sync 触发表）

权威表格。AI 在 dev-flow 流程内的以下节点必须主动调用 ask_followup_question 弹出 dev:sync 提醒。 详细规则 → references/in-flow-sync.md §1.2。 dev:sync ≠ 5.5b 替代品的单一权威源 → ~/.codebuddy/rules/AI行为规范.mdc §「主动文档同步弹框提醒」

sync_reminder_disabled: true 时的处理：仅对 #1 / #2 静默跳过；#4（恢复未完成的 sync）仍必弹（已经是用户主动召唤过的，需要给出收尾交互）；#3 本就是建议级，无影响。

流程加载指令（Prompt Chaining 架构）

Prompt Chaining 硬性规则：

• ❌ 禁止一次性加载多个步骤文件
• ❌ 禁止未加载步骤文件就执行该步骤
• ❌ 禁止跳过结构化完成标记 JSON 的输出

工作上下文持久化（核心要点）

完整规则、命名规则、项目缩写映射表 → references/working-context.md（规则单一权威源） 完整文件模板（YAML + Markdown 区块） → references/templates/working-context.tpl.md（创建新文件前必须加载）

• 创建前：① read_file("references/templates/working-context.tpl.md") 加载模板 → ② read_file("references/working-context.md") 查规则（命名/项目缩写/校验）→ ③ 跨项目复用预检（见下方小节，显式命令入口必经，堵"恢复网关不生效"漏洞）→ ④ ls 扫描目录匹配已有文件 → ⑤ 匹配到则更新，未匹配到才创建
• 创建/重命名后：必须调用 bash scripts/validate-working-context.sh <文件路径>，返回非 0 → 禁止继续
• ❌ 禁止不扫描就直接创建 / 禁止同一需求创建多个文件 / 禁止未加载模板就凭记忆创建

🆕 跨项目复用预检（显式命令入口堵漏，2026-07-02）

设计动机：v3 智能恢复网关（references/active-flows.md §「自动恢复决策逻辑」）只对非显式命令生效；用户在 B 项目直接输入 dev-flow 会绕过网关，导致 A 项目留下的 cross_project.status=pending_fix 工作上下文被遗忘、B 项目另开新文件。本预检仅在阶段 0 创建工作上下文前执行一次。

执行 5 步（AI 必走，约 1 次 ls + 1 次 head + 0~1 次 ask_followup_question）：

1. ls ~/.codebuddy/working-context/.active-flows/*.flow 2>/dev/null 拿活跃锁；空 → 跳到步骤 4 普通匹配
2. 对每个 .flow，对应工作上下文 .md 取 YAML 头（head -n 40 <name>.md 找 cross_project 块）
3. 命中条件：cross_project.enabled=true && status=pending_fix 且当前 workspace 与 fix_workspace 一致（或 fix_workspace 为空时弹选项让用户确认）
4. 命中 → ask_followup_question 弹「🔁 复用工作上下文 / 🆕 新建 / 👀 查看详情」三选项；用户选复用 → 跳到已有上下文路径，不创建新文件，按 references/cross-project/handoff.md §「衔接后行为」执行阶段 0 增量理解（步骤 1 跳过）
5. 未命中 / 用户选新建 → 继续原流程的步骤 ④ 普通匹配

反模式：❌ 跳过本预检直接创建（绕开本规约即视为违反强执行规则） / ❌ 预检中无 cross_project.enabled=true 时弹选项（无意义打扰）。

步骤切换门控（硬性规则）

完整门控规范 → references/gate-validator.md 🆕 程序化执行入口 → scripts/hooks/（PreStepLoad / PostStepComplete 钩子）+ config/gates.yaml + config/hooks.json

每步骤完成后必须：① 输出结构化完成标记 JSON → ② 更新工作上下文 → ③ 调用 validate-output.sh 机器校验（带 flow-name 参数）→ ④ 门控验证通过（.validated 已生成）→ ⑤ 才能加载下一步骤

🆕 推荐：使用统一钩子入口（替代各类零散调用）：

# 步骤完成后（替代直接调 validate-output.sh）：自动跑 validate + doc-platform-lint
bash ~/.codebuddy/skills/dev-flow/scripts/hooks/post-step.sh <step-id> <json-file> <flow-name>

# 加载下一步骤前（替代手动 ls 检查）：自动跑物理检查点白名单 + 步骤 5 加上编码前置硬卡点
bash ~/.codebuddy/skills/dev-flow/scripts/hooks/pre-step.sh <flow-name> <target-step-id>

Schema 机器校验（兼容旧路径，仍可直接调用）：

bash ~/.codebuddy/skills/dev-flow/scripts/validate-output.sh <step-id> <json-file> <flow-name>

• 必须传 <flow-name>（从工作上下文文件名去 .md 推导），脚本才会自动 touch .step-{N}.validated 物理检查点
• 返回码 0 → 加载下一步骤；≠ 0 → 补齐后重试（详见红牌 #14）
• Schema 文件：references/schemas/all-steps.schema.json

核心原则（精要）

§1~§12 由 alwaysApply 规则自动加载。§13~§18 为 dev-flow 扩展层。 完整说明 → .compiled/principles.md / references/core-principles.md

扩展层（§13~§18）：不确定就先确认 | 向用户解释 | 深度思考 | 不可变性优先 | 文件≤500行/函数≤80行 | 风格一致性

模式矩阵（5 种基础模式 + 1 种修饰层）

完整矩阵 → references/mode-matrix.md

• 基础模式（mode，互斥单选）：standard / full / iteration-fix / batch / cross-project + micro-fix（轻量快速修复专项模式）
• 修饰层（interaction_mode，正交叠加）：streamlined（启用后仅调节交互频率，不改变基础模式）

遇到模式冲突或不确定时 → read_file("references/mode-matrix.md")

按需加载索引

遇到对应场景时加载，不提前加载

help.md 一致性维护规则

权威源文件（SKILL.md / mode-matrix.md / step-router.md）与 references/help.md 之间存在手工维护的信息冗余。修改权威源后 help.md 不会自动更新，需主动检查。

被动提醒（AI 自动执行）

当对话中非 dev-flow 流程内修改了以下文件时，AI 必须在回复末尾主动提醒：

• SKILL.md
• references/mode-matrix.md
• steps/step-router.md

提醒格式：💡 提醒：help.md 可能与权威源存在不一致，建议运行 \dev:help --check` 检查。`

• ❌ 禁止在 dev-flow 流程中触发（与开发无关）
• ❌ 禁止自动执行检查或自动修改 help.md
• ✅ 仅在修改权威源文件后提醒一次

已知结构性差异（非错误）

以下差异是 help.md 与权威源之间的设计差异，help-consistency.sh 会报告但不需要修正：

其他规则

• Skill 优先级：用户级 Skill 优先于项目级同名 Skill
• dev-flow 优先级：「需求开发」= 写代码，文档类规则在 dev-flow 执行期间自动失效
• 冲突时：dev-flow 胜出
• Skill 自动发现：步骤×Skill 匹配表 → references/shared-rules.md §5

关键红线（不可省略）

• ❌ 禁止自动 git commit：commit message 仅生成，除非用户明确选择「📦 确认并提交」才执行
• ❌ 必须调用 smart-commit：禁止 AI 自行拼写 commit message（详见红牌 #12）
• ❌ dev-logs 目录命名四项 lint：步骤 4 创建 ~/.codebuddy/dev-logs/ 目录时，name_lint 四项（format_matched / type_valid / brief_has_chinese / no_project_suffix）必须全为 true，任一失败即 🔴 Block
• ❌ 先搜索后编码：新增工具函数/组件/Hook 前必须先 codebase_search 确认无已有实现
• ❌ 步骤完成必须经机器校验（v2 硬化 2026-04-30）：每个步骤完成标记 JSON 输出后，必须立即调用 scripts/validate-output.sh <step-id> <json-file> <flow-name> 脚本；脚本返回码非 0 或未触发 .step-{N}.validated 物理检查点 → 🔴 红牌 #14，禁止加载下一步骤。AI 不得自行 touch .validated 伪造通过。详见 steps/step-router.md §「🔐 物理检查点机制」和 references/gate-validator.md §「校验时机（v2 硬化版）」