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 | 目标:已有对话可以手动压缩上下文,并查看当前模型的窗口占用。 |
这样的输入同时给出了开发边界和审阅依据。Agent 不需要靠猜测决定“压缩”是否应该往聊天里插入一条用户消息。
3. 把上下文拆成规则、事实和记忆
我在此前的讨论中选定了一个轻量方向:使用 AGENTS.md、README.md 和模块 Markdown 记忆,不为项目记忆额外引入数据库、向量检索或后台服务。
| 文件或位置 | 主要职责 | 避免放入的内容 |
|---|---|---|
AGENTS.md |
工作约束、读取入口、验证要求 | 大段业务说明、一次性日志 |
README.md |
当前业务行为、运行方式、模块边界、接口入口 | 已失效的实现细节 |
.agent/memory/INDEX.md |
主题索引,告诉 Agent 何时读哪份记忆 | 所有主题的完整副本 |
.agent/memory/<topic>.md |
已确认决策、非显然约束、原因和踩坑 | 猜测、未经验证的成功结论 |
| 任务页或交接记录 | 本次完成项、当前提交、阻塞与下一步 | 永久复制一整套项目规则 |
同一事实只设一个主要维护位置。 其他文档放链接和简述,减少几个文件互相矛盾的机会。AGENTS.md 提供了面向编码 Agent 的指令文件约定;上表中的模块记忆布局则是我采用的组织方式,不是它规定的标准目录。
一条有用的记忆可以只有几行:
1 | ### 上下文占用与累计消耗分开维护 |
维护时区分三种动作: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 | { |
该事件可以证明收到了一条压缩结果,却不能单独证明整个功能已经验收。占用 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 | # 本次任务交接 |
长任务结束一个会话前,留下这样的交接比简单说“继续上次”可靠。Anthropic 的长期 Agent 工程实践也强调增量工作与可供下一会话接手的产物;上下文压缩本身无法承担全部交接职责。
发布前的最后检查
- 本次行为符合最初目标,重要取舍能解释。
- diff 范围清楚,未覆盖他人的工作。
- 检查结果与尚未验证的部分分别列明。
- 文档和记忆反映实际变化,未把猜测写成事实。
- 审阅的是具体提交,发布目标与回退办法明确。
- 发布后检查页面或功能,并记录实际部署的版本。
对“先审阅,再合并和部署”的任务,Agent 应先把文章、代码、测试和发布准备做完整,等审阅通过后执行发布。如果审阅期间主分支发生变化,还需要核对合并结果并运行受影响的检查。
我希望下一次打开项目时,接手的 Agent 能很快回答三个问题:现在是什么状态,为什么这样设计,怎样证明这次改动是对的。 能稳定回答这三个问题,工作流才开始成为可复用的工程能力。
整理依据与延伸阅读
本文综合了 2026 年 9—11 月与 ChatGPT、dots 的相关交互,以及个人 Notion 中的通用 Agent 规则、Harness 笔记、上下文压缩需求与 11 月 13 日交接记录。私人记录仅提炼方法和脱敏案例,未公开内部链接、人员、账号或部署地址。任务状态与验证边界按记录分别表述。
- AGENTS.md:指令文件约定
- MCP:工具发现、调用与 Schema
- AG-UI:事件与自定义扩展
- Anthropic:Effective harnesses for long-running agents
- Addy Osmani:Critical thinking when agents do the work
协议和 SDK 会继续演进。接入时应以项目锁定版本、实际接口和测试结果为准,文中的应用字段不能直接当作通用标准。
AI Agent 开发工作流指南:从上下文到可验证交付
https://www.xiaob.work/2026/11/14/ai-agent-development-workflow/
System sharing is unavailable in this browser. You can use the platform buttons above.