用 AI 工具做实验最大的敌人不是模型不够聪明,而是同样的坑踩第二遍。这一年我逐渐收敛出一套记录方法,核心只有一条:实验结束的瞬间就是记录的截止时间。这篇把这个方法拆开讲清楚,附上我实际使用的模板。
为什么随手记不行
折腾的过程天然碎片化:查文档、改配置、跑命令、失败了换思路。如果打算「事后再整理」,几乎注定不会发生——下次想起来时,上下文已经丢了,能记起来的只有「当时搞定了」,而当时怎么搞定的、为什么别的路不通,全忘了。
所以我把标准定为:一个实验算不算完成,不看功能跑没跑通,看档案文档写没写完。跑通但没落盘的实验,视为未完成。
记录的三层结构
我的记录分三层,粒度从粗到细:
- 档案(archive):一台机器、一套服务一份文档,记录链路拓扑、关键路径、凭据位置(只记位置,不记真值)。
- 坑点表(pitfalls):每条记录「现象 → 根因 → 解法」,根因写到源码行为级别。比如「NPM v3 登录后 API 全 403」不够,要写成「
user_permission表缺行导致 access.js 构造校验数据时空引用」。 - Skill:当一套流程被第二次执行,就把它从档案里提炼成 agent 可直接执行的 skill,坑点表内嵌其中。
三层的流转关系如下:
关键在于箭头方向:坑点是从失败里长出来的,不是抄别人的最佳实践。我管这个闭环叫坑点反哺——每次踩坑都让下一次「不用再踩」的资产变厚一点。
档案文档的模板
一份能用的档案不需要花哨,我固定用这几个段落:
# <机器/服务名> <主题> 档案
## 链路
(ASCII 图:入口 → 中间层 → 出口,标注端口与协议)
## 组件清单
| 组件 | 位置 | 说明 |
## 安全状态
(防火墙规则、凭据文件路径——只写路径)
## 坑(实测,含根因)
| # | 坑 | 解 |
## 验证命令速查
(可直接复制执行的 curl/ssh 命令)
最有价值的是最后两段。「验证命令速查」意味着任何人(包括未来的我、包括 agent)拿到文档就能** objectively 判断服务是否健康**,不用重新推理。
坑点要写到根因级
「重启后恢复」式的解法记录是负资产:它让下次遇到同样问题时优先怀疑错方向。我的经验是至少追问一层——能读到源码就读源码,读不到就抓日志对比。
一个真实例子:某面板 API 登录后所有 POST 一律 403 空响应体,账密对错都一样。如果停在「重启大法」,这条记录就废了。追下去的结论是:CSRF 中间件在密码校验之前就拒绝了请求,而且 token 藏在 /csrf-token 响应的 .obj 字段而不是直觉上的 .token。这一条坑点值三次排障时间。
让 agent 接管重复流程
记录做到第三层(skill)之后,agent 的角色从「陪聊的助手」变成「拿着操作手册的执行者」。我的判定标准很朴素:
一个新 agent,不依赖本次对话的任何记忆,
只读档案和 skill,能不能独立完成整件事?
能,这套记录才算数。为此 skill 里必须包含验收标准(什么命令、期望什么输出),而不是「配置完成后检查一下」。验收命令必须是可以机械执行的,比如「curl 公网地址返回 200 且出口 IP 为本机」,而不是「确认能访问」。
密钥红线
所有记录只有一个硬约束:凭据真值永远不进 git。档案里只写「密码在哪个文件」,文件权限 600,路径进 .gitignore。宁可多一次 cat,不冒一次泄漏。
这套方法没有技术门槛,难的只是纪律:踩坑的当时多花十分钟把它写下来。复利在第二个月开始显现——那时候你会发现,新问题的排障时间,主要取决于档案里已经有什么。