命令能跑但文档过期:让 Codex 生成可验证的 CLI 使用说明

“这个命令我昨天还会用，今天怎么又报错了？”同事把终端截图发到群里，真正缺的往往不是一条命令，而是一份能跟当前代码对上的说明。

很多 CLI 文档只写了 happy path：安装、复制一行命令、看到成功提示。但参数默认值、环境变量、退出码和失败后的处理，常常散落在脚本、配置文件和测试里。让 Codex 做一次“文档考古”，可以把隐含规则整理成一份能复核的使用说明。

先把输入边界说清楚

准备项目目录、入口脚本、配置样例、README 和相关测试。不要把密钥、生产数据或个人令牌直接交给模型。只读分析即可；如果要让 Codex 修改文档，需要明确允许写入的目录。

可以复制下面的提示词：

请只读分析这个项目，生成 CLI 使用说明草稿。
输入：入口脚本、参数解析代码、配置样例、README、相关测试。
请逐项标注来源文件和行号，并区分“代码确认”“测试确认”“推断”“待人工确认”。
输出：
1. 安装与前置条件
2. 命令格式、参数、默认值和示例
3. 环境变量及优先级
4. 成功输出、退出码和常见失败
5. 最小可复现检查步骤
不要执行会写入数据、联网发布或删除文件的命令；缺少证据的内容留空。

用一条小命令验证大部分说明

假设项目有report export命令。Codex 先从参数解析器确认--format默认是csv，再从测试确认json输出的字段。文档中不要只写“支持多种格式”，而要写成：

report export--input demo.json --format json --output out/report.json

随后给出检查方法：确认输出文件存在、读取前两行、检查进程退出码为 0。如果命令依赖REPORT_TOKEN，就写明它是必需变量、从哪里读取，以及缺失时应看到什么错误。令牌值用占位符，不把真实凭据放进示例。

这一步的关键是把“看起来合理”变成“可回到代码和测试复核”。如果 README 说默认输出 CSV，而代码已经改成 JSON，文档应该标出冲突，等待人工决定，而不是替用户猜一个版本。

让结果变成四张小表

一份好说明通常包含四张表：命令参数表、配置来源表、退出码表、故障排查表。每行都带证据位置。比如：

表格能帮助读者迅速发现缺口，也方便下一次代码变更后重新核对。若参数名、默认值或退出码发生变化，只需要定位受影响的行，而不是重写整篇 README。

检查这份说明是否真的可用

交付前做四项检查：

1. 每条命令都能在干净目录中解释输入、输出和权限前提。
2. 参数、默认值、环境变量与当前代码或测试至少有一处证据。
3. 成功与失败各有一个可观察信号，例如文件、日志或退出码。
4. 所有未实测部分明确写“演示”或“待确认”，不把静态阅读包装成实机验证。

如果允许执行命令，先使用临时目录和脱敏样例；如果只有阅读权限，就把执行步骤写成待人工验收项。这样，文档不会因为一次“看起来能跑”的演示而获得虚假可信度。

CLI 文档的价值不是把参数抄一遍，而是让下一位使用者知道：需要什么、会产生什么、失败时看哪里，以及哪些结论仍需要本人确认。Codex 擅长整理分散证据，最终的版本边界和权限决定仍应由项目负责人把关。