Long-running Agent 研发实践 · 下篇
上篇讨论了 Human-Led Multi-Agent 工作流：决策层、编排层、执行层三层分工，以及从需求确认到状态更新的七步闭环。它回答了“谁来做、任务如何流转”。
但分工只解决了一半问题。如果所有工程知识仍然保存在 Main Agent 的聊天记录里，多 Agent 架构只是把单窗口的上下文问题搬到了编排层。同时，如果执行 Agent 可能犯错，Main Agent 和 Review Agent 同样可能犯错，增加几个 Agent 并不会自动带来可靠性。
本篇讨论两个问题：
- 如何让研发过程跨会话恢复，不依赖某一次对话的长度？
- 如何让人类对 Agent 的信任有依据、可校准，既不盲信，也不重复检查一切？
前者是 Harness Engineering 的问题，后者是 Human-AI Interaction 的问题。
01｜Harness Engineering：把知识放在对话之外
Harness Engineering 的思路，是把 Agent 需要的知识、工具、约束和反馈机制，组织成可持续使用的外部工程环境。核心不是让 AI 记住所有历史，而是让 AI 能够重新找到并验证当前需要的信息。
从对话记忆转向版本化知识
长期项目的关键知识，可以拆成不同类型的工程产物，各自放在版本化的文件里。
这些内容不必塞进同一个文件。OpenAI 的 Harness Engineering 实践强调：用简短的 AGENTS.md 作为仓库知识入口，把详细资料放在可导航的版本化文档里。重点是给 Agent 一张知识地图，而不是一本无限增长的指令手册。
Claude Code 等工具有各自的 CLAUDE.md、Skills 等配置机制，自动加载方式并不一致。因此跨工具协作时，要明确配置每个工具的知识入口，不能默认所有 Agent 都会读同一个文件。
让新的 Agent 重建上下文
一个可恢复的工作流，不应要求 Agent 永远留在同一个会话里。新的 Agent 可以重新读取产品合同、当前代码、Git 状态和近期验证记录，自己重建任务所需的上下文。历史对话仍有价值，但主要用来解释决策背景和定位问题，不应覆盖当前仓库里的证据。
恢复上下文也不等于无条件相信文档，外部文档同样会过时。接手的 Agent 需要做上篇 Step 2 里的那件事：核对设计记录与工程事实是否一致，发现差异就记录，而不是默默选一边。
让规则可维护
把所有规则堆进一个很长的指令文件，不一定提高可靠性。规则太多、优先级不明、夹杂过时内容时，Agent 反而更难识别真正重要的约束。更合理的做法是按职责分层：
- 全局规则：基本工作方式和安全边界。
- 领域文档：具体业务约束。
- 任务指令：本次修改的范围。
- 自动化工具：能够机械检查的工程不变量。
某类问题反复出现时，先判断根本原因，再决定是补一条文档规则、加一个测试检查，还是加一道运行环境限制。目标不是让 Agent 遵守更多文字，而是让重要规则更容易被发现、执行和验证。
02｜分层验证：每一层只证明它能证明的事
验证体系的出发点是承认：每一层都会出错，所以要清楚每一层能证明什么、不能证明什么。
第一层：确定性工具验证。 类型检查、Lint、单元测试、集成测试、构建检查、Git 差异检查等，结果相对客观、可复现。但测试通过只说明被执行的断言得到了预期结果，不代表所有行为都正确。跨页面交互、桌面应用生命周期、真实用户操作和复杂外部环境，仍需要额外验证。
第二层：独立 Agent 审查。 Review Agent 可以关注代码逻辑、需求一致性、测试覆盖和潜在回归。使用独立会话，能减少对同一生成过程的依赖，却无法消除不同模型共享的知识盲区。它的价值是增加审查视角、发现问题、引导进一步验证，而不是提供形式化的正确性证明。
第三层：人工判断与授权。 人类监督不意味着逐行检查所有 AI 生成的代码。更有价值的参与集中在产品目标、重要技术取舍、高风险操作、异常结果和最终用户体验。核心是按风险配置人工注意力：低风险、可自动验证的工作减少重复介入；高风险、不可逆或涉及真实数据的操作，需要更严格的授权与审查。
03｜从 Human-AI Interaction 看：信任应当可校准
多 Agent 工作流里，人类面对的不再是一个对话对象，而是一条由多个 AI 角色组成的汇报链。三个来自 HAI 研究的概念，在这里变得很具体：
- Automation Bias（自动化偏见）：人类容易因为 AI 的报告流畅、解释完整，而高估其结论的可靠性。Agent 的完成总结写得越像样，越需要提醒自己：这是审查入口，不是证据。
- Human Oversight（人类监督）：系统必须明确哪些决策需要人类参与，以及人类能拿到什么信息来判断。如果监督者看不到 Git Diff、测试结果和验收条件，“有人类在环”只是形式。
- Calibrated Trust（可校准的信任）：使用者需要能区分三类内容：已被工具验证的事实、尚未验证的推断、需要进一步人工检查的结果。信任的程度应当与证据的强度相匹配。
好的协作机制，既不要求人类无条件信任 Agent，也不迫使人类重复检查所有低价值细节。它要让证据、风险和责任边界足够清晰，使人类能合理分配注意力。
这也解释了上篇三状态模型的意义：它不只是管理工具，更是一种界面设计。“已实现、已集成、已验收”这三个标签，把“Agent 说完成了”拆成了人类可以逐项核对的证据层级。
流程规则不等于技术权限
还有一个必须分清的区别：要求 Agent 不做某件事，与在技术上阻止它做这件事，是两回事。
在 AGENTS.md 里写“未经授权不得部署”，是行为规则。Git Worktree 隔离了代码目录，但并不限制 Agent 访问其他路径或执行 Git 操作。真正的技术边界，需要通过沙箱、文件系统权限、凭据隔离、分支保护、受控工具接口或审批机制来实现。
一个完整的 Harness 应当同时考虑行为指导和实际执行权限。不能因为任务指令里写了禁止事项，就认定系统具有硬性的安全保障。
04｜实践：一个轻量化的仓库结构
这套方法不需要一开始就搭建完整的自动化研发平台。下面是我在个人长期项目中使用的轻量结构：精简全局入口 + 按需加载专业规则 + 版本化业务知识。
几个设计要点：
全局入口保持精简。 AGENTS.md 允许执行 Agent 在明确授权的范围内自主编码、运行必要检查并修复本次引入的缺陷；而 Commit、Merge、Push、部署、真实数据修改和破坏性操作，由独立授权约束。普通执行 Agent 不需要加载调度规则，避免每次都读完整流程。
验证强度由风险决定。 AGENTS_VALIDATION.md 的原则是“最小充分验证”：低风险的局部修改只需差异检查；共享业务逻辑、异步状态和跨模块改动，要覆盖实际受影响的消费者；涉及持久化、迁移、凭据、权限或 Electron 生命周期的高风险改动，则需要隔离验证、兼容性和失败路径检查。验证强度不由 Agent 数量或修改文件数决定，也不默认对所有任务跑全量测试、完整 E2E 或多轮独立审查。
双轨台账：产品合同与验收清单分离。 长期项目中，工程知识既需要让人类理解决策背景，也需要让 Agent 能够进行确定性解析。如果把两者混在同一个文件里，往往两头不讨好。在实践中，我们通过两种互补的文件承载工程状态：
*_IMPLEMENTATION.md（人类可读）：记录工作包划分、模块依赖、产品决策合同（确定做什么、明确不做什么）与架构边界；*_FEATURES.json（机器可读）：为 Agent 和自动化检查提供带严格 Schema 的状态清单，包含 Feature ID、实现状态（implementationStatus）、逐项用户验收步骤（steps）以及最终结论（passes: boolean）。
| 维度 | *_FEATURES.json（功能状态与验收清单） | *_IMPLEMENTATION.md（实施台账与产品合同） |
|---|---|---|
| 核心定位 | 机器可读的结构化验收清单 | 人类可读的实施计划与产品合同台账 |
| 文件格式 | JSON（结构化 Schema） | Markdown（图文、表格、长文本说明） |
| 记录重点 | • 每个 Feature 的 ID、优先级与 Scope；• 实现状态（implementationStatus，如 IMPLEMENTED）；• 逐项真实用户验收步骤（steps）；• 验收最终结论（passes: boolean）；• 验证证据摘要（implementationNotes） | • 阶段整体范围与实施全貌；• 工作包划分（Work packages）与依赖顺序；• 产品决策与冻结合同（确定做什么、明确不做什么）；• 架构边界、退役/迁移方案与未决问题（Open Questions） |
| 主要读者 | Agent 任务调度、自动化检查、核对逐项验收步骤 | 开发者/产品 Owner 理解业务上下文、边界决策与实施方案 |
| 查阅时机 | 选择具体 Feature 开发、确认功能缺口、核对或更新最终验收状态时 | 规划阶段路线、裁定产品范围边界、了解模块依赖或技术约束时 |
在日常多 Agent 协作中，双轨台账遵循三条明确规范：
- 唯一事实来源（SSOT），避免重复记录：Feature 的逐项状态、具体验收步骤和最终结论以
*_FEATURES.json为准；宏观工作包实施安排、架构依赖与产品决策以*_IMPLEMENTATION.md为准。不在 Markdown 中分散维护易变的状态细节。 - 实现状态与产品验收严格分离：代码已合并或业务路径已通，仅代表
implementationStatus: "IMPLEMENTED"；只有在目标真实环境（如真实桌面客户端或终端设备）完成steps里的所有用户级验收步骤后，才能在 JSON 中将passes改为true。 - 收敛写权限，防止并发竞争：
*_FEATURES.json由 Main 集成 Owner 统一维护与闭环，普通执行 Agent 不得随意争用或修改状态文件，避免多 Agent 并行时发生状态覆写与“自我宣布完成”。
需要说明的是，这是我个人项目中的工作流设计和工程经验，没有经过控制实验验证，具体收益仍取决于项目复杂度和协调成本。评估思路见上篇第 04 节。
结语：从管理 AI 对话，到设计可靠的研发系统
当 AI 承担越来越多的实现任务，开发者的注意力会逐渐从“怎么向 AI 表达编码需求”，转向“怎么定义正确的目标、组织任务、维护工程状态、验证最终结果”。
两篇合起来，是一个完整的思路：
- 上篇用职责分离回答“谁来做、如何流转”，让设计意图、实现、集成与验收各归其位。
- 下篇用外部化知识回答“如何恢复”，用分层验证与可校准信任回答“如何放心”。
这并不意味着多 Agent 天然优于单 Agent，也不意味着所有项目都需要复杂的编排。真正重要的，是根据任务结构和风险选择合适的协作方式。
AI 软件开发的下一步，不只是让 Agent 写出更多代码，而是让整个研发过程变得更可理解、可恢复、可验证、可控。这是从 AI 辅助编码走向 AI-native Software Engineering 时，一个值得持续探索的工程问题，也是一个典型的 Human-AI Interaction 问题。
参考资料
- OpenAI. (2026). Harness engineering: Leveraging Codex in an agent-first world.
- Anthropic. (2025). Effective harnesses for long-running agents.
- Anthropic. (2024). Building effective agents.
- Anthropic. (2026). The AI-native SDLC playbook.
- Anthropic. Claude Code power user tips. Claude Help Center，持续更新。