AI Agent 开发工作流指南:从上下文到可验证交付

最近,我一边用 ChatGPT、Codex 等工具辅助开发,一边让 dots 处理跨系统的信息整理与同步,也在参与 Agent 产品本身的开发。问题逐渐从“这个模型能不能写出来”,转向了更具体的工程细节:换一个 Agent 能否接着做?上下文压缩后会不会丢掉约束?任务重跑会不会重复写入?它说完成时,到底验证了什么?

把这些交互与 Notion 中的开发、交接记录放在一起,最值得固定下来的,是一套让任务有边界、执行有状态、结果有证据、下一轮能接手的工作流。

本文主要讨论怎样使用 Agent 完成软件开发,并用“上下文压缩”这个 Agent 产品功能贯穿说明。素材以近期实践为主,结合此前的 Harness Engineering 笔记;其中的通用模板是整理后的建议,探索中的方案不代表已经上线。

1. 先分清谁负责什么

使用多个工具时,我更关心它们在任务中的职责,而不是给每个工具重复发送同一个大需求。下面是适合 Vue、TypeScript、Node.js 项目的分工建议,不是某款产品的能力上限。

工作 合适的入口 需要交付什么
行内补全、小段代码 编辑器补全;明确的重命名优先用语言服务 开发者当场读得懂、能判断的改动
需求澄清、方案权衡 ChatGPT 等对话入口 范围、取舍、验收条件
跨文件实现、排错、重构 能读取仓库并运行检查的编码 Agent diff、验证结果、剩余问题
会议、任务、笔记的持续整理 dots 等连接工作应用的 Agent 来源、更新记录、失败与待办
审阅与发布 人负责判断,Agent 执行已授权步骤 确认的版本、发布结果、回退办法

Codex、CodeBuddy、OpenCode 等可以接不同的实现任务,但交接必须落到文件、提交和验证记录上。工具名称不能代替责任边界。

2. 用六个步骤完成一次开发

步骤 Agent 要做的事 离开这一步的条件
读取现状 读适用规则、相关代码、最新接口和已有修改 能指出事实来源及不确定项
定义任务 写清用户行为、范围、约束和验收条件 “完成”有可观察的定义
小步实现 沿现有架构完成一个可验证的切片 改动可单独解释、检查
验证修正 跑相关检查,覆盖失败和恢复路径 有通过证据,或明确阻塞
更新交接 同步业务说明、长期约束和本次进度 换会话后能继续
审阅发布 展示 diff 与证据,按约定合并、部署 线上结果与批准版本一致

这里的“定义任务”不必变成冗长的计划。小修复可以快速进入实现;涉及接口不明、架构取舍或生产影响时,再把需要人决定的部分单独拿出来。一个问题未确认,不应阻塞其他互不依赖的工作。

例如,“加一个上下文压缩按钮”还不够明确。任务应该描述:

1
2
3
4
5
6
7
目标:已有对话可以手动压缩上下文,并查看当前模型的窗口占用。
范围:复用现有聊天组件、请求封装与流式处理链路。
约束:保留聊天记录、输入草稿、附件和原回复耗时。
验收:空对话隐藏入口;重复点击不重复提交;失败可退出忙碌态;
切换会话后旧请求不能覆盖新会话;普通发送仍然正常。
待确认:请求字段、事件载荷、历史恢复位置,以当前接口和代码为准。
交付:改动、已跑检查、未验证事项、接手所需说明。

这样的输入同时给出了开发边界和审阅依据。Agent 不需要靠猜测决定“压缩”是否应该往聊天里插入一条用户消息。

3. 把上下文拆成规则、事实和记忆

我在此前的讨论中选定了一个轻量方向:使用 AGENTS.md、README.md 和模块 Markdown 记忆,不为项目记忆额外引入数据库、向量检索或后台服务。

