概述
Stripe 的开发者体验团队在 2026 年初做了一个系列实验，试图回答一个很实际的问题：怎么让 AI Agent 正确使用你的 API？
他们做了大约 12 个实验，分三类：被动提示（在文件里埋提示）、主动引导（重构 skill 文件、CLI 登录页推装）、分发策略（文档页加安装按钮）。
结果非常清晰：
- 被动提示几乎全部失败——Agent 不读 AGENTS.md、不看 warnings、不浏览依赖目录
- 主动引导和分发策略有效——部分实验效果好得出乎意料
这对所有给 Agent 提供 API 或 SDK 的团队都有直接参考价值：给 Agent 设计开发者体验（DX），是一个分发问题，不是内容问题。
实验背景
Stripe 团队的目标很明确：让 Agent 使用 Stripe 的当前 API 版本、遵循最佳实践、使用 Stripe skill（一组结构化指令和参考，Agent 可以加载来理解 Stripe 平台）。
实验分三类：
| 类型 | 做法 | 假设 |
|---|---|---|
| 被动提示 | API 响应加 warning、SDK 源码加注释、包目录放 AGENTS.md | Agent 像好开发者一样会"注意到"这些信号 |
| 主动引导 | 重构 skill 文件结构、CLI 登录页推装、认证流程加提示 | 把正确信息直接塞进 Agent 的上下文窗口 |
| 分发策略 | 文档页加 skill 安装按钮、CLI 提供一键安装、onboarding 加 AI/agent 路径 | 让开发者在高意图时刻把 skill 装上 |
什么失败了
1. SDK 内部埋提示：完全无效
Stripe fork了自己的 SDK 包，在 README 里加引导文字、在包根目录放 AGENTS.md、在源码里加注释。
假设是合理的——Agent 频繁检查项目文件和依赖来构建上下文。但实际结果是：Agent 几乎从不读取依赖目录内的文件。 所有引导提示都是隐形的。
2. API 响应加 warning：Agent 直接忽略
在 API 响应中加了 warn 字段，提示 Agent 在用过时参数。还在兼容模式的错误消息里嵌入了 skill 安装指令。
结果：Agent 解析 API 响应只取需要的数据，warning 被完全忽略。
Agent 的行为模式
Princeton 的 SWE-bench 项目和 Cognition（Devin 团队）的案例都记录了相同模式：
Agent 不是好奇的开发者，而是赶工期的承包商。 它们识别任务 → 定位代码 → 做修改 → 继续前进。它们不浏览、不探索、不看变更日志。
这对开发者基础设施团队有一个重要推论：如果你的 DX 策略依赖 Agent 通过"探索"发现引导（读 changelog、看弃用通知、浏览相邻文件），它大概率会失败。你必须把指令直接放在 Agent 的必经之路上。
什么有效
1. Skill 文件的渐进式披露（+10% 正确率）
Stripe 对比了两种 skill 格式：
- 单一大文件：所有内容塞在一个文件里
- 模块化结构：顶层 skill 引用可按需加载的子 skill
模块化格式在评估套件中正确率高约 10%，token 用量也明显减少——因为 Agent 只拉入需要的上下文，而不是吞掉整个文件。
这和 Anthropic 的长上下文研究一致：模型对长文档中间部分的注意力会衰减（Stanford 的 "lost in the middle" 问题）。单一大文件里，payments 部分的指导可能很清晰，但读到 billing 部分时注意力已经下降了。渐进式披露绕过了这个问题。
附带好处：模块化结构让不同产品团队各自维护自己的子 skill——payments 团队维护 payments skill，billing 团队维护 billing skill。
2. CLI 登录页推广（30-35% 转化率）
在 stripe login 确认页面加了一个提示，建议用户用一键 npx 命令安装 Stripe skill。
30-35% 看到提示的用户复制了命令。 对一个纯文本插入式提示来说，这个转化率高得惊人。
Stripe 的解读是：用 CLI 的开发者已经处于"agent-adjacent"状态（很多人可能就是被 Agent 指挥来做认证的），所以对能让 Agent 工作得更好的工具天然有接受度。
3. 错误式引导（Error-based steering）：效果最好
当新商户用过时 API 版本请求时，Stripe 从"降级响应"改为"返回显式错误"。
Agent 的反应：可靠地检测到错误 → 识别版本不匹配 → 修正请求。
这和 warning 方案形成鲜明对比。差别很简单：
错误会阻断进度，warning 不会。 Agent 遇到错误必须处理才能完成任务；而 warning，在 Agent 看来，往往只是噪音。
两个核心结论
结论一：给 Agent 设计 DX，是分发问题，不是内容问题
Stripe skill 本身一直很好——指令清晰、结构合理、覆盖面广。限制从来不是"内容够不够好"，而是"Agent 到底有没有加载这些内容"。
每个成功的实验本质上都是分发上的胜利：让 skill 被安装、让正确的子 skill 在正确的时候被加载、让安装命令在高意图时刻出现在开发者面前。
类比：这和经典的手 App 分发挑战惊人地相似。你可以做出全世界最好的 App，但如果没人安装，它就不存在。对 skill 来说，漏斗是：意识 → 安装 → 加载 → 遵循。大部分胜果来自改善前两步。
结论二："硬引导" vs "软引导"是最重要的设计轴
| 类型 | 做法 | 是否有效 |
|---|---|---|
| 硬引导 | 错误、已加载上下文中的显式指令、阻断式响应 | ✅ 有效 |
| 软引导 | warning、提示、相邻文件、带内建议 | ❌ 通常无效 |
这对架构设计有实际影响：
- API 设计：错误消息不只是调试工具，而是你的主要引导机制
- CLI 设计：
--help文本不是锦上添花，可能是 Agent 行动前唯一读的东西 - 文档设计：问题不是信息在页面上"有没有"，而是它是否在 Agent 实际加载进上下文的文本里
这和过去十年开发者工具团队的设计哲学完全不同。面向人类的 DX 是宽容的——开发者会浏览、搜索、交叉引用，最终会找到弃用通知。面向 Agent 的 DX 是不宽容的——Agent 加载上下文一次、执行、继续前进。如果你的引导不在已加载的上下文里，它就等于不存在。
对你的实际影响
| 你的角色 | 需要做什么 |
|---|---|
| 提供 API / SDK 给 Agent 使用 | 把引导塞进错误消息和已加载上下文，不要依赖 warnings |
| 写 Agent skill 或 system prompt | 用模块化结构，不要用单一大文件 |
| 设计 CLI 工具 | --help 和错误消息是 Agent 唯一可能读的东西 |
| 做 Agent 集成 | 确保正确信息在 Agent 启动时就被加载，不要假设 Agent 会自己发现 |
| 用 Claude Code / Cursor 接 API | 优先安装官方 skill，而不是指望 Agent 自己摸索 |
一句话结论
Stripe 用 12 个实验证明了一件事：Agent 不是好奇的开发者，它们是赶工期的承包商。 软提示（warnings、AGENTS.md、注释）它们不看；硬阻断（errors、已加载 skill、CLI 提示）才有效。如果你在做给 Agent 用的开发者工具，停止优化内容，开始优化分发。