CLI 人体工学

CLI 为什么会在脚本里翻车

命令行工具最常见的故障不是崩溃，而是"能用但没法用在流水线里"。比如 --force 的实际含义随子命令变化，--verbose 把日志写进了 stdout，于是 tool --json | jq .name 得到的是一行 Loading...；失败时进程照样返回 0，make 认为构建成功，坏产物被推向下游。这类问题在交互使用中几乎不可见——人会读提示、会手动重试、会猜默认值——但一旦进入脚本，歧义和隐式行为会被精确放大。

这个技能如何工作

它按一份明确的清单审查现有 CLI，关注三类可脚本化指标：

• 词汇层：命令名和 flag 是否使用清晰的动词与名词（lint、deploy），而不是 go、do 这类聪明但无信息量的名字。
• 契约层：--help 是否说明必需输入、输出格式、示例，以及哪些操作不可逆；失败路径是否使用非零退出码，诊断信息是否全部走 stderr，保证 stdout 只输出机器可解析的内容。
• 安全层：破坏性操作是否提供 --dry-run 或二次确认，安全默认是否真的是用户不干预时的默认路径。

审查重点是找出"令人意外"的地方：有歧义的 flag、未记录的默认值、缺失的示例，以及那种只报错误不告诉用户如何恢复的报错信息。

适用边界

这是一个评审型技能，不提供自动化修复，也不修改代码。它适用于你自己维护或打算长期依赖的工具；对一次性脚本或已有成熟规范的项目，收益有限。它也不覆盖交互式 UI（如 TUI 或 prompt 交互）的体验设计，只约束可预测性与可脚本化契约。