跳转至

小米 Harness 工程落地：提示词是建议，Harness 让规则落地

Ch05.078 小米 Harness 工程落地：提示词是建议，Harness 让规则落地

📊 Level ⭐⭐ | 8.0KB | entities/xiaomi-harness-prompt-is-advice-rules-land-2026.md

小米 Harness 工程落地：提示词是建议，Harness 让规则落地

小米技术 2026-07-29。核心论点：AI Coding 下一阶段的关键不是继续优化提示词，而是建立不可绕过的工程约束——把 AI Coding 从"个人手艺"变成"团队工程"。

三机制架构

在 AI 对话外建立编排层，用三个机制把 AI 的自由能力装进可控工程管道：

  1. 流程约束 — 需求不清禁止编码、跳过方案禁止出代码
  2. 知识注入 — 团队规范/领域知识前置到 AI 上下文
  3. 质量门禁 — 评审后绕过门禁修改被拦截

融合 Skill Engineering 的技能编排与 OpenSpec 的规格化变更流程，通过 Hook 和门禁补上强制执行与可审计能力。

门禁引擎（workflow-gate.sh）做 5 路校验（技能事件/CLI 事件/工件/度量/项目状态），Fail-Closed 不降级放行；23 个样本合规率约 91.3%。

与同系列关系

本文是小米 Harness 专栏"怎么搭"篇，回答方法落地为团队标准；同系列 JDK 升级实践（JDK 升级实践）回答"值不值得做"。演进脉络另见 三次跨越。

深度分析

提示词是"软"约束：团队规模下必然失效

自由对话模式存在结构性缺陷：需求不清就编码、跳过方案直接出代码、评审后绕过门禁——输出质量全看个人提示词水平与纪律。 团队首次把流程写进 Prompt（/flow 命令 + 结构化模板）后，跳步骤现象虽减少，但暴露根本局限：AI 仍可能绕过规则，上下文压缩后甚至"忘记"约束；更关键的是无法核验 AI 的实际操作，只能相信它的"自述"。约束在"人"身上而非"流程"里。

Hook 与门禁：把约束从对话层下沉到执行层

第二次跨越把约束下沉到 Claude Code 的工具调用执行层：PreToolUse / PostToolUse 生命周期挂载检查脚本，执行前查阶段与准入条件，执行后记录关键事件。三层拦截构成强制力——PreToolUse 源码守卫（方案未定则 exit 2 阻断 Edit/Write）、Commit 守卫（前置产物未落盘禁止提交）、Bash 状态守卫（审查每条命令，拦截对 .workflow-state.json 的篡改）。 约束由此从"建议"变成受管控工具路径内不可绕过的规则，Fail-Closed 任何一路失败都不放行。

双通道证据：软件工程不相信 AI 的自述

AI Coding 改变了审计前提——真正的设计过程发生在对话中，AI 声称"已分析过所有影响范围"只是模型生成的自然语言，不能当作审计证据。团队因此设计双通道证据：关键步骤必须同时留存"工程工件中的证据标记块"与"Hook 自动写入的工具事件记录"，二者缺一即判定流程不通过。 工件有证据而事件缺失＝AI 声称完成却未执行；事件存在而工件缺失＝产物不完整。审计的意义不是追责而是协作。

从个人手艺到团队工程：插件化是最后一跃

单体阶段 Hooks、门禁脚本、知识库散落在各项目本地目录，靠 rsync/git pull 分发，版本不统一、升级成本极高。第三次跨越通过插件化解决分发、强制力与可审计性：约束逻辑封装为 Claude Code 插件经内部 Marketplace 统一分发，SessionStart 幂等注入，双策略同步（默认覆盖 / 项目锁定版本），状态文件仅允许通过门禁验证后的 mark-step 子命令更新。 配套知识库沉淀 110 份知识类 Markdown，首次深度审计修复 15 项高风险、37 项中风险、30 项低风险错误并补 64 项遗漏。23 个正式需求流程归档后，最大的变化是"AI 的行为不再依赖个人提示词，而变成了团队共享的工程能力"。

实践启示

  1. 从最小可行版本起步：先用约 50 行脚本跑通"一个 .workflow-state.json + 一个 PreToolUse 拦截器"（stage 非 implement 时阻断对 src/ 的 Edit/Write），观察一周再决定是否加约束。约束是被实际问题逼出来的，不是一次规划完成的。

  2. 约束要落到执行层，而不是提示词层：Prompt 是软约束，上下文压缩后 AI 会"忘记"。把阶段检查挂到工具调用生命周期（PreToolUse/PostToolUse），用源码、Commit、状态文件三层守卫实现 Fail-Closed，让"方案未定，代码不动"不可绕过。

  3. 建立双通道证据，把审计对象从对话变成工件：关键步骤同时留存工程工件证据标记 + Hook 自动写入的事件记录，缺一即判定不通过。不要相信 AI 的自述，只相信系统能验证的证据。

  4. 模板约束要显式设上限：brainstorm 阶段 AI 列了 11 个问题耗时 25 分钟，模板加"上限 5 个"后降回 12 分钟。AI 天然追求"全面"，约束必须写进模板。

  5. 项目能力要变成团队能力，靠插件化分发而非文档：约束逻辑、门禁脚本、命令定义封装为插件统一分发，SessionStart 幂等注入、版本可锁定，替代逐项目 rsync/git pull——代价是维护复杂度集中化，发版前必须有严格回归验证。

  6. 先问痛点类型，再决定是否上这套方案：痛点是"AI 写的代码不可审计、不可追溯"→ 直接改善；痛点是"代码质量不够好"→ 只能提高问题被提前发现的概率，不提升模型能力上限。同时警惕平台锁定（深度依赖 Claude Code Hook API）与 Bus Factor = 1（2600 行 Bash 一人维护），抽象层应面向能力接口而非特定产品。

→ 原文存档