让 Agent 的执行结果更容易追溯：NagaAgent 中四个 Skills 的调整

在梳理 NagaAgent 的测试与迁移工作时，我让 Agent 按计划执行任务，并生成 Journal，记录每次工作的结果。这也是我整理个人 Testing SOP 项目时，希望逐步建立起来的一种工作方式。

保留这些文档有很实际的用途。以后继续开发、修改已有实现，或者发现某处出了问题，我希望能沿着记录查回去：Agent 当时执行了哪些步骤，改了什么，为什么这样处理，又根据什么判断任务已经完成。

但回看生成的 Journal 时，我发现文档虽然列了很多技术点，读起来却不容易把一次工作的过程和结果连起来。这个问题促使我重新检查文档的组织方式，以及生成它们的 skills。之后，在寻找调整思路的过程中，我了解了 AWS 对 ADR 的说明，也读到了 Anthropic 关于 Agent 自主执行与人工控制的文章。

这篇文章记录的就是这次调整过程。

一、从一份 Journal 的目录看问题

我先回看了两份记录：C0-3 执行报告和 MIG-1 文档迁移报告。前者为 CI 保存结构化测试证据，后者把已有文档迁入新的上游基线，同时说明历史测试结果的适用范围。

两份报告都沿用了 17 个主章节的模板。技术点已经列得这么全，为什么还是很难看懂这次工作究竟是怎么做成的？

以 C0-3 为例，下面是它的全部主章节，并展开了第一节的三个子章节；括号内是补充的中文释义：

markdown 复制代码

1. Work Unit（任务信息）
   1.1 2026-08-31 Closure Evidence
   1.2 为什么需要 C0-3（目的）
   1.3 C0-3 在系统中的作用
2. Learning Objective（学习目标）
3. Initial Understanding（初始理解）
4. Project Review Inventory（项目调查清单）
5. Problem Model（问题模型）
6. Options and Trade-offs（方案与权衡）
7. Decision Record（决策记录）
8. Guided-Learning Checkpoint（引导学习检查点）
9. Requirement-to-Code-to-Evidence Mapping（需求、代码与证据映射）
10. Planned Changes（计划改动）
11. Actual Changes（实际改动）
12. Execution Evidence（执行证据）
13. Deviations and Recovery（偏差与恢复）
14. Remaining Risks and Uncertainty（剩余风险与不确定性）
15. Teach-Back（学习复述）
16. Final Proof（最终验收依据）
17. Next Recommended Task（下一项建议任务）

如果把它当作执行记录来读，我会先找具体改动，再看验证结果和未完成事项。但在这份目录里，这些内容与调查清单、问题模型、学习目标并列展开，读者需要自己安排阅读顺序。

开头虽然已经标了 DONE，具体交付却在第 11 节 Actual Changes。要分清原计划和实际结果，还得对照第 10 节，再到第 12、16 节查看执行证据和验收结论。

如果要追溯为什么失败后仍要上传测试报告，又要把第 5 节的问题模型、第 7 节的决策和第 12 节的验证接起来。相关内容都在，但"发现问题、决定处理方式、执行后确认结果"被拆进了不同栏目。

报告中还有时间上的差别。第 14 节保留着早期"需要测试失败 run 的托管证据"的记录，开头第 1.1 节和第 16 节则说明，这个缺口已在 8 月 31 日关闭。报告交代了这段变化，但直接跳到 Remaining Risks 的读者，还要返回前文确认哪些问题已经解决。

这就是这份 Journal 让我感到"AI 味"的地方：标题、要点和表格很齐全，技术信息却分散在各处。即使熟悉相关技术，也需要来回对照，自己补全发现、决定、改动和结果之间的联系。

当时的 evidence-backed-plan-executor 同时承担实现和教学任务，还默认设置引导学习环节。这能解释报告为什么包含那么多内容。但对 Journal 来说，我需要先看清一次工作的结果，并能从结果找到对应的执行依据。原有结构没有充分照顾这个阅读顺序。

二、记录的目的，是以后能查回这次执行

要修改文档，首先得明确我希望怎样使用它。

Agent 执行的各个步骤，应当能定位到相应的操作记录和结果。任务结束后，Journal 要帮助我把这些记录与具体工作对应起来。过一段时间再看，仍然能分清哪些是计划、哪些已经实际执行，失败之后又发生了什么。

例如，后来修改了 CI 的报告上传方式，我需要找到当时选择这套配置的理由，知道哪些行为已经验证，改动后该重新检查什么。如果一个历史测试结果被拿来说明新分支的能力，我也需要能查到它原来对应的代码版本。

为此，执行记录至少要保留任务、改动和证据之间的联系：

