《读懂 Token》README 越详细，AI 越看不懂：1000 Token 才是甜蜜点

README 越详细AI 越看不懂1000 Token 才是甜蜜点系列第 4 篇 · 实操层你花了一下午写给人类看的那份详细 READMEAI 每次进你项目都得从头读一遍。这句话听起来有点反直觉——README 不是越详细越好吗对人类读者来说是的。但 AI 编程助手Cursor、Copilot、Claude Code、Cline 等打开你仓库时的阅读方式和人类完全不一样它每一次请求都会把 README 当成上下文的一部分塞进去没有“已经读过了跳过”这回事。更要命的是实测发现一份 README 的信息命中率并不随长度上升它在约 1,100 token 处触顶90%再往上加内容反而因为噪声太多而回落。换句话说——你越用心写AI 越抓不到重点。这一篇要讲的就是怎么把 README 从“AI 每轮都要重读的长故事”改成“人和 AI 都爱读的操作手册”。一、为什么 README 在偷偷烧你的 Token第 3 篇讲过.github/copilot-instructions.md是每次请求都要读的固定税。那 README 呢它是更重的那一档税。主流 AI 编程工具加载项目上下文时README 几乎是“最优先、最完整”加载的文件之一Cursor与Claude Code默认把项目根目录的README.md加进基础上下文Copilot Chat的workspace会优先扫描 README 定位项目结构Cline / Roo Code在首次打开仓库时会把 README 作为“项目地图”。结果是你在一个对话里问了 20 个问题README 就被读了 20 遍。更糟的是因为 README 通常出现在 system prompt 之后、用户对话之前它落在提示缓存的前缀段——这本来是最便宜的位置。但只要你频繁切模型、切分支或让 README 包含易变内容比如动态徽章、“最新发布”日期缓存就会频繁失效每一轮都按全价计费。反例一个典型的“为人类写的详尽 README”含徽章行、项目故事、功能大列表、完整目录树、嵌入正文的贡献指南、完整 MIT 许可证全文长度约 5000 token。按 Claude Sonnet 4 缓存读取价 $0.3/MTok单次约 $0.0015 看起来便宜但在 20 人团队、每人每天 50 轮对话的节奏下光 README 一个文件一个月就要烧掉 $40——而这只是被反复重读的几十份文件之一。二、README 各章节到底在烧多少 Token我们把一份真实存在的“百科全书式 README”按章节拆了一遍用分词器统计每个章节的 token 数和一份“AI 友好”的 README 放在一起对比差距一目了然。最烧 Token 的三个章节恰恰也是对 AI 最没用的项目背景与历史故事1200 TokenAI 不需要知道你在 2021 年哪家咖啡店起的名字完整目录树800 Token列出了.github/workflows/、.vscode/、tests/fixtures/等 AI 根本不会主动改的目录嵌入正文的贡献指南600 Token 完整 LICENSE 全文400 Token这些内容只在特定场景才用得到不该常驻。而真正被 AI 频繁用到的部分——快速开始、核心 API、配置变量、Gotchas坑点——在臃肿版里反而只占了不到 30%。三、一个反直觉的结论最详尽 ≠ 最好用很多开发者以为 README 写得越详细AI 对项目理解就越深。实际正相反——信息密度太低AI 抓不到重点。下面这张图展示了五种不同长度 README 在实际使用中的表现。蓝色折线命中率不是越长越高而是在约 1100 token 左右达到峰值90%然后因为无关信息太多而下降一句话都没有仅代码AI 只能猜命中率 15%极简说明小于 500 tokenAI 知道项目是干嘛的但不知道怎么用命中率 48%AI 友好结构化约 1100 token命中率 90%——甜蜜点标准详尽 README约 3000 token信息变多但重点稀释命中率回落到 72%百科全书式大于 8000 tokenAI 在大量背景故事、徽章、完整目录树里翻找关键信息命中率 45%——和极简版差不多但 Token 花了 18 倍。关键洞察AI 阅读 README 的目标不是“理解项目文化”而是回答三个问题——① 这是什么、能干嘛② 跑起来要什么③ 改代码 / 调用 API 要注意什么其他内容都是噪声。四、成本曲线README 越长每次对话都要重付README 的成本不是一次性的它叠加在每一轮对话上。下图展示了 README 长度与单次输入成本、AI 首响延迟的关系在 70% 缓存命中的正常情况下500 tok README单次约 0.07 美分首响额外小于 1 秒1000 tok README推荐区间约 0.14 美分延迟可忽略5000 tok README约 0.7 美分 / 次首响额外延迟约 3.6 秒20000 tok README约 2.7 美分 / 次首响额外延迟约 12.6 秒——AI 回答之前先等 12 秒。把这个数字乘上团队规模和对话量10 人团队、每人每天 50 轮、月工作日 22 天5000 tok README 比 1000 tok 多消耗约140 万 token / 月——按缓存读价算约 $0.4但一旦缓存失效切模型、切分支、改了 README就是$5 / 月。钱不是大数但积少成多更重要的是每轮 3~12 秒的延迟对开发体验的影响远比你想象的大。五、写一份“AI 友好”README 的七个原则在反复测试后我们提炼出七条原则。它们的核心思路是README 只放“每次都用得到”的信息低频内容搬到 /docs 按需被读。原则 1一句话讲清楚是什么不要在开头铺排“项目愿景”“时代背景”“命名故事”。第一行就用一句话说清项目是什么 核心能力例如SuperQueryDBContext-aware hybrid vector relational query layer. Drop-in on Postgres/MySQL/SQLite.一句话20 个 token。比带 emoji 的口号加 3 段品牌故事有效得多。原则 2徽章保留必要的删掉装饰性的徽章shields.io不是白送的一个徽章是一行 Markdown 加图片链接加 alt 文本大约15~25 token。保留 CI 状态、npm 版本、许可证这 3 个就够了Twitter 关注、下载量、“PRs Welcome”、TypeScript 标签这类装饰性徽章直接删。建议徽章行控制在 3 个以内。原则 3快速开始只给“最短路径”“快速开始”应该真的快安装命令 最小依赖要求 一个能跑起来的最小示例三部分加起来不超过 200 token。那些“推荐使用 Node 20.x LTS”“推荐什么终端”这类话删掉AI 不需要你推荐终端。环境要求只要版本号Requires: Node 18, Postgres 14 | MySQL 8 | SQLite 3.35原则 4核心 API 用表格不要散文式描述很多 README 喜欢用一大段话介绍每个方法“createClient 方法用于初始化客户端它接受一个配置对象……”这对 AI 来说是浪费。用一张表格列清楚方法名、用途、关键参数token 数少一半以上而且结构化程度更高AI 提取更准确。原则 5目录树给“精简版”不要给完整树完整目录树是最浪费 token 的内容之一。AI 不需要知道.vscode/launch.json存在。只列 src 下的核心目录 每个目录的一句话职责大约 100~150 token 就够src/ query/ # planner, executor, hybrid/vector search index/ # hnsw / ivfflat / btree cache/ # memory redis cache migrations/ # auto-detect and zero-downtime需要完整目录树的时候AI 自己会去列文件树。原则 6把最容易踩的坑单独列一个 Gotchas 段这是对 AI 帮助最大、也最容易被忽略的部分。把“默认端口是多少”“什么环境变量必须设”“什么场景下缓存要关”“常见报错怎么解”集中写成一段 Gotchas / FAQ提示这是第 7 篇计算器里最被低估的一格记忆——它直接减少 AI 自己试错、反复查文档的轮次。原则 7历史故事 / 架构哲学 / 完整贡献指南 / 许可证全文——全部搬到 /docs低频内容不要放 README。用相对路径链接指向它们AI 需要时会自己去读- Design philosophy and background: docs/architecture.md - Contributing: CONTRIBUTING.md - Full license: LICENSE许可证正文不要复制进 README——放一句“MIT — see LICENSE”就够LICENSE 文件本身在仓库里AI 真要读条款自己去读。六、AI 友好 README 的段落 Token 预算把上面七条原则落到具体数字上一份“AI 友好” README 的 token 预算大概是这样合计约1000 token刚好落在推荐区间。和 5000 token 的臃肿版对比信息命中率从约 45% 提升到 90%AI 更容易抓到关键信息单次成本约 0.7 美分降到约 0.14 美分首响延迟约 3.6 秒降到约 1.2 秒维护成本你改 README 的频率也低了。七、一份可以直接抄的模板下面是一份 60 行级别的 AI 友好 README 骨架按这个结构写绝大多数项目都够用了# 项目名 一句话是什么 核心能力 ## Quick Start 安装命令 Requires: 运行时版本、数据库版本等硬要求 最小可运行示例约 10 行 ## Core API | Method | Purpose | |--------|---------| | 方法签名 | 一句话用途 关键参数 | ## Project Structure 精简目录只列核心 src 子目录每个一行注释 ## Gotchas - 默认值坑 - 环境变量坑 - 容易误配的参数 - 性能/内存注意事项 ## Environment Variables | Var | Required | Default | Purpose | |-----|----------|---------|---------| ## Further Reading - 完整 API 参考: docs/api-reference.md - 迁移指南: docs/migration.md - 架构设计: docs/architecture.md - 贡献指南: CONTRIBUTING.md ## License 协议名 — see LICENSE为了让你直观对比这一篇我准备了两份真实可读的示例文件臃肿版约 320 行、5000 tok反面教材精简版约 60 行、1100 tok符合上面七条原则你可以把这两份文件贴进 tiktoken 或任何 token 计数器里自己对比一下。八、四个常见误区误区 1README 写短了人类读者看不懂AI 友好不等于人类不友好。一句话介绍、快速开始、核心 API、Gotchas这四样东西对人类读者同样是最高价值信息。你砍掉的只是品牌故事、徽章墙、完整目录树、许可证全文这些“装饰项”。误区 2放到 /docs 的文件 AI 就不读了不是。AI 编程工具在需要细节时会主动去读 /docs 下的文件Claude Code 的/context、Cursor 的 file、Cline 的 read_file 都是干这个的。区别在于README 是每轮必读/docs 是按需读——把低频内容搬到 /docs就是把“每轮都付费”变成“需要时才付费”。误区 3用 AI 生成 README 就完事了AI 写的 README 普遍偏长它喜欢铺陈你生成之后还得自己用这七条原则过一遍。推荐流程让 AI 写 → 自己砍到 1000 token 以内 → 用 token 计数器复核。误区 4我的项目小README 无所谓项目越小越要精简。小项目往往 README 已经足够短但很容易因为“反正短”就随手加徽章、加故事、加贡献指南。1000 tok 的原则对小项目、大项目都成立。到这里我们拆掉了两个最常见的“隐形固定税”上一篇的指令文件、本篇的 README。接下来我们会从“文件瘦身”转向“客户端实战”——先把写代码最常用的 IDE 彻底讲透。你以为自己天天在用 Cursor但可能从来没算过Codebase比选中片段贵 75 倍、Ask 模式比 Agent 模式便宜 44 倍、自动索引回灌在你不知道的时候每次多塞几百 Token。下一篇我们把 Cursor 的 8 个开关一次讲完。下一篇预告《在 Cursor 里省 Token8 个开关》——.cursorignore怎么写、Rules 文件怎么砍、什么时候必须开新会话、引用的粒度怎么选60 秒就能落地的清单改完账单立刻掉 60%~80%。附本篇示例文件bloated_readme.md— 反面教材约 320 行、5000 tokslim_readme.md— AI 友好版约 60 行、1100 tok