AI 工作流质量门禁：把软件工程的纪律搬进个人系统

「能跑」不等于「可靠」

大多数人搭个人 AI 系统时，第一条验收标准是：能不能跑？

能写出一篇文章，能改完一段代码，能把十页资料压成一页，看起来就算完成了。但用久以后，真正折磨人的是无声的错误：结构工整，语气笃定，结论却悄悄偏离了事实。

传统程序越界，常常会抛异常；模型走偏，往往仍能交出一份流畅的答案。于是个人 AI 工作流的关键问题随之改变：

当它做错时，我能否尽早知道；当我不知道时，系统能否停下来？

软件工程里，可观测性、测试、代码评审、变更记录和故障升级，本来就是为这个问题服务的。把这些纪律搬进 AI 工作流，只需要先承认一个朴素事实：模型输出是一个带概率的候选答案，不是一纸已经生效的判决。

可观测性：别把模型自报当成日志

让 AI 在答案末尾写「依据如下」「信心 90%」「我调用了某工具」，有帮助，但那仍然只是模型自报。它和系统真正记录下来的日志，不是一回事。

可靠的记录至少要区分三层：

1. 模型陈述：它声称用了什么依据、哪里不确定。这适合帮助人定位检查点，但不能单独证明事实。
2. 运行日志：系统实际记录的输入摘要、工具调用、来源 URL 或文件路径、时间、返回状态与错误。它回答「刚才真的发生了什么」。
3. 评测结果：用固定样本和明确标准，比较不同版本的正确率、失败类型、成本与延迟。它回答「这个系统是否比上一版更可靠」。

OpenAI 的 Evals 返回示例会保留运行状态、评分、所用模型、token 用量、采样参数与错误信息；Anthropic 对 LLM gateway 的说明也把 usage tracking 与 audit logging 列为独立能力。这些字段的价值，不在于表格更完整，而在于让一次结果可以追溯、让两个版本可以比较。

我会给每次关键产出留下一张很小的「证据卡」：

task_id: article-review-2026-07-31
model: provider/model-version
instructions_version: git-sha-or-v3
sources:
  - url-or-file-path
tools:
  - name: web-search
    status: success
checks:
  factual_claims: 8/8 sourced
  broken_links: 0
uncertainties:
  - "第三方数据仅有单一来源"
reviewer: human-or-eval-name

这张卡不要求记录模型隐含的思考过程，也不把「模型说它查过」当作完成。它只保留可核对的外部事实：什么版本，读了什么，调用了什么，检查了什么，哪里仍然不知道。

质量门禁：第二个 AI 不是第二份真相

让另一个 AI 扮演挑剔的评审，的确可能暴露第一份答案中的部分盲点，尤其是遗漏的反例、格式错误、前后矛盾和没有覆盖的验收条件。但它不是天然独立的证人。

两个模型可能共享相似训练偏差；同一个模型换一段提示词，也可能把同一种误解说两遍。更危险的是，第二个 AI 给出「通过」，容易让人把一次文本判断误当成事实验证。

所以门禁要按失败类型配检查，而不是笼统地「再问一个 AI」：

门禁的输出也不该只有「通过/失败」。更诚实的格式是：

decision: conditional_pass
evidence_coverage: 0.86
failed_checks: []
unknowns:
  - "供应商文档未说明边界行为"
risk: medium
next_action: human_review

这里的 0.86 只是按预先写好的 rubric 算出的覆盖率，不是真理。它的作用是触发流程：低于多少必须补证据，出现什么风险必须交给人。概率输出负责暴露不确定性，失败阈值负责阻止侥幸，人工升级负责承担后果。

三种东西别混在一起：上下文、项目指令、持久记忆

「把所有规则都塞进 CLAUDE.md 或 AGENTS.md，AI 就会记住」是一个很诱人的误解。至少要把三种机制分开：

• 上下文中的指令：当前会话里由系统、开发者、用户等角色提供的要求，作用域和优先级由产品的指令层级决定。OpenAI 将不同来源的指令按信任级别处理，低优先级内容不应覆盖更高优先级约束。
• 项目指令文件：仓库中的 CLAUDE.md、AGENTS.md 等文件，是工具在特定目录范围内加载的项目约定。它们适合写构建命令、架构边界、命名规则和验收方式；它们是否加载、作用到哪一层目录，取决于具体工具。
• 持久记忆：跨会话保存的用户偏好或事实。它可能由产品功能、专门的 memory 文件或外部存储实现，也需要更新、删除与来源治理。项目文件被再次加载，看起来像「记住了」，但不等于模型自身获得了可靠、永久的记忆。

