1. Coding Agent 不是自动写代码是自动做工程1.1 从一次线上告警说起上个月我让一个 Coding Agent 去给项目里所有 API 调用统一加上超时和重试逻辑任务描述写得很清楚它也确实交出了漂亮的一版 diff重构干净、注释到位、相关单测全部补上。我当时觉得这事儿稳了直接合入主分支。结果第二天凌晨监控告警响了——不是代码逻辑出错而是它为了跑通集成测试在容器里执行了apt-get install装了一个系统级依赖这个依赖和线上环境的另一个包冲突导致服务启动时动态链接库报错。这让我意识到一个关键问题用 Coding Agent 最大的风险从来不是它生成的代码有没有 bug而是它为了完成目标所执行的那些看不见的动作。你审得了 diff但未必审得了它在终端里敲下的每一条命令。所以从那以后执行记录这四个字就成了我用 Agent 时的第一关注点这篇就专门聊聊怎么通过执行记录做风险调查。1.2 Coding Agent 的典型工作链路先说清楚一件事现在主流的 Coding Agent比如 Codex CLI、Claude Code 这类终端型工具并不是一个简单的自动补全插件它本质上是一个能自己规划、自己动手、自己验证的工程执行体。它的工作链路大致可以拆成六步理解读取仓库结构、关键文件、任务描述建立对项目的认知。规划拆解任务决定先改哪个文件、后跑什么命令、需要引入什么依赖。执行调用工具shell、文件编辑、代码搜索、测试运行器实际操作。验证运行测试、构建、静态检查确认改动是否符合预期。迭代根据验证结果修正方案失败就重新规划直至通过或放弃。收尾输出最终 diff、提交信息等待人工确认。这六步每一步都会留下痕迹——规划留在日志里执行留在 shell 历史里修改留在 git 里验证结果留在测试输出里。这些痕迹合起来就是执行记录。很多人用 Agent 只看最后一步的代码产物这就是本末倒置。产物只告诉你它想让你看到的结果执行记录才告诉你它真正做了什么。尤其当 Agent 拥有执行权限时它的能力边界已经超越了写代码而是触及了改系统。一个能跑 shell 的 Agent理论上可以安装软件、修改配置、读写文件、甚至拉取远程资源——这些动作的后果远比一段代码里的逻辑错误更严重。所以我认为评价一个 Coding Agent 好不好用第一标准不是它写的代码质量多高而是它的行为是否透明可审计。这也正是执行记录的价值所在。2. 执行记录Agent 的黑匣子里到底装了什么2.1 一份完整执行记录包含的六类信息我复盘过很多次 Agent 的完整执行过程一份可用的执行记录通常包含以下六类信息每一类都有它的独特价值记录类型内容示例核心价值命令调用python -m pytest tests/test_auth.py判断是否有越权操作、非预期命令文件变更前后的 diff、新建/删除文件路径审查代码逻辑是否符合需求构建与测试输出编译日志、测试失败堆栈判断验证环节是否真实通过决策路径Agent 的推理摘要、中途计划调整判断规划是否合理、有无走弯路时间与资源消耗每步耗时、token 数、运行时长识别异常行为比如长时间的静默外部交互网络请求、API 调用、下载行为识别数据外传、供应链投毒风险这里我想特别强调一个容易被忽视的点很多 Agent 工具默认只保存摘要而不是原文。比如 Codex CLI 在交互时会展示每一步的概要但如果你不主动开启完整日志模式那些关键的命令参数、环境变量、真实输出可能会被截断。做风险调查最忌讳的就是拿到一份残废的日志所以从配置阶段就要把记录做完整。2.2 一条命令引发的蝴蝶效应我为什么这么警惕 shell 命令因为 Agent 的很多行为通过 diff 是完全看不见的。举个典型的例子Agent 发现某个测试需要连接数据库但它读不懂现有的环境配置于是它可能执行了一条docker run -d -p 5432:5432 postgres:latest来启动一个临时数据库。看起来无害对吧但这条命令意味着你的机器上多了一个永远在跑的容器占用了端口和内存。这个容器可能覆盖了你原本正在用的5432端口导致本地原有的开发数据库不可用。如果 Agent 后续把连接串写死成了localhost:5432那这段代码在你的 CI 环境里就是坏的。再比如npm install -g、pip install --user、chmod x、sudo这类命令它们的影响范围远超当前项目目录甚至会污染全局环境。我在一次调查中发现Agent 为了加速依赖安装自己往~/.bashrc里写了一个环境变量结果我之后每次打开终端都会加载一个失效的路径。所以做风险调查时第一件事不是看它改了什么代码而是看它执行了什么命令。命令是 Agent 与真实系统交互的唯一通道也是风险最大的入口。2.3 执行记录的时效性问题还有一个实际坑很多 Agent 的会话记录是保存在本地、且可以被自动清理的。Codex CLI 会把历史会话存在~/.codex下但如果你的会话量很大或者你换了机器这些记录可能就没了。我现在的习惯是任何一个重要的 Agent 任务跑完后立刻导出完整会话日志并连同 git diff 一起归档到项目仓库的 docs 目录下。这一步看似麻烦但等到一周后线上出问题、需要追溯这个改动是哪来的时你就会感谢当时那个多花两分钟归档的自己。3. 风险调查方法论从怀疑到实锤要走这几步3.1 静态审查先看 diff再看意图第一步永远是先看 git diff。不是逐行读代码而是看改动的地图改动了哪些文件改动密度是否合理有没有新增奇怪的依赖声明package.json、requirements.txt有没有修改配置文件.env、Dockerfile、CI 配置有没有新增网络相关代码fetch、axios、requests 指向不明 URL这些通过git diff --stat和git diff --name-only就能快速扫出来。我通常还会跑一条git diff --word-diff去看细粒度的文本变化有时候 Agent 会偷偷改掉一个看起来无关紧要的默认值比如超时时长从 3 秒改成 30 秒这种改动语义影响很大但视觉效果很小。3.2 追踪 shell 命令把执行记录当言行录来读第二步是从终端日志里恢复 Agent 的真实行为序列。我建议把执行记录里所有命令抽取出来按时间排序然后问自己三个问题每一条命令和任务目标是否相关有没有命令涉及安装、下载、权限变更、系统配置有没有命令的运行时间异常长、或反复执行了多次有一次我发现 Agent 连续执行了 40 多次npm install每次都是装了一部分又中断重来。虽然最终代码没问题但这个行为本身就是在烧时间和 token——更重要的是反复安装依赖增加了从非锁定版本中拉取到恶意包的概率。这里有一个实用的排查技巧如果是本地会话直接翻 shell 的历史记录如果是 CI 环境看 runner 的 step 日志。命令级日志是风险调查的核心证据没有它其他所有分析都是猜测。3.3 依赖与配置变更最容易被忽略的定时炸弹很多 Agent 风险事件最后都追溯到依赖和配置层面。原因很简单代码逻辑错误会立刻爆炸但依赖变更往往是延迟引爆的——今天引入一个传递依赖两周后才被发现它和另一个包冲突。我建议重点关注三类变更依赖锁定文件的变化package-lock.json、poetry.lock里有没有新增包新增的包是不是知名来源版本号是不是被固定了CI/CD 配置的变化Agent 有没有修改.github/workflows/、.gitlab-ci.yml改了什么 step运行时配置的变化环境变量、启动参数、数据库连接串、缓存配置。我的做法是做一个变更清单表格把 Agent 每次任务涉及的文件按风险等级分类代码文件是低风险配置文件中风险依赖锁文件和 shell 脚本是高风险。每次合入前过一遍这个清单基本能做到心里有数。3.4 运行时验证让 Agent 自己证明改完没坏静态审查只能发现问题不能证明正确。所以最后一步是运行时验证。我强烈建议不要让 Agent 只跑自己的测试而是让它同时跑与本次改动相关的既有测试套件并且抽查几个相邻模块的测试。为什么是相邻模块因为 Agent 的规划通常是局部的它不会主动考虑你的代码库里 A 模块和 B 模块之间那些隐蔽的耦合关系。有一次它重构了一个内部工具函数自己的单测全过了但另一个模块对这个函数有用**kwargs传参的隐式依赖改动后那个模块静默报错。这种问题只有跑全量或相邻测试才能发现。如果项目允许我还会要求 Agent 在执行记录里明确标注验证命令和验证结果这两行信息是判断它是否真的做了验证、还是嘴上说测试通过的试金石。4. 实操参考用 Codex CLI 跑一次完整的风险复盘4.1 环境准备从安装到开启完整日志这一节用 Codex CLI 举个例子因为它是目前比较好拿来做演示的终端型 Agent——当然方法论完全适用于其他同类工具。先把环境准备好。Codex CLI 目前的安装方式很简单通过 Homebrew 安装后需要登录 ChatGPT 账号完成认证# 安装 Codex CLI brew install codex # 登录认证会跳转浏览器完成登录 codex login这个小工具我实际用下来稳定性还可以但有一点必须提醒默认配置下它的输出是偏精简模式的很多底层细节会被压缩。做风险调查之前建议先确认日志级别。如果你用的是类似架构的工具找到它的配置项把输出级别调到最详细同时确保会话历史默认保留{ log_level: debug, save_session: true, auto_approve: false }auto_approve: false是特别重要的一项——让 Agent每次执行 shell 命令前都要征求你的同意。这会牺牲一部分流畅度但在高风险任务中这是最有效的一道防线相当于给 Agent 的每个动作都装了一个确认闸门。4.2 让 Agent 执行任务并保存完整记录假设我们现在要让 Agent 做一个有风险的操作优化某个服务的内存占用。我的做法是这样的第一步单独开一个干净的工作分支避免 Agent 的改动和别人的未提交内容混在一起git checkout -b feat/agent-memory-optimization第二步在任务描述里明确要求它记录每一条命令并保留完整输出codex 分析 src/service.py 中可能造成内存泄漏的写法给出优化方案并实施。 要求1. 每次执行 shell 命令前先说明目的2. 把所有命令及输出完整记录到 /tmp/agent-trace.log3. 修改完成后运行 pytest tests/test_service.py 和你认为相关的所有测试。第三步让 Agent 跑完后把会话历史导出来归档。Codex CLI 会在本地保存会话可以通过它提供的历史命令找到对应的会话记录复制出来作为调查基线。这一步的关键是把 Agent 变成了一个自带口供的嫌疑人——它自己记录了全部行为后面出了问题逐条对质就好。4.3 复现、提取证据、定位根因任务跑完后我做了一次标准的风险调查整个过程大概如下先用静态审查看改动范围发现它改了三个文件src/service.py、tests/test_service.py、requirements.txt。diff 本身没有明显问题内存优化逻辑也合理。但我的注意力立刻被requirements.txt吸引了——为什么一个内存优化任务需要改依赖我打开执行记录发现它执行过这条命令pip install memory-profiler这个命令本身没问题但问题是它在requirements.txt里加的不是memory-profiler而是psutil5.9.8——因为它发现memory-profiler依赖psutil而现有环境的psutil版本比较旧就顺手做了升级。它认为这是合理的但实际上那个旧版本是一年前故意固定下来的因为新版psutil在某个内部组件上有兼容问题。如果我只看 diff很可能就把这次依赖升级当成顺便优化放过去了。但通过执行记录我看到了完整因果链条然后手动把它升级的那一行撤销重新跑了一遍全部测试确认没有回归问题才算处置完毕。4.4 调查结论的归档模板做完风险调查后我会按固定模板归档方便日后追溯任务标识分支名、提交 hash、会话 IDAgent 配置模型版本、日志级别、审批策略执行摘要共执行 N 条命令修改 M 个文件耗时 X 分钟高风险动作安装依赖清单、配置变更、网络交互处置决定全部接受 / 部分回滚 / 完全撤销复盘结论Agent 哪些行为合理、哪些需要未来约束这个模板看起来繁琐但实际每次只需几分钟填完。它的价值在于三个月后当你需要回溯一个问题时不用重新人肉调查直接翻档案就能定位当时的决策依据。5. 常见问题与排查技巧实录5.1 高频问题速查表我把这段时间处理 Agent 任务遇到的典型问题整理成一张速查表供你们直接对照现象可能原因排查方法Agent 改了很多无关文件规划阶段对任务边界理解有偏差查看决策路径日志下次在提示词里明确只允许修改 XXX 目录测试跑了但代码有问题Agent 只跑了单测没跑集成测试检查执行记录里验证命令的数量要求补跑相关全量测试依赖出现非预期新增Agent顺手解决环境问题审查 lockfile 变更逐个确认新增依赖来源和版本本地环境被污染执行了全局安装或修改了 shell 配置检查执行记录的安装类命令用备份还原系统配置Agent 卡在循环里反复试错任务描述有歧义或环境不满足预期中止后人工澄清需求把前置条件写清楚再重跑执行记录缺失关键步骤日志级别太低或输出被截断调整日志配置重要任务手动开启完整记录5.2 防止垃圾进垃圾出的提示词三条红线很多人以为风险调查是事后的事其实一半的风险在任务下发的那一刻就已经决定了。我总结了三条规定每次给 Agent 派活都抄在提示词里第一明确边界你只能修改 src/ 和 tests/ 目录下的文件不得改动配置文件、CI 脚本、环境相关文件除非先询问我。这条直接堵住了很多顺手牵羊式改动。第二强制自证每次修改后必须运行相关测试并在回复中列出实际执行过的命令及通过/失败结果不允许只描述意图。这条倒逼 Agent 留下实在的执行记录。第三禁止越权不允许安装任何新的系统级依赖或全局包如需新增项目依赖先列出包名、版本和用途等待我批准后再操作。这条相当于把最高风险的动作变成人工把关。你会发现这三条本质上都是把 Agent 的自由度收窄到一个可审计的范围。Agent 的能力越强越需要给它划出清晰的活动边界这跟给员工定权限是一个道理。5.3 团队落地 Coding Agent 的三条组织经验如果说个人用 Agent 是技术活那团队引入 Agent 就是管理活了。这里分享三条经历踩坑后换来的经验一是统一 Agent 的审批策略。如果团队里有十个人各自用默认配置那么这个 Agent 干了什么就会变成一个没人能回答的问题。我建议团队统一要求关键任务必须开启人工审批模式至少对安装类命令强制确认。二是把执行记录纳入 code review 流程。现在的 code review 只审 diff 是不够的至少要在 PR 描述里附上 Agent 的执行摘要让 reviewer 能一眼看到有没有安装依赖、有没有改动配置。我们团队已经把这写进了 PR 模板。三是建立高风险操作的黑名单。我整理了一个命令黑名单全局安装、删除文件、修改权限、直接推送远程分支等以 pre-commit 钩子和 CI 检查的方式强制拦截。效果显著至少帮我们挡住了三次 Agent 要往生产分支直接推代码的行为。5.4 几条真实的心得最后说几条我在多次实战里沉淀下来的体会不一定成体系但每一句都是真金白银换来的心得一永远不要相信 Agent 的我认为。Agent 在日志里写的我认为这不会影响其他模块我已确认兼容性本质上都是它的推理不是事实。只有命令输出、测试结果、构建日志才是事实。调查风险时只看事实不看表态。心得二高频小步比低频大步安全得多。与其让 Agent 一口气完成一个大任务不如拆成三五个小任务每个任务跑完都人工确认一次。虽然慢一点但每个环节的可控性完全不同。我之前不信邪让 Agent 全自动跑一个大重构结果跑了二十分钟中途的某一步引入了一个隐蔽的竞态条件排查花了整整一天。心得三执行记录和代码仓库一样需要版本管理。我现在会在项目里单独建一个.agent-records/目录存放每个 Agent 任务的会话摘要和命令日志文件名按日期-任务命名定期提交。它的作用和 commit 历史完全一样——让我们知道系统是怎么一步步变成今天这个样子的。没有这套记录风险调查就是无源之水。6. 写在最后把 Agent 当外包工程师而不是黑盒工具我个人在实际操作中的体会是Coding Agent 这个工具最危险也最迷人的地方是它把写代码这个行为从思考的结果变成了行为的起点。过去我们 review 的是思考的产物代码现在我们不得不同时 review 行为本身执行记录。这个转变很多团队还没适应。我的建议很简单把 Agent 当成一个远程协作的外包工程师来管理——给它清晰的边界、要求它汇报每步动作、对高风险操作保留审批权、留下完整的审计日志。如果你能接受一个外包工程师不会随意动你的生产环境那同样的标准也应该作用于 Coding Agent。说到底工具本身没有立场风险全部来自怎么用它。执行记录不是一种限制而是一种底气——有了它你才敢放心地把更复杂的任务交给 Agent因为你永远有办法在事后看清它到底做了什么。这比任何模型参数、提示词技巧都重要。