一个让我改变想法的经历

去年我做了一个开源的 CLI 工具，README 写了将近 2000 字——安装方法、使用示例、参数说明、FAQ，全都有。我觉得文档写得挺好的，GitHub 上也有不少 star。

然后有一天，一个用户开了个 Issue 说："我让 Claude 帮我用你的库写代码，结果 AI 根本不知道这个库的 API 是什么，生成的代码全是错的。"

我的第一反应是：README 就在那里啊，AI 不会自己看吗？

答案是：不会，至少不会像你想的那样看。

当你跟 ChatGPT 或者 Claude 说"帮我用 xxx 库写个功能"的时候，AI 依赖的是它训练数据里的知识。如果你的库比较新、比较小众，或者最近做了 breaking change，AI 的知识就是过时的。它不会主动去爬你的 GitHub README——除非你手动把文档贴给它。

这就产生了一个新问题：怎么让 AI 工具自动获取你项目的最新文档？

答案就是这节课要讲的——给 AI 写专门的文档。

三种"给 AI 看"的文档

目前有三种主要的"AI 友好"文档标准，它们解决不同的问题：

1. AGENTS.md —— "AI Agent 的使用说明书"

AGENTS.md 是 Linux Foundation 维护的一个开放标准。它的定位是：告诉任何 AI Agent "怎么跟这个项目打交道"。

跟 CLAUDE.md 和 .cursorrules 不同，AGENTS.md 不是某个特定工具的配置文件——它是一个通用标准。未来不管出什么新的 AI 编程工具，只要它支持 AGENTS.md 标准，就能自动理解你的项目。

一个 AGENTS.md 长什么样？

# AGENTS.md

## Project Overview
A personal blog built with Next.js 14 and TypeScript.

## Development Setup

bash pnpm install pnpm dev # starts at localhost:3000

## Coding Standards
- TypeScript strict mode
- Functional components only
- File naming: kebab-case

## Testing
Run `pnpm test` before committing.
All new features need unit tests.

## Areas of Caution
- Do not modify files in src/lib/core/
- All API routes must have authentication

你可能会说：这跟 CLAUDE.md 不是差不多吗？

确实很像。区别在于：CLAUDE.md 是 Anthropic 定义的、Claude Code 专用的；AGENTS.md 是开放标准、任何工具都可以支持。我个人的做法是两个都写——内容有重叠没关系，因为不同的工具读不同的文件。

2. llms.txt —— "给 AI 搜索引擎的站点地图"

如果说 AGENTS.md 解决的是"AI 编程工具怎么理解你的代码仓库"，那 llms.txt 解决的是一个完全不同的问题：AI 搜索引擎怎么理解你的网站内容。

你知道 robots.txt 吧？它告诉 Google 爬虫"哪些页面可以爬、哪些不可以"。llms.txt 的定位类似，但面向的不是传统搜索引擎，而是大语言模型。

为什么需要它？因为 LLM 处理信息的方式跟 Google 完全不同：

你的网站可能有几百个页面，每个页面有导航栏、侧边栏、广告、页脚——这些 HTML 噪声对 Google 没问题，但对 LLM 来说是一种浪费。LLM 更希望看到的是：一个精简的、纯 Markdown 格式的内容目录，告诉它"这个网站有什么内容、每个内容的核心信息是什么"。

这就是 llms.txt 做的事情。

3. README 的 AI 化改造

你不一定要创建新文件——改造现有的 README 也能让 AI 更好地理解你的项目。核心原则就一句话：少写"为什么用这个项目"，多写"这个项目的 API 长什么样"。

传统 README 花大量篇幅在"项目介绍"、"功能特点"、"截图"上——这些是写给人看的，帮人决定"要不要用这个库"。但 AI 需要的不是被说服，它需要的是可操作的信息：

❌ 传统 README 的风格：
"这是一个高性能的状态管理库，支持 React 和 Vue，
拥有极小的 bundle size 和优秀的 TypeScript 支持..."

✅ AI 友好的风格：
"## Quick Start
import { createStore } from 'my-lib';
const store = createStore({ count: 0 });

## API
createStore(initialState) — 创建 store
store.get(key) — 获取值
store.set(key, value) — 设置值
store.subscribe(callback) — 订阅变化"

你看到区别了吗？AI 不需要你的营销文案，它需要的是可以直接复制粘贴进代码的示例和 API 签名。

这些文档之间的关系

话说回来，你不需要全部都写。如果你只是做自己的项目用 Claude Code，一个 CLAUDE.md 就够了。但如果你做的是开源库，或者你的网站希望被 AI 搜索引擎（比如 Perplexity、ChatGPT Search）更好地理解，那 llms.txt 和 AGENTS.md 就值得花时间写。