文档齐全、llms.txt 可访问、OpenAPI 合法、MCP 能连通，都只能证明 Agent 找到了入口。产品是否真的适合 AI 使用，要看 Agent 能否在真实版本和权限约束下完成任务，并由产品状态而非 Agent 自述证明结果。
把 AI 就绪度拆成五层
很多产品把几个不同问题压成一个 0 到 100 分。分数看起来简洁，却无法指向具体改进。
| 层级 | 要回答的问题 | 最低证据 |
|---|---|---|
| 可发现 | Agent 能否找到入口 | 文档索引、稳定 URL、工具声明 |
| 可读取 | Agent 能否解析材料 | Markdown、Schema、示例与错误说明 |
| 可理解 | Agent 能否选中正确版本和规则 | 检索轨迹、版本与作用域 |
| 可执行 | Agent 能否正确调用接口 | 被接受的命令、工具或 API 请求 |
| 可完成 | 用户目标是否真正实现 | 数据库、UI、API 或文件系统的终态 |
静态扫描适合检查前两层，也可以检查 OpenAPI 或 MCP 描述是否存在。这些指标有用，但它们属于上游。产品真正交付的是第五层。
一个文档站可以写得很完整，同时存在示例过期、权限语义模糊、局部失败不报错、工具返回成功但业务状态未改变等问题。文档容易阅读，产品仍然可能难以被 Agent 使用。
Vercel 的 53%、79% 和 100% 说明了什么
Vercel 用 Next.js 16 任务比较了几种文档供给方式。在强化后的行为评测里，无文档基线通过率为 53%。默认 Skill 同样是 53%，因为 56% 的用例根本没有触发 Skill。加入显式指令后，触发率超过 95%，通过率升到 79%。把压缩后的版本匹配文档索引放进 AGENTS.md，再指向 .next-docs 里的完整文档，该套件达到 100%。
真正可复用的结论是：同一份知识经过不同的发现、触发、排序和版本选择机制，会产生完全不同的任务结果。文档质量从来不是唯一变量。
Vercel 还公开了评测器本身的修正过程。早期套件包含模糊 Prompt、绑定实现细节的断言，以及模型训练数据里已经存在的 API。团队随后改用可观察行为，并加入训练截止后出现的 Next.js 16 API。评测器先变可靠，结果才有解释力。
100% 只属于这套评测与这组条件。它无法推出 AGENTS.md 在所有产品、模型和任务上都优于 Skill。Vercel 自己也把两种机制视为互补。
把产品设为被测系统
常见 Agent Eval 评估的是自家 Agent 有多强。平台与 SaaS 团队面对另一个问题：无法控制用户选择的 Agent 时，产品本身是否仍能被正确使用？
实验设计因此需要翻转。冻结产品版本、任务集、账号、数据和判定器，再轮换模型、Harness、文档方式和工具接口。用户任务保持不变，访问路径作为变量。
用户目标
-> 干净的产品初始状态
-> Agent 加文档或工具
-> 行动轨迹
-> 产品终态
-> 外部判定器
Agent 的最终回答只能证明它认为自己完成了。产品终态才能证明任务完成。
Supabase 的公开实践已经把 Skill 加载、任务完整性和实际工具调用拆开评估。判定器检查真实调用、SQL、文件和有效输出，而非一句已经完成。Supabase 同时明确说明，公开数字来自每个条件仅六个场景，属于早期小样本结果。这个限制本身就是合格评测的一部分。
Stripe 的 AI 仓库把 SDK、工具、Skills 与 benchmarks 放在同一产品面里，说明 AI 可用性同时涉及知识、执行接口和任务环境。大型集成环境证据更强，复刻成本也更高。小团队可以先做一个更小的版本。
一套最小动态任务评测
先从客服工单、新手引导摩擦、常见 API 流程和高代价错误中选 8 到 12 个任务。第一版至少覆盖：
- 一个正常配置任务；
- 一个版本敏感任务；
- 一个权限或认证失败；
- 一个必须先检查环境再行动的模糊请求；
- 一个局部失败后的恢复任务；
- 一个带确认边界的高影响操作；
- 一个允许多种正确实现的任务；
- 一个应该拒绝或升级给人的任务。
每个任务都要定义干净初始状态、用户可见目标、允许使用的资源、时间或成本预算，以及 Agent 无法修改的判定器。
优先验证确定性终态：数据库记录符合预期、部署后的接口返回正确结果、权限规则阻止禁用行为、测试通过且没有无关修改。解释清晰度、恢复方案质量等难以写成断言的指标，可以交给 LLM judge，但要与确定性结果分开报告。
评测摩擦，而不只看通过率
通过率只回答最终有没有到达目标。产品团队还需要知道完成一次任务消耗了多少摩擦。
| 指标 | 揭示的问题 |
|---|---|
| pass@1 | 第一次尝试成功的概率 |
| pass@k | 多次尝试能否至少成功一次 |
| 重复一致性 | 工作流是否稳定，而非偶尔走运 |
| 正确终态率 | 是否满足全部业务不变量 |
| 恢复率 | 错误和局部失败是否可诊断 |
| 工具与检索次数 | 接口和文档摩擦 |
| 时延与成本 | 实际运行预算 |
| 高风险误操作率 | 速度是否掩盖控制失效 |
只报告三次中的最好成绩，测到的是能力上限。报告 pass@1，测到的是默认用户体验。两者都可以存在，但口径必须分开。
公平比较文档、Skill、MCP 与 CLI
这些接口承担不同职责。文档分发知识，AGENTS.md 提供持续项目上下文，Skill 封装条件式流程，MCP 提供结构化实时工具，CLI 提供可执行且可自解释的操作。
比较时保持产品版本、任务、初始状态、判定器、预算和模型 Harness 组合一致，每次只改变一个接口。失败要继续定位到可发现、检索、触发、执行或终态验证中的某一层。
如果 Agent 从未加载 Skill，问题在触发与路由。如果它读到了最新文档，却调用不存在的命令，问题在示例或接口发现。如果工具调用成功，用户目标仍未实现，问题在产品合同或终态定义。不同失效需要不同负责人。
这与四层 Agent Skills 兼容模型和编程 Agent 评测框架指向同一件事：格式通过或榜单高分，只是可部署系统的一层证据。
把能力任务升级为发布门控
新任务先作为诊断用例。产品稳定支持后，再把它加入回归套件。以下任一输入变化都应触发重跑：
- 产品 API、UI 或权限模型；
- 文档与示例；
- SDK、CLI、Skill、插件或 MCP Server；
- 模型或 Agent Harness；
- 认证与沙箱策略；
- 判定器或测试夹具。
每轮保留完整 Manifest：精确版本、任务与判定器哈希、试验次数、预算和时间戳。按失效层级观察趋势，比追逐一个总分更能推动产品改进。
目标也无需永久保持 100%。真正重要的是建立反馈闭环：哪一层产品边界失效、失败成本多高、修复能否跨过下一次发布。
常见问题
产品适合 AI 使用是什么意思？
Agent 能找到正确接口，理解当前合同，在权限边界内执行，从错误中恢复，并让产品到达用户期望的状态。文档可读只是其中一个输入。
Agent 就绪度分数等于任务成功率吗？
两者口径不同。就绪度分数通常检查文件、Schema、协议和抓取能力。任务成功率需要在受控环境中运行 Agent，并核对真实终态。
每个任务要运行多少次？
没有统一次数。行为方差高、失败代价大或预期改进很小时，应增加重复次数。始终公开试验口径，并区分首次成功与 best-of-k。
什么时候使用 LLM judge？
产品状态、权限、数据完整性和安全不变量优先使用确定性判定器。主观表达质量可以增加 LLM judge，并单独报告证据类型。
100% 是否证明产品完全适合 AI 使用？
它只证明已记录配置通过了已定义任务。新任务、新版本、新模型、新接口与真实用户仍可能暴露未测失效。