Coding Agent 的交付汇报：6 种状态怎么写

Coding Agent 的汇报要让下一个执行者能复现、验证或继续推进，而不是只知道“做了很多事”。

人写周报，常常是为了同步进度。Coding Agent 的汇报不一样：读者往往会顺着它继续改代码、跑测试、审查 diff，或者判断是否能发布。此时“已完成”“已修复”没有证据就没有意义。

我更愿意把 Agent 汇报看成一次交接：它应该告诉下一个人，代码现在处于什么状态、改动在哪里、已验证到哪一步、还有什么没有验证。

一句话总结

Coding Agent 汇报的最小单位不是“做了什么”，而是可核验状态：变更范围、验证证据、Git 状态、部署状态和下一步。先给状态，再给证据；不要用构建通过推断线上可用，也不要用推送成功推断部署完成。

1. 完成交付：给出可以复跑的证据

完成不等于写完代码。它至少包含四层彼此独立的状态：工作区、提交、推送、部署。它们必须分别报告。

1
2
3
4
5

【结论】文章页的目录滚动高亮已修复。
【变更】修改 src/toc.ts、src/article.css；未改路由和数据结构。
【验证】pnpm test toc 通过；localhost 逐段滚动验证 6 个标题均切换高亮。
【状态】工作区干净；已提交 abc123；已推送 origin/main；未验证生产环境。
【风险】Info：Safari 尚未手测。

这比“修复完成，已发布”多了一点长度，却少了三个常见误解：构建通过不等于功能正确，推送成功不等于 CI 已部署，部署成功也不等于用户路径已经验证。

项目状态报告通常也会要求摘要、阻塞、指标和下一步；对 Coding Agent 来说，要把这些信息进一步落到具体文件、命令和环境。Atlassian 的项目状态报告指南提供了状态、风险和行动项的基础骨架。

2. 进行中：写清“已经落在哪”和“还没有做什么”

进行中最怕伪完成。不要说“完成了 80%”，因为没有人知道剩下的 20% 是一个 CSS 微调，还是一套迁移和回滚逻辑。

1
2
3
4
5

【当前落点】Provider Adapter 已抽出接口，Codex 实现已迁移。
【未完成】Qoder Adapter、失败重试、端到端回归尚未开始。
【依赖】需要确认 Qoder 最新 SDK 的流式事件字段。
【下一步】确认字段后补 Adapter 映射与两条集成用例。
【状态】仅本地工作区修改，未提交、未推送。

这里“有意未动的范围”很重要。它把真实边界交给下一位执行者，避免对方误以为某个目录只是漏看了。

3. 失败阻塞：先说根因、影响和解除条件

失败报告不需要整段日志。日志是证据链接，不是结论本身。先给读者足够的信息判断是否要介入：

1
2
3
4
5

【阻塞】生产 API 返回 403，部署无法验证。
【根因】当前 token 缺少 release:read Scope；代码请求已在本地 mock 验证。
【影响】不影响本地实现与单测，阻塞生产 Smoke Test。
【已尝试】刷新 token、切换 staging 凭证，均无效。
【需要】由凭证 Owner 补充 Scope，或提供可用的 staging token。

“外部依赖未就绪”不够具体。谁能解决、需要什么、影响到哪一步，才是可执行的阻塞信息。

4. Bug 诊断：把现象、根因和修复证据拆开

Bug 汇报最容易把猜测写成根因。正确顺序是现象、范围、已确认根因、修复和回归证据；尚未确认的内容要标成假设。

1
2
3
4
5

【现象】中文输入法确认候选词时，Enter 被当成消息发送。
【范围】Chrome 与桌面 WebView 复现；英文输入不受影响。
【根因】keydown 未检查 composition 状态，已用最小页面复现。
【修复】加入 isComposing 与 keyCode 229 guard。
【回归】中文拼音、五笔、英文 Enter、Shift+Enter 换行均通过手测。

如果修复没有回归范围，下一位开发者无法判断这次改动是解决了根因，还是只是把症状藏起来。

5. 方案决策：把分析压缩成能拍板的选择

Coding Agent 不只交付代码，也会遇到依赖、架构和迁移路径的选择。此时不需要把调研过程逐条搬出来，而要给出自己的建议和明确取舍。

1
2
3
4
5

【建议】首期采用方案 B：保留现有 SQLite，新增异步索引表。
【收益】迁移风险低，可在当前版本上线。
【代价】复杂查询继续由应用层处理，第二阶段再评估独立检索服务。
【备选】A 一次性迁移到新存储，能力完整但多 3 周迁移和回滚成本。
【需要决定】请在周三 17:00 前确认 B；确认后我按 B 落地并补迁移验证。

决策文档的关键是让决策人知道该批准什么。Atlassian 的 Decision 模板也把状态、影响、驱动者、批准者和截止时间单独列出，避免“讨论过”被误认为“决定了”。

6. 评审与发布：把“能合”与“能上”分开

Code Review 的结论和发布结论不是同一件事。

1
2
3
4

【Review】未发现阻断性问题；1 个 Warning：空状态未覆盖窄屏。
【发布】构建与 migration dry-run 通过；尚未执行生产部署。
【回滚】保留上一个镜像标签，迁移为向后兼容。
【下一步】补窄屏截图后发起部署。

把这些状态拆开，会减少“PR 合了所以线上应该没问题”这种错误推断。

什么时候不该套汇报模板

短问题、单个命令、纯事实查询不需要包装成六段报告。模板只用于复杂、可持续或有风险的交付。若读者只需要一个命令或一个结论，直接给答案更好。

对涉及规划和大范围投入的任务，叙事型方案仍然有价值。Amazon 的 Narrative 方法要求把规划写成连续论证，AWS 的公开说明提到此类文档用于团队和组织规划，正文通常限制在六页以内。AWS Startups 对 Narrative 的介绍适合在 Agent 完成调研后，沉淀为需要人拍板的方案，而不是替代每次代码交付的短报告。

我的判断框架

先问下一个读者要做什么，再决定输出粒度：

1
2
3
4
5
6

继续开发或审查代码 → 交付 / 进行中报告
解除外部依赖       → 失败阻塞报告
确认修复是否可靠   → Bug 诊断报告
批准技术路线       → 方案决策报告
进入下一环境       → 评审 / 发布报告
只要一个答案       → 直接回答，不套模板

对 Coding Agent，好的汇报不是一段漂亮总结，而是一份可以接手的工程状态：事实可定位、验证可复跑、风险有边界、下一步有人能执行。