文件或位置 主要职责 避免放入的内容
AGENTS.md 工作约束、读取入口、验证要求 大段业务说明、一次性日志
README.md 当前业务行为、运行方式、模块边界、接口入口 已失效的实现细节
.agent/memory/INDEX.md 主题索引,告诉 Agent 何时读哪份记忆 所有主题的完整副本
.agent/memory/<topic>.md 已确认决策、非显然约束、原因和踩坑 猜测、未经验证的成功结论
任务页或交接记录 本次完成项、当前提交、阻塞与下一步 永久复制一整套项目规则

同一事实只设一个主要维护位置。 其他文档放链接和简述,减少几个文件互相矛盾的机会。AGENTS.md 提供了面向编码 Agent 的指令文件约定;上表中的模块记忆布局则是我采用的组织方式,不是它规定的标准目录。

一条有用的记忆可以只有几行:

1
2
3
4
5
6
### 上下文占用与累计消耗分开维护
- 决策:窗口占用从服务端占用快照/事件读取,不用累计 Token 推算。
- 原因:压缩后窗口占用会下降,历史调用的累计消耗不会因此减少。
- 影响:模型切换、历史恢复、占用圆环与压缩完成反馈。
- 依据:当前接口契约、事件处理实现和对应验证记录。
- 复核时机:模型适配、事件结构或历史恢复链路变化时。

维护时区分三种动作:init 建立入口,sync 按实际改动更新知识,check 只读检查漂移。没有知识变化,就不为了“记了一笔”刷新记忆。

文件存在也不代表所有客户端都会自动加载。换工具时,要核对其规则发现方式、目录作用域和覆盖关系;重要约束让 Agent 指出读取位置,比询问“你记住了吗”更有意义。

压缩对话时保留什么

长对话的交接摘要至少保留:目标、用户修正、有效约束、已经完成的改动、验证范围、未解决问题、当前运行状态、已授权与尚待批准的操作,以及原始证据入口。

不要把“有人建议这样做”压缩成“项目已经这样做”,也不要只留下“已完成 80%”。百分比无法告诉接手者还有哪个失败路径没验证。

4. 工具和 Skill 要有可执行的契约

我的 Harness 笔记把规则、工具、流程、记忆和验证放在同一个体系里。落到实现时,各层职责应该清楚:

层次 负责的问题 一个例子
指令与规则 应遵循什么约束 只修改本次涉及的模块
Skill 某类任务怎么完成 接口核对、迁移检查、交接整理
工具或 API 对外执行什么动作 读取任务、更新属性、查询运行状态
运行时策略 哪些操作可以真正执行 服务端鉴权、目录限制、写入审批
验证 结果是否符合约定 结构校验、回读、测试与业务验收

提示词中的“不要越权”不能替代运行时检查。尤其是脚本执行和外部写入,应在真正执行的位置检查授权、参数和作用范围。

MCP 的工具规范定义了工具发现、调用及输入输出描述。它能帮助统一接入,但业务上的“重复执行怎么办”“什么状态允许修改”仍然需要应用实现。

工具很多时,可以先暴露名称、简述和检索入口,命中后再加载完整 Schema。这是可选的工具选择策略,需要验证当前框架的支持情况。检索负责缩小候选,服务端仍必须对实际调用做权限检查。

一个可复用 Skill 也应该写明输入、前置条件、产物、验证方式、失败处理和边界。把一次成功操作整理为 Skill 之后,还要用失败样例检查它是否依赖了偶然成立的环境条件。

5. 实例:上下文压缩怎样从按钮变成交付物

近期的 Notion 记录里,“手动/自动压缩”任务已标记完成,但交接文档同时明确:已经做过静态与内存流式自检,尚未做浏览器视觉验收、真实接口/模型联调和部署验证。这个差别本身就是工作流的一部分。

先拆开三种状态

状态 表达什么 不能拿什么代替
窗口占用 当前模型这次上下文装了多少内容 历史累计 Token 消耗
调用消耗 已发生的模型调用用量 当前剩余窗口
压缩操作 本次压缩正在进行、完成、跳过或失败 整轮对话的运行状态

这样拆分后,手动压缩就可以保留聊天内容与草稿、单独计时,并在无需压缩时准确反馈。没有收到有效占用数据时,也应显示未知,而不是伪装成 0%。

