ava-grace-zoe/agent-facing-design

agent-facing-design 执行规范

核心前提：Agent 消费的工具和文档，验收标准不是"人能读懂"，而是"一个能力受限的 Agent 仅凭文档能独立完成任务"。

适用场景

• 新建面向 Agent 的 CLI 工具或 SDK
• 审查/改进 AGENTS.md、SKILL.md 或其他 Agent 消费的文档
• 合并多个脚本为统一 CLI 入口
• 设计跨数据源的统一视图模型（多种输入 → 单一规范输出）
• 评估现有工具的 Agent 可用性

一、工具设计原则

1.1 CLI 自描述性

CLI 的 --help 输出必须是完整的使用合同，不依赖外部文档补全语义。

检查清单：

| 检查项 | 要求 | |--------|------| | 子命令描述 | 每个子命令的 description 能独立说明"做什么、输入什么、输出什么" | | 参数默认值 | 所有有默认值的参数在 help 中标注默认值 | | 参数适用范围 | 跨子命令共享的参数（如 --env）明确说明适用于哪些子命令 | | 互斥参数 | 互斥的参数组合在 help 中标注（如 --capture <dir> 与 --session-id <id> 二选一） | | 输出说明 | 命令产出文件时，说明输出目录和文件结构 | | 前置条件 | 需要其他服务运行、需要先执行某个子命令等，在 help 或 description 中提及 |

1.2 输出与交互的 Agent 适配

这一节是 agent-facing CLI 区别于普通 CLI 的核心——决定 agent 能不能用得动。

默认模型可读优先。这个 CLI 的主消费者是模型，所以默认输出就是模型可读的；人类装饰版（对齐、颜色、emoji）是需要显式 opt-in 的（如 --human / --pretty），而不是反过来。

• 具体格式按数据形状定，不强绑 JSON：结构化对象用 JSON，平铺记录用 CSV / TSV，单值用裸字符串。原则是「无歧义、易解析」，不是「一律 JSON」。
• ❌ 默认输出对齐表格 + 颜色，让 agent 用正则去切；agent 想要结构化还得自己发现有没有 --json。

退出码 + 流分离是 agent 的成败信号。agent 先看 exit code，再看内容。

• ✅ 成功 0、失败非 0；正常结果走 stdout，错误/诊断走 stderr，两者可分别捕获。
• ❌ 出错也 exit 0、报错混在 stdout 里——agent 会把失败当成功继续往下走。

错误信息的验收标准是「可操作」，不是「可理解」。报错要让 agent 看完知道下一步敲什么。

• ✅ 缺少 --env，可选值 dev|prod，例：--env dev
• ❌ Error: invalid configuration（agent 卡死，不知道改哪）

--help 不能依赖 TTY、不能进分页器。agent 跑 cmd --help 若被 less 接管会挂起等输入；颜色码在非 TTY 下会变乱码。

• ✅ help 一次性打到 stdout，非 TTY 自动关掉分页和颜色。

破坏性操作要可预演、要显式。agent 容易重复或误执行。

• ✅ 删除 / 覆盖类命令支持 --dry-run 先预览影响；真执行需显式 flag；help 标注哪些子命令是破坏性的。

参数命名跨子命令一致。agent 靠模式复用——一处学会 --out，别处就指望也叫 --out。

• ❌ 一个 --dir、一个 --output、一个 -o，agent 每次重猜。

产出路径要可预测或回显。命令生成文件后，agent 必须知道文件在哪。

• ✅ 把生成的绝对路径打到 stdout（结构化输出里带 path 字段最佳）。
• ❌ 写进带随机时间戳的目录又不告诉 agent 路径。

1.3 数据模型收敛

当工具需要处理多种数据源时，先设计统一的输出视图模型，再实现各数据源的 adapter。

执行顺序：