Anthropic 的 Claude Code 文档也明确区分项目共享指令、用户级偏好和项目相关的本地偏好，并建议用 /memory 查看实际加载了哪些文件。这个动作很重要：不要猜规则已经生效，要检查工具到底加载了什么。

目录结构仍然有价值，但它只是可维护性的边界，不是魔法。我的做法是：

• 根级文件只放全局且稳定的项目规则；
• 子目录文件只放该目录特有的约束；
• 易变事实放到有来源与更新时间的数据文件；
• 个人偏好与团队规范分开；
• 每条重要规则都配一个可以验证它是否被遵守的检查。

一条没有检查方式的规则，最后很容易变成墙上的标语。

SOP 与分层交付：先跑通，再加速，再放手

一套流程值得自动化，前提是你已经知道它在什么条件下算完成。

我更喜欢这样的顺序：

1. 自己跑通：保留输入、判断依据和失败样本，写清成功标准。
2. 交给 AI 加速：让模型承担检索、起草、分类和重复检查，人保留关键判断。
3. 用评测观察：固定一组正常样本、边界样本和历史失败样本，记录版本变化。
4. 有限地放手：只有低风险、可回滚、通过阈值的动作才能自动执行。
5. 持续回收失败：每次人工纠正都变成新的测试用例，而不是只在聊天里说一句「下次注意」。

Anthropic 关于评测的建议从「先定义具体、可衡量、可达到且与任务相关的成功标准」开始；OpenAI 的 eval 机制也把测试数据、grader 与 run 分开。两家的共同启发落在同一处：先写清什么叫好，再谈如何自动判断好不好。

工程纪律从不消灭不确定性。它只做一件更实际的事：让不确定性有名字、有记录、有退出路线。

一份可复制的五项最小门禁

不需要先搭平台。把下面这段复制到任务模板里，就能得到一个足够小的起点：

## 1. 任务契约
- 目标：
- 必须满足的硬性条件：
- 明确不做：
- 可回滚方式：

## 2. 证据账本
- 来源 URL / 文件路径：
- 访问时间：
- 工具与调用结果：
- 模型 / 提示词 / 项目指令版本：
- 尚未验证的假设：

## 3. 自动检查
- [ ] 格式、链接、测试或静态检查通过
- [ ] 关键事实可追溯到一手来源
- [ ] 正常、边界、历史失败样本已运行

## 4. 失败阈值与升级
- 任一硬性检查失败：停止
- 关键来源冲突或缺失：转人工核验
- 涉及隐私、安全、法律、资金或不可逆操作：必须人工批准
- 仅允许低风险、可回滚任务自动执行

## 5. 复盘与评测
- 本次决策：通过 / 条件通过 / 失败
- 失败类型与样本：
- 与上一版本的质量、成本、延迟对比：
- 需要新增或更新的测试：

它看起来没有「军师天团」那么热闹，却更接近真实工程：有输入，有证据，有检查，有刹车，也有人来接管方向盘。

把纪律搬进来，而不是把系统搞复杂

个人工作流不需要复制大公司的仪式。低风险草稿，可以只做链接检查和一次编辑复核；要发给客户的结论，多加来源核验；涉及生产环境、资金与隐私的动作，再加权限隔离、回滚和人工审批。

门禁的重量，应该和错误的代价成正比。

我越来越不相信「再写一个更长的提示词，就能获得确定性」。真正可靠的系统，往往没有那么神秘：它知道自己用了什么，知道哪些检查通过了，也知道什么时候不该继续。

AI 会给我们越来越强的执行力。但做决定、定方向、承担后果的，仍然是人。工程纪律不是为了束缚这种执行力，而是给它一条能看见边界的河床。

官方参考

• OpenAI：The Instruction Hierarchy
• OpenAI API：Evals
• Anthropic：Claude 如何记住你的项目
• Anthropic：Define success criteria and build evaluations
• Anthropic：Other LLM gateways

延伸阅读：动手搭建见《把笔记交给 AI 操作》 ；方法论总纲见《从信息到创作》 。