🌐 语言: 中文版 | English Version
使用 Agent 做项目时，即使已经写了指令，有些要求仍会在不同任务里反复解释：写计划前核对已有实现，测试报告说明实际执行了什么，修复以后复验原来的失败场景。一次对话里把要求补清楚，任务可以继续；换个项目或重开会话，相同的缺口又可能出现。问题于是变成：指令究竟缺了什么，怎样根据实际执行过程改进它？
一开始收集 Agent 会话日志，就是为了回答这个问题。当时还发现，所用 Agent 工具的本地日志最多只保留约三个月，更早的记录会找不到。为了能持续回看和分析，先把日志备份出来。最初的目标是据此修订指令，提高它在实际任务中的有效性；随着复盘积累，才逐渐把其中一部分稳定的任务做法提炼成 skills。
摘要：备份有保留期限的 Agent 会话日志，是为了找出指令在实际任务中反复失效的地方，并据此修订。随着复盘积累，稳定的任务做法逐渐形成 skills；投入使用后，再结合使用感受和日志中的执行记录持续调整。
为什么要备份日志
要改进指令，先要保住能说明指令哪里失效的记录。
一次任务结束时，通常能看到最终代码、方案和总结，却未必知道中途哪个判断被纠正。例如，计划起初把一项查询能力列为新增，核对当前实现后改成复用。最终计划只呈现“复用”，会话还保留了先前为什么认为需要新增、纠正发生在什么位置。
这类记录对复盘有用，但不能把 Agent 的解释直接当成事实。需要保留消息顺序、来源会话、项目上下文和原始记录位置；涉及工具执行时，还要核对调用及返回，区分“准备执行”“已经执行”和“执行成功”。日志能保存可观察的对话与工具事件，不能还原模型内部的完整推理。
归档可以把不同工具的记录转换成便于阅读和检索的统一形式，同时保留回到原始记录的路径。阅读层适合发现线索；判断某个命令是否运行、某项代码是否存在，仍要对照原始事件和实际代码。统一格式也不能保证每个来源都完整提取了所有工具事件。
flowchart LR
A["本地会话日志有保留期限"] --> B["备份并统一检索"]
B --> C["回查纠偏与实际结果"]
C --> D["修订共用指令"]
D --> E["稳定的任务做法提炼成 skill"]
因此，备份日志不是为了单纯保存历史。它解决的是本地记录过期后无法回查的问题，也为判断“现有指令为什么没有起作用、下次该怎样修改”提供材料。
用纠偏修订指令
指令要写清可检查的判断依据，而不只写期望的态度。
复盘不必平均阅读每一句对话。更有价值的是找到被纠正的地方：方案为什么重写，测试为什么不能算通过，某次操作为什么改变了待测条件。然后区分，这个问题来自一次性的业务信息、特定环境，还是跨任务都会遇到的协作缺口。
以上述查询能力为例，下表是脱敏后的决策概括，不是会话原文：
| 起初的判断 | 回查时要核对 | 可以复用的规则 |
|---|---|---|
| 为需求新增查询能力 | 现有入口、调用方、返回契约与过滤条件是否已经覆盖需求 | 实施计划逐项写明当前行为和代码依据，再判断复用、修改或新增；新增要说明现有能力为什么不够 |
“认真阅读代码”很难检查是否做到。计划若列出实际代码位置、需要改变的差异、调用方影响和对应测试，下一位执行者就能继续核对。这个场景里，测试预期也要随决定变化：验证复用入口满足新需求，并回归受影响的调用方，而不是继续验证一个并未新增的接口。
测试报告的纠偏有相同结构。“测试文件存在”“测试进程启动”“业务行为通过”是三种不同事实，不能合并成“测试完成”。因此，规则落到每项用例的实际结果、版本、环境与观察；未执行和受阻分别标明。涉及页面与业务数据时，再核对操作、请求、持久化和关联结果。
这些发现先用于修订指令，而不是一发现问题就新建 skill。筛选时有一道边界：某个业务字段的含义应留在项目里；“计划要对照当前实现”“报告要区分执行状态”才可能写进共用指令。历史复盘依赖关键词筛选、抽样阅读和具体会话补查，并未覆盖全部日志，也不能据此统计模型失败率或量化规则的收益。
何时从指令提炼出 skills
共同边界与任务步骤适用范围不同，放在同一个入口会增加阅读和维护成本。
最初，复盘得到的约束用于改进 AGENTS.md。随着指令不断细化，“保护已有改动、遵守授权、如实报告验证”和“怎样调查故障、记录缺陷、执行业务验收”开始混在一起。前者在多数任务里都适用，后者各有输入、步骤、证据和完成条件。这时才有了把任务做法拆成 skills 的理由。
| 放置位置 | 保留什么 |
|---|---|
| 项目规则 | 业务语义、技术约束与环境前提 |
共用 AGENTS.md |
授权边界、已有改动保护、证据与交付要求 |
| 任务 skill | 某类任务的输入、操作顺序、交接内容与完成条件 |
例如，从“测试完成说不清”提取的共同规则是如实区分已执行、未执行与受阻；业务验收 skill 再规定如何依据确认用例核对页面、接口、数据和关联汇总。从“修复后无人复验”提取的规则是保留原失败场景；对应的交付流程再明确开发修复、Review、独立测试复验和问题关闭的顺序。
这样，skill 不是把一次会话保存成模板，也不是给每个小问题建一个入口。它是指令逐步改进后，对一类稳定任务做法的整理：什么时候进入、需要什么输入、产出什么证据、何时结束或交还给人。已有工具和流程能覆盖时，应复用或合并，避免两套规则给出不同预期。
一个逐渐形成 skill 的例子：多 Agent 交接
交接失败往往不是缺少执行者，而是下一位执行者拿到的依据不一致。
复盘中，开发拿到修订后的设计、测试却沿用旧用例，或者测试期间代码变化而报告只写“通过”，都会让结果失去可判定性。相应的规则不是简单要求“多沟通”，而是让详细设计与唯一权威测试用例属于同一确认版本，并在交接时带上代码基线、当前差异、环境前提和本轮范围。
沿用查询能力的场景：开发依据“复用现有入口”的修订决定实现；Review 检查有无重复实现和调用方影响；测试按同版用例验证查询结果及关联回归。明确违反既定预期的缺陷，可继续修复、复查和复验；若过滤条件的业务含义尚未决定，则必须交还给人，更新设计和用例后再继续。
flowchart TD
A["人工确认设计、用例与实施授权"] --> B["开发实现与自测"]
B --> C["主 Agent Review"]
C --> D{"符合确认预期？"}
D -- "明确偏差" --> B
D -- "符合" --> E["独立测试"]
E --> F{"测试结果？"}
F -- "明确缺陷" --> B
F -- "通过" --> G["核验证据并交人工验收"]
D -- "业务预期未定" --> H["人工裁决并更新契约"]
F -- "业务预期未定" --> H
H --> B
这里的主 Agent 负责交接、Review 和证据核验；“交接契约”指同版设计与用例，以及授权和版本前提。它可以推进已确认范围内的循环，不能自行补上新的业务决定，也不能把实施授权延伸成 Git 提交、推送或发布授权。流程因此需要更多版本和证据记录，但每轮修复有了相同的判断基准。
规则能约束到哪里
写成 skill 只解决规则表达，不能代替工具权限和实际验证。
指令能要求执行者在操作前核对授权、遇到共享状态冲突时停止；真正的权限限制、资源锁和进程隔离仍由工具与环境提供。格式和链接检查能发现文档结构问题，行为是否符合规则则要放进具体任务观察：只读任务有没有保持只读，未执行的测试有没有如实报告，已有确认有没有被正确复用。
skill 开始运行后，复盘并没有结束。用过一段时间，对它是否顺手、哪里反复需要人纠正，通常会先有直观感受；备份的会话日志则可以把这种感受落到具体任务上：它是否按预期进入了流程，执行到哪一步，交付物和验证结果是什么，在哪个判断点停下或走偏。再对照实际代码与结果，才能判断问题出在指令表述、skill 的步骤、任务前提，还是一次性的业务情况。
这些观察会反过来推动修订。步骤遗漏就补足输入或完成条件；某条规则只适用单个项目，就移回项目；与现有流程重复，则合并入口。下一轮运行后再看日志，检查同类问题是否还会出现。这样，日志既是最初改进指令的依据，也是 skill 投入使用后的持续反馈来源。
适用范围与代价
跨项目反复出现的协作偏差，先用来修订共用指令；输入、步骤和完成条件逐渐稳定的一类任务，才值得进一步做成 skill。一次性的小修改或单篇文档编辑，保留关键依据和实际验证即可，不必引入完整的多 Agent 交接。
这条路径也有成本：日志要持续备份和回查，指令要随实际偏差校正，skills 要避免重复入口。我的取舍是先用日志改进指令，等某类任务的做法确实稳定，再将它提炼成 skill。