Stripe 的 llms.txt 有一个 instructions 部分。这比听起来更重要。
Source: Dev.to
Why This Matters
This post is a follow‑up to [API Design Principles for the Agentic Era]. That article covered the broader shift in how APIs need to be designed for autonomous consumers. Here we dive deep into one specific mechanism: the llms.txt instructions section.
独特指令章节
在 docs.stripe.com/llms.txt 中，你会看到如下块：
# Instructions for LLMs
You are an AI assistant that helps developers understand Stripe’s API.
When answering questions, you must:
1. Cite the official Stripe documentation.
2. Provide code examples in the language requested.
3. Avoid speculation; if the answer is unknown, say so.
4. Highlight any upcoming deprecations or beta features.有何不同
- 自描述行为 – 文件告诉语言模型 如何 谈论 Stripe，而不仅仅是 说什么。
- 强制最佳实践 – 通过要求引用、代码示例以及对未知的明确处理，Stripe 确保 AI 生成内容的一致性和高质量。
- 面向未来 – 提及废弃或 beta 功能，使开发者在无需手动更新的情况下了解即将到来的更改。
对您的 API 的影响
- 对 AI 输出的控制 – 将指令直接嵌入文档，使您能够引导第三方 LLM 如何呈现您的服务。
- 降低支持负担 – 一致且准确的 AI 响应可以减少重复性支持工单的数量。
- 文档即代码 – 将文档视为可执行的工件（例如，LLM 读取的
.txt文件），鼓励使用版本控制和可测试的文档。
要点
- 在自己的 API 文档中采用指令章节，如果你想影响 AI‑驱动的交互。
- 使指令明确且有版本，以便它们随你的 API 演进。
- 监控 AI 使用情况，确保遵守指南，并随时间进行优化。
通过遵循 Stripe 的做法，你可以将 AI 时代从模糊的流行词转变为开发者体验中具体且可控的一部分。
大型语言模型代理的指令：集成 Stripe 的最佳实践
- 始终使用 Checkout Sessions API，而不是旧版 Charges API
- 默认使用最新的稳定版 SDK
- 绝不推荐使用旧版 Card Element 或 Sources API
- 建议将 PaymentIntents 迁移到 Checkout Sessions
- 优先使用动态支付方式，而不是硬编码的
payment_method_types
注意： 这 不是 文档，而是一个 提示——作为 Stripe 域根目录下的静态文件发布——旨在在开发者询问 “如何添加 Stripe？” 之前加载到 AI 编码助手中。
Stripe 正在编程 AI 工具对 Stripe 的描述。每当开发者向 Cursor、Claude 或其他助手询问如何接受付款时，代理都会先获取此文件，并将这些指令传播到答案中。它们不仅仅是让文档对机器可读；它们正在大规模塑造第三方 AI 系统的行为。
起源
Jeremy Howard（fast.ai，Answer.AI）在 2024年9月 提出了这一标准。它解决的问题非常真实：
- 大语言模型的上下文窗口是有限的。
- HTML 内容噪声很多。
- 你无法把整个文档站点一次性塞进提示中。
他的解决方案故意保持低技术门槛：在 /llms.txt 中放置一个 Markdown 文件，内容包括：
- 一个 H1 标题。
- 一个可选的摘要块引用（blockquote）。
- 用 H2 分隔的、经过挑选的链接章节。
配套的 /llms‑full.txt 则将完整文档汇总在一个文件中。任何单独的页面都可以通过在其 URL 后追加 .md 来获取干净的 Markdown 版本。
这种格式刻意保持平淡——没有特殊语法、没有模式、没有 JSON——仅仅是 LLM 已经能够原生理解的普通 Markdown。关键的洞见在于 策展：你比任何爬虫都更了解自己的文档，因此应该告诉 AI 代理哪些部分重要。
它类似于维护良好的 robots.txt——不同的是，它提供 优先级 而不是排除。robots.txt 告诉爬虫跳过什么，sitemap.xml 告诉它们有什么，而 llms.txt 则告诉 AI 先读什么。
当前采用
- 没有主要的 AI 提供商确认他们的训练爬虫会自动获取
llms.txt。 - 它今天的真正价值在于推理时，而非训练时——开发者手动将其加载到 Cursor、Claude 或其他代理中以获取项目上下文，或框架在启动时获取它。
- BuiltWith 追踪的 800 k+ “实现”大多是 Yoast SEO 为 WordPress 网站自动生成该文件。手动整理的数字更接近 784 个已验证站点。
示例
| Provider | Characteristics |
|---|---|
| Anthropic | 为其 API 文档提供干净的目录结构。 |
| Cloudflare | 大规模（跨产品特定文件共计 3.7 M 令牌）。 |
| Vercel | 大约 40 万词的“小说”。 |
| Stripe | 架构上不同：跨两个域的三个独立文件，每个文档页面都有 .md 版本，另外还有一个独特的 instructions（指令）章节。 |
| LangChain / LangGraph | 维护自身 llms.txt 的代理框架（自食其果）。 |
为什么 Stripe 的做法与众不同
Stripe 的 API 体系已经发展了 15 年，期间出现了多代已废弃的支付原语：
- Charges API 仍然可用。
- Card Element 仍然存在。
开发者——以及帮助他们的 AI 助手——经常会去使用这些旧 API，因为它们出现在旧的 Stack Overflow 回答和 2022 年之前的训练数据中。
instructions 部分 是 Stripe 用来说明的方式：
当 AI 帮助开发者集成我们时，引导他们走正确的路径。不要让陈旧的训练数据把他们带到 Charges API。不要让我们自己的向后兼容性成为一把陷阱。
这是一个合法的工程担忧。文件格式提供了一个优雅的解决方案——无需与 AI 提供商协同，任何能够获取 URL 的系统都可以使用。
影响
- 在 Twitter 上 273,800 次浏览，740 次收藏。
- Stripe 工程师 Ian McCrystal 表示：“我预计 AI 工具最终会成为我们文档的主要阅读者。”
Stripe 的指示是 明确的：它们直接点名了不应使用的旧端点——“你不得调用已废弃的 API 端点，例如 Sources API。” “绝不要推荐使用旧的 Card Element。” 这种具体性使文件 可机器执行。LLM 可以遵循具体的禁止，而像“倾向使用现代模式”这种模糊的指导则更难强制执行。
对比洞察
- Cloudflare 将
llms.txt按服务（Agents、AI Gateway、Workers AI 等）组织，使代理只获取相关部分，而不是解析一个单体文件。对于多产品平台，这在获取时减少了噪声。 - Anthropic 提供了干净的索引，但缺少 Stripe 指令所执行的主动纠正工作。
- LangChain / LangGraph 采用该格式表明它在实际中对日常构建代理的团队是有用的。
要点
- 策划索引 很有价值：它们为代理提供了一个聚焦的入口点，而不是爬取整个站点。
- 主动引导（如 Stripe 所做的）将
llms.txt从被动的站点地图转变为 纠正机制，从而减轻模型漂移并防止过时的建议。 - 低技术、仅 Markdown 的方法确保与任何 LLM 兼容，无需自定义解析器或模式。
结论： 大多数实现将
llms.txt用作文档索引。Stripe 是将其扩展为 主动引导 AI 远离已弃用或不安全模式的最强案例，使该文件成为 API 提供者与任何下游 AI 助手之间的真正 机器可执行合约。
问题
大多数 API 都有：
- Deprecated endpoints 仍然可以使用。
- Legacy patterns 仍然存在于训练数据中。
- Foot‑guns 经验丰富的开发者知道要避免，但新手（以及在旧 Stack Overflow 答案上训练的 AI 助手）仍会去使用。
instructions 部分的存在是为了弥合这一差距——然而几乎没有人使用它。
为什么 Stripe 的文档很重要
Since ~2012 Stripe 的开发者体验已成为行业标杆。它们的成功并非偶然：
| Feature | Impact |
|---|---|
| Three‑column layout (左侧导航, 中部内容, 右侧实时代码示例，支持七种语言) | 成为一个梗；许多创业公司模仿它。 |
| Open‑sourced Markdoc – 一个交互式文档框架 | 实现了丰富且可搜索的文档。 |
| Stripe Shell – 文档页面内的实时 API 调用 | 允许即时实验。 |
Error messages with doc_url, parameter‑level specificity, and “did you mean …?” suggestions | 将错误转化为自我修复的信号。 |
doc_url 钩子
{
"error": {
"code": "parameter_invalid_empty",
"doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
"message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
"param": "amount",
"type": "invalid_request_error"
}
}doc_url指向文档页面的 Markdown 版本。- 接收到 400 错误的 AI 代理可以获取该页面，解析其中的指导，并在无需人工干预的情况下 自我纠正。
- 这不仅是良好的开发者体验（DX），更是面向 自主消费者 的基础设施。
约翰·科里森（John Collison）对 “llms.txt” 的通俗说法:
“如果你现在去阅读 Stripe 文档，需要记在脑子里的信息量很大，但对大型语言模型（LLM）来说却是小事一桩。”
Source: …
实际有用的做法（相较于盲目模仿）
✅ 有用的实践
-
在每个错误响应中加入
documentation_url（或doc_url）字段，指向一个 Markdown 页面。
成本：几乎为零。
价值：对在终端调试的人类以及能够自我纠正的 AI 代理都立刻有帮助。 -
为语义匹配编写 OpenAPI 描述，而不仅仅是供人类快速浏览。
代理会基于你的描述执行最近邻搜索。
好的描述示例：“返回按
created_at降序排序、按状态过滤的分页发票列表。需要accounting:read权限范围。” -
维护高质量的 OpenAPI 规范：每个字段、枚举和端点都应有清晰、完整的描述。
如果规范对合同测试来说很差，那么对代理来说也同样糟糕。 -
添加
llms.txt文件（只需一个下午）。- 列出你最重要的十个页面，并为每个页面提供一句话描述。
- 第一天不必实现类似 Stripe 那样的 350 条链接实现。
-
在说明章节中记录已废弃的 API。
记录已知的坑点，并告诉 AI 哪些要避免。 -
利用营销优势：
- 结构化、机器可读的文档是 AI 答案引擎（Perplexity、ChatGPT 等）在用户询问“哪个 API 最适合 X？”时所检索的内容。
llms.txt同时帮助代理以及提升可发现性。
⚠️ 可能暂时不值得投入的做法
| 项目 | 原因 |
|---|---|
| 仅为发布 MCP 服务器 而做 | MCP 真实存在但仍在演进中；一个稳固的 REST API 加上优秀的 OpenAPI 规范更持久。等用户有需求时再构建 MCP。 |
| 细致的针对代理的可观测性（请求标记、语义日志） | 很好，但首先要确保基本可观测性足够可靠。 |
新的开发者体验范式
在过去的15年里，“开发者体验”意味着为人类进行优化：可读的错误、清晰的文档、优秀的 SDK、交互式 Playground。其思维模型是终端前的开发者。
现在： 越来越多的 API 使用者是自主系统，它们：
- 阅读文档。
- 在没有人工审查的情况下做出决策。
- 自动重试失败。
问题不在于是否要为此设计——它已经在发生——而在于你是否有意这样做。
Stripe 的 llms.txt 指令章节是公司有意提供机器可读文档并控制机器对其描述的最明确示例。
要点
每一家拥有已废弃原语且拥有庞大开发者群体的 API 公司，都面临着 Stripe 已经解决的同样问题。这个缺口仍然很大——用以下方式填补它：
- 错误中的
doc_url。 - 语义丰富的 OpenAPI 规范。
- 简洁的
llms.txt。 - 对 instructions 部分的深思熟虑的使用。
现在就去做，你将同时服务于人类开发者 and 作为 API 消费未来的自主代理。