复制代码

计划中的工作单元
  → 实际执行的操作与改动
  → 对应日志、命令输出或测试产物
  → 结果判断及其适用范围
  → 后续修正与当前状态

这些信息可以分别放在日志、代码差异、测试报告和 Journal 中。Journal 负责讲清结果并提供查找入口；详细记录仍然保留在能够定位的来源里。精简正文时，不能顺手删掉唯一一份失败记录或恢复依据。

C0-3：从"运行失败"查到具体证据

C0-3 本身就体现了这种需求。CI 已经能够运行测试，pytest 退出码也能让 Check 变绿或变红。但后续排查还需要知道：哪条测试失败，失败消息是什么，它属于哪个版本、哪次运行和哪次重试。

报告记录的处理包括生成 JUnit、失败后仍尝试上传，以及在 artifact 名称中加入 suite、run ID 和 attempt。JUnit 保存结构化的 testcase 与 failure 信息，artifact 则保存这次运行的产物。

其中，if: always() 让上传步骤在测试失败后仍尝试执行；if-no-files-found: error 用于暴露预期报告缺失的情况。测试断言与退出码继续负责测试结论，上传成功不会抹去测试失败。

验证也经历了补充。早期已有本地 XML 和远端成功运行信息，但缺少完整的失败路径证据。8 月 31 日的补充记录显示，失败运行中 pytest 步骤失败、上传步骤成功；随后完成下载、摘要比对和 XML 解析，结果为 tests=2 / failures=1，并能定位故障断言。恢复运行的报告记录为 tests=2 / failures=0。

如果以后这条路径出了问题，就可以沿着具体运行和测试产物复查。这里仍有范围限制：这些记录没有证明 runner 被强制终止后一定能上传，也没有验证真实 LLM 或完整 Agent 工作流。

MIG-1：追溯时必须带上版本

MIG-1 报告处理的是文档迁移。已有文档记录了旧分支上的测试与 CI 成果，而对应实现还没有随文档迁入新的上游基线。

如果只保留"测试通过"，后续读者很容易把它理解成当前分支的状态。因此，迁移计划要求保留文档，同时写清历史证据尚未在目标分支重新验证。这些区别也进入了迁移状态说明。

报告还记录了一次恢复过程：切换分支后，八份只在旧分支被 Git 跟踪的文档从工作区消失，随后从保留的证据分支恢复。这条记录能帮助后续读者判断文件的来源，也解释了为什么实际执行增加了恢复操作。

MIG-1 没有运行 pytest。它根据分支起点、文件清单、排除规则和迁移说明完成文档迁移验收。报告中的 DONE 对应这个工作单元，后续代码、测试和 CI 的迁移仍有各自的验收要求。

这两份材料其实已经保存了不少追溯依据。我想改善的是它们的组织方式，让读者能从当前结果查到相关步骤，也能看清一条旧记录在哪个版本、哪个阶段成立。

三、AWS ADR 和 Anthropic 的文章给了我什么指导

ADR：留下当时为什么作出这个决定

在思考怎样整理这些内容时，AWS 对 ADR 的说明很贴近我的需求。

ADR 是架构决策记录。AWS 的介绍要求至少保留决策背景、决定本身，以及它对项目的后果，并说明记录选择理由的价值。后来的维护者可以据此理解一项设计，而不必只凭最终代码猜测。AWS：Architectural decision record process

我从中得到的启发是：执行记录除了能查到动作和结果，还应该能找到重要选择的依据。

例如，"给上传步骤加了 if: always()"记录了一项改动；"测试失败时仍需要保存诊断证据，所以让上传步骤继续尝试执行"则补出了它与任务目标之间的关系。以后修改这段配置时，这个理由能提醒我检查失败路径。

工作单元里的选择未必都达到架构决策的规模。这里借用的是保留背景、理由和后果的方式，是否单独写成文档，还要看这个决定的影响和后续查阅需要。

Anthropic：执行过程可以调整，目标与边界要清楚

Anthropic 的 Trustworthy agents in practice 讨论了另一个相关问题：Agent 会根据执行反馈调整行动，人可以通过整体计划和权限保持控制；遇到未知情况时，还需要区分哪些事实可以自行调查，哪些意图或偏好必须交回用户决定。

这让我重新考虑 skill 应该约束到什么程度。

在 NagaAgent 的任务里，Plan 可以提前规定目标、实现要求、范围和验收。项目规范提供长期约束。具体执行时，Agent 仍需要检查当前仓库，根据真实情况选择做法，并留下发生调整的依据。

MIG-1 中恢复那八份文档，就是在既定目标下处理新发现。以后遇到接口变化，也可能需要调整原先设想的接入方式。但如果某个实现要求本来就是明确约束，调整会违反它，或者改变验收条件，就需要先把冲突说明白。

