要沉淀什么
自动化资产真正需要被记住的不是命令本身，而是背景：这条任务的前提条件是什么、失败会有什么后果、为什么用这个参数而不是别的、曾经的故障是如何处理的。这些内容写在任务注释与仓库说明里，与代码一起被版本控制和评审，才能在人员变动后仍然可读。变更记录与事故复盘则提供了「历史上为什么改过」的线索，缺少它时同样的坑会被反复踩。
基本信息
| 资产内文档 | 任务注释、参数说明、前置条件与副作用 |
|---|---|
| 仓库文档 | 环境说明、凭据获取方式、执行入口与责任人 |
| 变更记录 | 提交信息、关联工单、评审意见 |
| 复盘记录 | 事故时间线、根因、改进项与责任人 |
有效沉淀的做法
- 注释写原因：说明为什么这样写，而不是重复命令本身做什么。
- 文档与代码同仓库：避免文档散落在个人笔记与聊天记录里。
- 变更随提交说明：提交信息写清影响面与验证方式，便于回查。
- 事故复盘留改进项：每条改进项落到人、落到时间，并在资产里体现。
- 新人可用性检查：让新人按文档独立完成一次非破坏性执行，检验文档是否可用。
- 定期清理过时文档：明确归档规则，避免过期内容误导执行。
文档类型与要点
| 类型 | 写什么 | 常见缺陷 |
|---|---|---|
| 任务注释 | 前置条件、副作用、参数含义 | 只复述命令 |
| 仓库说明 | 环境、凭据、入口 | 缺少更新，路径已失效 |
| 变更记录 | 原因、影响面、验证方式 | 只写「优化」或「修复」 |
| 事故复盘 | 时间线、根因、改进项 | 只写过程不写改进 |
| 新人上手说明 | 从零到一次成功执行 | 跳步，缺前置依赖说明 |
判断文档是否有效，看它能否回答「半年后能不能安全地改这条任务」。如果读完仍然只能靠找作者确认，说明文档记的是操作而不是判断。
文档工作量要与变更风险匹配：影响面大的资产要求更完整的说明，一次性脚本标注有效期即可，不必强行补全。