概念来源
"AI Friendly" 并非某一篇论文或某个人的单一发明，而是从几条线索交汇演化而来的：
1. "Machine Readable" 的延伸 早期互联网时代有 "human readable"（语义化 HTML、SEO 友好）和 "machine readable"（结构化数据、schema.org、RSS）的概念。AI Friendly 本质上是这一思路在 LLM 时代的升级版——不只是让爬虫能解析，而是让语言模型能理解和推理。
2. LLM 工具调用（Tool Use / Function Calling）的普及 2023 年 OpenAI 推出 Function Calling，Anthropic 推出 Tool Use，AI 从"问答机器"变成了"能执行操作的 Agent"。这直接催生了一个问题：怎样的 API、文档、系统设计才能让 AI Agent 正确使用？"AI Friendly" 作为工程实践开始被讨论。
3. Andrej Karpathy 的 "LLM OS" 视角 Karpathy 2023-2024 年多次提出 LLM 正在成为操作系统内核的类比——文件系统、API、工具都将被 LLM 调度。这把"如何让系统被 AI 友好使用"提升到了架构层面。
4. MCP（Model Context Protocol）的出现 Anthropic 2024 年底发布 MCP，明确定义了 AI 与外部系统交互的标准协议，这可以看作 "AI Friendly" 在工程规范层面的具体落地。
AI 时代开发者应该如何做到真正 AI Friendly
一、让你的代码对 AI 可读（Code-level）
代码本身就是 LLM 的上下文，可读性直接影响 AI 能否正确辅助你：
- 命名要语义化，不要
d、tmp、fn2，要userSessionDuration、parseInvoiceDate。AI 推理依赖语义，缩写是噪音。 - 函数要小、职责单一。AI 的 context window 有限，一个 500 行的函数让 AI 很难定位问题；20 行的纯函数则几乎总能被正确理解和修改。
- 类型信息要完整。TypeScript / Python 类型注解不只是给编译器看的，LLM 通过类型推断能准确理解数据结构，减少幻觉。
- 注释写"为什么"，不写"是什么" 。"为什么这里要加锁" 比 "这里加了锁" 对 AI 更有价值。
二、让你的 API 对 AI 可用（API-level）
如果你在构建供 AI Agent 调用的服务：
- RESTful 语义要严格：动词、状态码、资源命名必须规范。AI 从命名推断行为，
POST /user/delete这种设计会让 AI 产生错误预期。 - 错误信息要机器可读：返回结构化的错误（
{ "code": "INSUFFICIENT_BALANCE", "message": "..." }），而不是 HTTP 500 + 一段 HTML 页面。AI Agent 需要根据错误决策下一步动作。 - 提供 OpenAPI / JSON Schema：这是 LLM 理解你 API 能力边界的最高效方式，也是 MCP Server 的基础。
- 幂等性：AI Agent 可能因为不确定上次调用是否成功而重试。没有幂等保证的接口在 Agent 场景下很危险。
三、让你的文档对 AI 可索引（Docs-level）
这是目前最被低估的方向：
- 提供
llms.txt：类比robots.txt，这是 2024 年兴起的约定——在网站根目录放一个llms.txt，用简洁的 Markdown 描述你的产品是什么、核心文档在哪里，让 AI 爬取和理解你的内容。Anthropic、Vercel 等已经实践。 - 文档结构要平坦：深层嵌套的文档树对向量检索不友好。把重要概念放在顶层，可以独立理解的页面比需要上下文的页面更容易被 RAG 正确召回。
- 代码示例要完整可运行：AI 在理解和生成代码时，完整的 runnable example 比片段更有用，因为它包含了隐含的依赖和上下文。
四、设计 AI-native 的交互模式（System-level）
真正前沿的思考：
- 暴露意图，而非仅暴露操作。传统 API 暴露 CRUD，AI-friendly 的设计还应该暴露"业务意图接口"，比如
POST /order/fulfillment-check而不是让 AI 自己编排 5 个 API 调用来判断订单能否履约。 - 提供沙箱/干运行模式。AI Agent 在执行前需要验证方案，提供
dry_run=true参数可以大幅降低 Agent 犯错的成本。 - 状态要可查询。Agent 是异步、多步骤的。如果你的系统没有清晰的状态查询接口，Agent 就无法做错误恢复。
- 操作要可审计和撤销。AI 会出错，软删除、操作日志、undo 机制是 AI 时代的基础设施，不再是可选项。
五、开发者自身的工作流（Workflow-level）
- 用 CLAUDE.md / .cursorrules 等 context 文件描述你项目的约定、架构决策、不应该碰的地方。这是你和 AI 协作的"说明书"。
- 把 AI 当 junior dev，不当搜索引擎：给任务、给约束、验结果，而不是问问题、粘贴答案。
- 测试是 AI Friendly 的基础：有完整测试套件的代码库，AI 修改后可以立刻验证。没有测试的代码库，AI 改一处破一处，你无法信任它。
总结一句话：AI Friendly 的本质是减少模糊性——语义清晰的命名、结构化的接口、完整的类型和文档，让 AI 能在更少幻觉的情况下正确理解和操作你的系统。这和"对人友好的好工程"高度重合，只是对标准的要求更严格了。