协议结构与业务约定分别维护

AG-UI提供运行、消息、工具和状态事件,以及 CUSTOM 扩展。这里的 CUSTOM、name、value 是协议结构;compaction、context.usage.updated 和各自载荷属于本次应用契约。

下面是从开发记录提炼的事件示例:

1
2
3
4
5
6
7
8
9
10
{
"type": "CUSTOM",
"name": "compaction",
"value": {
"phase": "done",
"compacted": true,
"beforeTokens": 12450,
"afterTokens": 3120
}
}

该事件可以证明收到了一条压缩结果,却不能单独证明整个功能已经验收。占用 UI 仍应消费约定的占用快照或事件,不从这两个数值推算当前模型窗口。

本次手动压缩复用了现有 run 链路,以 forwardedProps.action = compact_context 表达意图,并使用空 messages 避免添加普通聊天消息。这是该项目的设计选择;迁到另一个项目时,需要重新核对输入约定、鉴权和 SDK 解析行为。

把异常路径写进验收

情况 应有结果
空对话 隐藏入口,不发无用查询
连续点击 仅发起一次压缩
正在生成或等待人工确认 不插入另一次手动压缩
无需压缩、失败、停止、断流 正确收尾,不制造成功状态
只有运行终态,没有有效压缩结果 不把运行结束直接解释为压缩成功
自动压缩没有真实开始时间 不展示推测的耗时
切换会话后旧响应到达 旧数据不能污染新会话
历史恢复、重新订阅 正确识别手动压缩与普通对话中的自动压缩

交接中还记录了一个很实用的坑:某些非标准字段经过当时的 SDK 校验后会消失。迁移时必须检查实际解析结果,不能因为后端发出了字段,就认定前端回调一定拿得到。

合理的实现顺序因此是:先核对契约和事件归属,再整理状态与生命周期,随后接 UI,最后检查普通发送、嵌入入口及历史恢复。漂亮的圆环是其中一个交付点。

6. dots 的持续任务,需要重跑与恢复设计

跨系统同步是另一类很能暴露问题的 Agent 工作。近期的交互包含项目任务同步到 Notion、登录态检查、重新执行和人工补充记录。这些需求让我把下面几项纳入持续任务的验收标准:

约束 可以固化的实现方式
同一条任务反复同步 用源系统标识与稳定任务 ID 定位目标,更新而非重复新建
同一自然周重复运行 记录业务周期,不能每重跑一次就推进一周
同步内容旁边有手写内容 分开维护同步区与人工区,只更新约定范围
已勾选归档的记录 按明确规则跳过,保留用户的归档选择
文本成功但图片缺失 标记部分完成,列明缺失项
登录失效或访问受阻 保存当前进度、报告阻塞,恢复后核对再继续

这些是从真实需求整理出的约束与实现建议,不等于每条自动化都已经通过完整验收。

对于定时任务,我会把“调度触发”和“业务上该不该执行”分开。先按指定时区、自然周及工作日规则判断执行资格,再检查访问状态。调度器重试不应改变任务所属周期。

持续任务还应记录本轮处理到了哪里、哪些条目成功、哪些失败,以及最近一次成功同步的源版本。若写入超时但不确定服务端是否成功,应先查目标,再决定重试。回读验证、幂等键、冲突检测要进入代码和工具契约,不能只靠 Agent 在对话里“记得小心”。

7. 当开发对象本身也是 Agent

使用编码 Agent 和开发 Agent 产品,会在一些地方相遇,但需要维护不同的状态。

前端关心交互与归属。 消息属于哪个会话,事件属于哪次运行,什么时候允许停止或确认,刷新后怎样恢复,都要有明确语义。页面上展示历史消息,不代表应该把这些消息全部送入新的模型上下文。

后端关心执行与恢复。 工具调用、持久化状态、外部副作用和权限检查需要统一管理。仅在前端断开流式连接,不能据此宣布后端任务已经停止。

切换 Agent 要重新确认能力边界。 近期开发记录提到的工具残留问题,说明模型、工具集合、MCP 连接和上下文不能只跟着一个下拉框变更。它们应按新 Agent 的配置与会话规则重新绑定,旧请求也要正确收尾。