1. 枚举数据源：列出所有输入来源及其原始数据形状。
2. 定义统一视图：设计一个最小充分的输出模型——只包含消费者需要的字段，不保留数据源私有细节。
3. 区分消费者：默认输出服务模型（结构紧凑、无冗余），人类装饰视图是显式 opt-in。若 AI 和人类需求差异大，设计独立的视图类型，而非用 flag 在同一结构上切换。
4. 实现 adapter：每个数据源一个转换函数，输入原始数据，输出统一视图。
5. 实现 renderer：视图到最终输出格式的转换。

让模型视图"紧凑"，落到具体动作（"结构紧凑"不能停在口号）：

• 扁平优于深嵌套：模型逐层取字段易错，能平铺就别套三层。
• 枚举用字面量字符串，别用数字码：status: "active" 而非 status: 1——agent 没有码表。
• 时间带明确单位：createdAtUnixMs 而非 ts；或直接 ISO 字符串。
• 去掉 UI-only 字段：颜色、图标、排序权重对 agent 是噪声。
• 布尔就用布尔：别用 0/1 表达 true/false。

字段名自解释：agent 没有 UI 上下文，全靠字段名推语义。命名要让"只看这个 key 就懂含义"。

空值表达统一：null / 缺字段 / 空字符串三者不要混用——agent 对"字段不存在"和"字段为空"的处理是分叉的。定一条规矩（如「无值就省略该字段」）并贯穿所有 adapter。

反向约束——不要过度收敛：砍掉的应是"数据源私有细节"，不是"消费者可能用到的语义字段"。砍过头会逼 agent 回头再查一次原始源，比不收敛更糟。判断标准：这个字段被砍掉后，agent 还能不能仅凭输出完成任务。

1.4 合并脚本的判断标准

多个独立脚本应合并为统一 CLI 的信号：

• 共享相同的外部依赖（API endpoint、认证机制、数据库）
• 输出的数据最终会被同一个消费者串联使用
• 存在重复的工具函数（HTTP client、数据清洗、格式化）

合并时保留各子命令的独立性——每个子命令可以单独执行，不强制要求按特定顺序调用。

合并对 agent 的真正收益是「降低发现成本」：散落的多个脚本，agent 得先知道它们存在；统一成一个 CLI，--help 一次就看全入口。因此所有子命令必须在顶层 --help 中列出——否则 agent 发现不了的子命令，等于没合并。

二、文档编写原则

2.1 AGENTS.md 的读者是 Agent

AGENTS.md 的消费者是其他 AI Agent，不是人类开发者。关键区别：

| 人类文档 | Agent 文档 | |---------|-----------| | "详见 --help" 够用 | Agent 可能无法运行 --help，需要文档内提供完整命令 | | 描述概念和原理 | 提供 copy-paste-ready 的命令序列 | | 可以跳读、搜索 | 按执行顺序线性阅读 | | 理解省略和暗示 | 需要显式写出每个参数和步骤 |

2.2 必须包含的内容

对每个工具或 CLI，AGENTS.md 中至少包含：

1. 完整命令示例：覆盖最常见的 3-5 个使用场景，每个示例可直接复制执行。
2. 输出文件说明：命令产出的文件路径和每个文件的内容摘要。
3. 参数默认值：Agent 无法从 help 推断哪些参数可省略。
4. 跨命令参数说明：如 --env 适用于哪些子命令，在文档中一句话说清。
5. 失败处理：常见错误的排查步骤，包含具体的诊断命令和日志路径。
6. 前置条件：需要先运行的服务、需要先执行的命令。

2.3 不应包含的内容

• 内部实现细节（Agent 不需要知道用了什么库）
• 过长的参数解释（--help 负责这个）
• 已过期的 session ID、示例输出、临时 workaround
• 重复其他文档已覆盖的内容（给链接即可）

三、Subagent 冒烟验收

这是本 skill 的核心验收手段：用一个能力受限的 Agent 模拟"只读文档"的场景，检验文档是否自足。

3.1 实验隔离原则

这是一个受控实验，必须遵守标准实验流程。核心要求：subagent 的上下文必须与执行者的上下文完全隔离，模拟一个从零进入的 Agent 的真实体验。

为什么隔离：如果 subagent 能从 prompt 措辞、暗示、工具权限中获得文档之外的信息，测出来的是 AI 的推理补全能力，不是文档质量。信息泄漏会导致假阳性——文档有缺陷但测试通过。

