这篇讲什么
你在代码库上跑了一份 30 页审计，有值得修的 findings，想让编程 agent 去干活。把整份报告一股脑丢进对话看似省事，实际产出是”做了一些重构”——改得含糊、漏 action items。这篇讲的是”chunk → 摘要 → 优先级”模式，把长报告变成 agent 能执行的 brief，外加确认”修对了”的核验循环。
这篇适合谁看
在真实项目里用编程 agent（Claude Code、Codex、Cursor Agent、Aider）的开发者：审计后清理、依赖升级报告、无障碍审计、性能 review、安全 findings。报告来自不同工具（Lighthouse、LLM 审计、人类顾问）、修复用另一个 agent 的场景尤其受益。
什么时候适合用
准备把长分析丢给 agent 之前：多页审计、安全报告、重构提案、技术债清单、架构 review。报告已经 1 页内、范围紧凑就跳过。
什么时候不建议用
单 issue 票和小报告——agent 能直接处理。报告主要是叙事没有 action items 的也跳过，要么先改写成清单，否则任何 agent 上都活不过第一轮。
开始前准备
- 自己先读一遍。你说不出来的，agent 也抓不到。
- 想清目标产出：多个 PR、一个 PR 多 commit、triage 列表、还是后续 ticket。
- 知道哪些 finding 不能商量（安全、破坏性）、哪些是建议（风格、优化）。
- 确认 agent 能访问相关代码——对它看不到的文件下 finding 是浪费。
具体步骤
- 把全报告压成 1 页 brief——不是重写、是 brief。包含：审计标题、范围（审了什么）、Top 3 findings、按严重度的总 finding 数。
- 选 3-5 个 agent 能真做的 action items。其他丢进 follow-up 文件。5 个具体行动赢过 15 个模糊行动。
- 每个 action item 写 mini-spec：
Action 1：把弃用的 request.json() 替换为 await request.json()
- 文件：src/api/*.ts
- 来源：报告 3.2 节
- 验收：现有测试全过、无 console warning- brief + action items 喂 agent。某个 action 真需要时再引用全文。多数 action item 用 mini-spec 单独就能跑。
- 让 agent 一个 action 开一个 PR（或一个 PR 多 commit、每项一个 commit）。原子 PR 好审、好回滚。
- 对照原报告对应 finding 复核每个 PR。闭环——这个 action 真的解决了 finding，还是 agent 修了一个”接近的”？
一个走完的例子
审计报告：“checkout 流程性能 review”，42 页，18 个 findings。
Brief：“性能审计，2026 年 5 月。范围：/checkout/*。Top 3：(1) CheckoutForm 不必要的 re-render；(2) cart.ts 的 N+1 查询；(3) OrderSummary 缺图片懒加载。”
Action items：只取 Top 3，每个 mini-spec 标文件、验收、报告节号。
结果：3 个小 PR。剩余 15 个进 follow-up，下个 sprint 处理。
第一次实操怎么跑
- 拿一份手边的报告。压成 1 页 brief。
- 挑最具体、最 agent 友好的 3 个 action items。
- 用你常用的 agent 跑一个。审 PR。
- 看 spec 哪里不够——通常是缺验收或文件范围不清——下一个 item 前修模板。
完成后检查
- 每个 PR 真的修了对应的 finding，还是修了”接近的”？读原报告 → 读 PR。
- 测试过吗？性能和安全审计常发现”没测试”的 finding，让 agent 提一个。
- agent 引入回退了吗？跑全套测试，不只跑动到的文件。
- follow-up 真的进 backlog 了吗，还是你本想写但忘了？合并前先写下来。
怎么复用这套流程
- brief 模板存片段——标题、范围、Top 3、严重度计数。
- mini-spec 格式存模板。同形状能让 agent 行为一致。
- 建一份”报告入站”清单：读 → 摘要 → 抽 action → 立 follow-up → 跑 agent → 核验 → 立剩余 ticket。
- 每次审计后记”几个 finding 出 PR vs 滑进 follow-up”。低于 70% 出 PR 就说明 brief 太激进。
建议的操作流程
全文 → 1 页 brief → 3-5 个带 mini-spec 的 action items → agent 执行 → 原子 PR → 对照原报告核验 → 剩余 finding 进 follow-up。
容易踩的坑
- 30 页报告一把丢进 prompt。agent 读完、被淹没、给你”general improvements”。
- 只有 finding 没有 action item。finding 是观察，action item 是命令。
- 跳过严重度排序。agent 会挑最容易的，几乎不是最重要的。
- 让 agent 自己挑修哪些 finding。你 triage，agent 执行。
- 整审计一个超级大 PR。原子 PR 审得快、回滚干净。
- 忘了写 follow-up。今天没出 PR 的 finding 不写下来就蒸发。
FAQ
- 报告是 PDF / slides 怎么办？: 先转纯文本。多数 agent 接受 PDF，但 chunk 步骤在纯文本上更容易。
- 做审计的 agent 该自己修吗？: 有时可以——Claude Code 同会话能审 + 修。要无偏 review 就分开”审” + “修”。
- 报告错了怎么办？: 行动前核验 finding。brief 这一步也是对审计本身的一道理性检查。
- brief 该多大？: 最多 1 页。1 页装不下就是审计范围太大、没法行动。