Building effective agents 对预定义工作流和动态执行的区分，也帮助我理解这件事。明确、稳定的检查可以继续交给固定流程，需要结合当前代码作判断的部分则留出调整空间。

这两类资料分别帮助我思考"为什么这样决定"和"执行时如何保留判断空间"。具体怎样拆分四个 skills，仍然是我针对当前记录问题做的设计。

四、最终把职责收敛到四个 Skills

修改过程中，我先缩短 executor 的默认报告要求、取消默认教学暂停，随后进一步把工程决策解释收敛为 evidence-backed-execution-rationale。进度、结果和恢复上下文则各自交给对应的技能。

当前这一轮形成的四个 skills 是：

Skill	主要负责什么	后续追溯时从这里找什么
`evidence-backed-execution-rationale`	结合证据解释重要工程决定	为什么采用这个做法，影响了什么，验证支持到哪里
`evidence-backed-work-unit-journal`	记录一个工作单元的实际结果	改了什么，与计划有什么差异，证据在哪里，还有什么未完成
`plan-progress-checkpoint`	维护任务状态、验收范围和进度记录	某项工作何时推进、依据什么更新状态，对应哪份记录
`plan-reentry-guide`	从计划和证据整理恢复上下文的入口	当前工作到哪里，下一步为什么做它，详细材料在哪里

决策解释保留理由

evidence-backed-execution-rationale 关注会影响行为、依赖、正确性或证明范围的选择。它要求把仓库事实、事实带来的工程问题、采用的决定和验证联系起来。

普通的文件打开、搜索或格式化仍可以出现在执行日志中，但不需要每个动作都附一段决策解释。需要解释的是那些会影响后续维护的选择，例如为什么控制某个测试依赖，或者为什么放弃原先的接入点。

这也保留了学习用途。需要学习工程思路时，可以进一步说明相关原则，以及下次遇到什么情况时值得考虑它。学习说明由任务需要决定，不再默认加入提问、掌握程度标签或暂停环节。

Journal 先交代结果，再链接依据

evidence-backed-work-unit-journal 围绕本次结果组织正文：实际成果、与计划的差异、验收证据、证明边界和下一步。

对 C0-3 这样的任务，读者应该先看到报告保存能力做到了什么程度，再通过引用找到具体运行、失败消息和验证记录。重要的历史材料继续保留，正文无需重复铺开全部调查过程。

如果读者还想了解选择某种方案的原因，Journal 可以链接已有的决策说明。这样，同一份详细解释有明确的查阅位置，也不会在几个文档中反复复制。

Checkpoint 保留进度变化

plan-progress-checkpoint 把工作单元与计划状态对应起来。它保留验收范围，记录有意义的推进结果，并引用 Journal 或证据。

它按一次逻辑上的工作单元执行维护记录，避免每次工具调用、重试或对话继续都变成一条新的任务。需要查具体操作时，再沿着证据链接进入执行记录。

项目已经有台账或状态体系时，也应沿用已有结构。这样才不至于出现一份报告说完成、另一份清单仍待办，却看不出两者关系的情况；存在差异时需要把差异写清楚。

Re-entry 提供重新进入项目的入口

plan-reentry-guide 面向隔了一段时间回到项目的人。它从计划和工作记录中整理目标、当前进展、剩余问题和下一步，并给出深入阅读的位置。

以 MIG-1 为例，这份指南应该提醒读者：文档已迁移，但旧测试结果仍属于原来的版本。需要详细依据时，可以打开迁移状态说明和对应 Journal；需要理解某个实现选择时，再进入已有的 Rationale。

四个 skills 通过这些引用衔接，执行日志和测试产物保存具体事实。它们的职责划分与修改依据，可以在阶段性改动摘录和当前职责说明中查看。

五、修改后的效果，还需要实际使用验证

目前完成的是 skills 的职责与输出规则调整。C0-3 和 MIG-1 都是调整前的历史材料，用来说明我遇到了什么问题，不能作为新版 skills 已经改善记录质量的证明。

接下来需要在真实工作单元中使用这四个技能，再回看生成的文档：能否快速找到执行结果，能否沿着结果查到具体步骤和证据；遇到后续改动或错误时，能否定位当时的版本、决定和恢复过程。

同时，还要检查精简后有没有丢掉必要信息，以及不同文档是否真的通过链接衔接起来。只把报告写短，或者减少几个章节，都不足以说明追溯变得方便。

本文引用的案例来自实践材料索引中的历史报告、计划与技能文件，没有重新执行文中的 CI 或迁移操作。