至于 Jev、Laya 一类决策模型,我目前仍把相关讨论当作探索:先限定它要选择的动作与输入,和规则方案比较,再决定是否接入。本地推理也不必天然采用 HTTP;是否封装服务,应由调用方语言、部署边界与运行条件决定,具体能力以项目文档和实测为准。

若要验证一个调度 Demo,可以先准备正常、冲突、数据缺失和无法决策的固定样例,检查选择结果及回退行为。动画跑通、输出一个概率,都不能替代业务可行性验证。

8. 用证据结束任务,用交接开始下一轮

我收藏的 Addy Osmani 文章 Critical thinking when agents do the work 提醒了一个问题:产出越快,越容易跳过判断。放到工程里,我希望每次交付都能回答:这个检查证明了什么,还有什么没证明?

证据 能说明什么 仍不能说明什么
类型、Lint、编译通过 对应静态规则与编译链路通过 用户行为正确
单元测试、内存事件自检通过 所列样例和模拟条件符合预期 真实网络、持久化与跨实例恢复可靠
真实接口与浏览器验收通过 当前环境的关键路径可用 所有部署环境都等价
部署后检查通过 指定版本在目标环境通过所列检查 未来运行不会再出问题

检查要跟改动匹配。接口适配要测异常载荷;流式功能要测中断和恢复;纯文字修改重点检查生成结果与链接。既不要为一个小改动无边界扩测,也不要用“测试通过”掩盖未执行的验证。

审查时先读需求、diff 和证据,再读 Agent 的总结。即使换一个 Agent 复核,也要让它接触原始材料,避免只审核上一位写得很自信的摘要。

可直接复用的交接模板

1
2
3
4
5
6
7
8
9
10
11
12
# 本次任务交接

- 目标与范围:
- 基线与当前提交:
- 修改位置及原因:
- 必须保持的业务行为:
- 已确认契约及来源:
- 已执行验证(环境、命令/步骤、结果):
- 未执行验证与限制:
- 已知问题、阻塞和下一步:
- 已授权操作与尚待审阅事项:
- 需要更新的 README / 主题记忆:

长任务结束一个会话前,留下这样的交接比简单说“继续上次”可靠。Anthropic 的长期 Agent 工程实践也强调增量工作与可供下一会话接手的产物;上下文压缩本身无法承担全部交接职责。

发布前的最后检查

  • 本次行为符合最初目标,重要取舍能解释。
  • diff 范围清楚,未覆盖他人的工作。
  • 检查结果与尚未验证的部分分别列明。
  • 文档和记忆反映实际变化,未把猜测写成事实。
  • 审阅的是具体提交,发布目标与回退办法明确。
  • 发布后检查页面或功能,并记录实际部署的版本。

对“先审阅,再合并和部署”的任务,Agent 应先把文章、代码、测试和发布准备做完整,等审阅通过后执行发布。如果审阅期间主分支发生变化,还需要核对合并结果并运行受影响的检查。

我希望下一次打开项目时,接手的 Agent 能很快回答三个问题:现在是什么状态,为什么这样设计,怎样证明这次改动是对的。 能稳定回答这三个问题,工作流才开始成为可复用的工程能力。

整理依据与延伸阅读

本文综合了 2026 年 9—11 月与 ChatGPT、dots 的相关交互,以及个人 Notion 中的通用 Agent 规则、Harness 笔记、上下文压缩需求与 11 月 13 日交接记录。私人记录仅提炼方法和脱敏案例,未公开内部链接、人员、账号或部署地址。任务状态与验证边界按记录分别表述。

协议和 SDK 会继续演进。接入时应以项目锁定版本、实际接口和测试结果为准,文中的应用字段不能直接当作通用标准。

AI Agent 开发工作流指南:从上下文到可验证交付

https://www.xiaob.work/2026/11/14/ai-agent-development-workflow/

作者

Bryan

发布于

2026-11-14

更新于

2026-11-14

许可协议