隔离清单：

| 维度 | 要求 | 违反示例 | |------|------|---------| | 上下文继承 | subagent 必须是全新实例，不继承当前会话历史 | 在同一对话中让 AI "假装没看过"——它看过了 | | 信息输入 | 只提供被测文档的原文，不做任何改写、摘要或补充说明 | 在 prompt 里写"这个 CLI 用于调试 agent session"——这就是泄漏 | | prompt 中立性 | prompt 只描述目标任务，不暗示实现方式或预期命令 | "用 inspect 命令查看 session"——已经告诉它用哪个子命令了 | | 工具权限 | 禁止 Read/Bash/代码搜索——真实消费者只有文档 | 给了 Bash 权限，subagent 自己跑了 --help | | 模型能力 | 使用低级模型（如 haiku），避免高级模型凭推理补全文档缺陷 | 用 opus 测试——它能猜对缺失的参数，掩盖了文档问题 | | 场景描述 | 用业务目标描述任务，不用技术术语暗示路径 | "从 Console API 拉取 session"——已经泄漏了数据源名 |

执行模板：

你是一个需要使用开发工具完成任务的 AI Agent。
你只能依据下面提供的文档来推演命令，不能假设文档之外的任何信息。
如果文档中缺少完成任务所需的信息，明确指出缺少什么。

## 文档

{被测文档原文，不做任何修改}

## 任务

请针对以下每个场景，推演出完整的命令序列：

1. {场景描述——用业务目标而非技术路径}
2. ...

反模式警告：

• 不要在场景描述里使用文档中的子命令名——让 subagent 自己从文档中发现入口
• 不要解释"为什么要做这个测试"——那会泄露你对文档薄弱点的预判
• 不要对文档做"友好化"预处理（去掉无关章节、加粗重点）——真实 Agent 拿到的就是原始文档

3.2 场景设计

设计 3-5 个覆盖不同使用路径的场景，每个场景描述一个具体目标：

• 首次使用：从零开始完成一次完整操作（安装 → 配置 → 执行 → 查看结果）
• 常规使用：最高频的日常操作
• 故障排查：遇到常见错误时的诊断步骤
• 跨环境操作：涉及环境切换（如 prod/dev）的操作
• 进阶组合：需要串联多个子命令的复杂流程

3.3 评估标准

对 subagent 的输出逐场景检查：

| 结果 | 含义 | 行动 | |------|------|------| | 命令完全正确 | 文档覆盖充分 | 无需改动 | | 命令基本正确但缺少参数 | 文档缺少某个参数的默认值或适用说明 | 补充参数说明 | | 命令方向正确但路径错误 | 文档缺少关键路径信息（日志路径、输出目录等） | 补充具体路径 | | 完全无法推演 | 文档缺少该场景的入口信息 | 补充完整的命令示例 | | 推演出错误命令 | 文档存在歧义或误导性描述 | 重写相关段落 |

3.4 迭代

修复文档后，可选择再次执行 subagent 冒烟验证，确认修复有效。通常一轮修复即可收敛——如果两轮后仍有大量问题，说明文档结构需要重新组织而非逐处修补。

四、文档腐化审计

定期审查已有文档的健康度。

4.1 腐化信号

• 命令引用的脚本路径已不存在
• 参数名或子命令名与实际 --help 不一致
• 示例中的 session ID、URL、端口号已过期
• 引用的外部文档已删除或重命名
• "临时"标注的 workaround 已超过 30 天

4.2 审计方法

1. 提取文档中所有文件路径，验证存在性。
2. 提取文档中所有命令，与实际 CLI 的 --help 交叉比对。
3. 检查"先读哪个文档"索引表中的链接有效性。
4. 标记所有含日期、ID 或临时标注的段落。

输出要求

执行完成后，输出：

1. 变更摘要：改了什么、为什么改。
2. Subagent 验收结果：每个场景的通过/失败状态和关键发现。
3. 剩余风险：未覆盖的场景或已知的文档薄弱点。