Vibe-coder们，请把Claude写的README去去水

一位开发者在Reddit上吐槽：用Claude vibe-coding生成的GitHub项目README，正在让寻找工具的普通用户苦不堪言。他为了给Steam Frame VR头显找脚本，翻遍了相关仓库，结果发现99%的项目README都是Claude的手笔——内容冗长、信息密度极低，读起来像AI在给自己做笔记，而不是写给人类看的说明书。

当README变成AI的草稿纸

这位用户强调，他并不反对vibe-coding本身。有人愿意分享用Claude写出来的修复脚本和工具，对社区是好事。问题出在README的写法上：Claude近期的输出风格变得异常稠密，用大量文字去解释对最终用户毫无意义的东西。

他举了一个实际例子。一个眼动追踪脚本的功能列表，人类写法是："自动找到你的PC；使用One Euro滤波器平滑注视；用死区抑制瞳孔抖动"——15个词。Claude的写法则是：先解释它如何通过Steam Link串流找到PC、无线适配器如何直连、家庭网络为什么无关紧要，再说明One Euro滤波器如何平滑注视和眼睑、小死区如何在注视时保持眼睛不动、闭眼时注视如何保持因为Frame的眼动在睁眼时会跳变——71个词。同样的信息量，长度翻了五倍，可读性反而下降。

vibe-coding 指开发者用自然语言描述意图，由大语言模型（如 Claude）直接生成可用代码或项目文件的开发方式，强调“凭感觉描述、快速产出”，而非逐行手写。它降低了创作门槛，但也让代码之外的产物（README、注释、提交信息）同样由模型代笔。README 是仓库根目录的说明文件，通常是访客接触项目的第一份文档，承担“这是什么、怎么用、怎么装”的职责，其读者是陌生人而非作者本人。当 vibe-coding 把生成重点放在“让模型把事做完”，README 就容易退化为模型输出过程的副产品，而不是面向读者的入门指南——这正是原文所述可读性下降的结构性原因。

信息过载：用户不需要知道后端细节

问题不止于啰嗦。Claude还会事无巨细地解释每一个功能，包括那些显而易见的、符合预期的行为，以及纯属后端实现、用户根本不需要了解的细节。

这让在GitHub上浏览仓库变得非常困难。用户被大量只对开发者（或其他AI代理）有用的信息轰炸，而这些信息本来应该去看代码本身。讽刺的是，这些README里明明包含了给人类手动在头显上运行命令的说明，却写得像是给另一个AI读的。

信息密度指单位篇幅内对目标读者有用的信息量。技术文档写作通常遵循“面向读者分层”的原则：面向使用者的部分只保留操作步骤、前置条件和预期结果；实现原理、内部数据结构、异常分支等属于后端实现细节，应放在代码注释或开发者文档中。AI 生成文本的常见偏差是把“解释得完整”等同于“写得好”，于是把推理链条中的中间结论也写入正文，造成读者需要自行筛除噪声。判断一段说明是否该留在 README，可以用一个简单标准：读者若不需要据此做出操作决策，就不必出现在这里。

社区的分歧：是给人看还是给AI看？

帖子下有评论认为"AI生成的README本来就是给其他AI读的"。但发帖人反驳说，在这个场景下不成立：Claude并不运行在Steam Frame上，用户没法把README丢给Claude让它帮忙操作。这些README明确写着给人类用户的指令，却用了AI之间交流的语体。

这恰好点出了问题的本质：很多vibe-coder在生成README时没有切换视角——他们让Claude把"思考过程"直接倒进了文档，而没有要求它面向最终读者重写一遍。

面向 AI 的文档与面向人类的文档在语体上确有差异：前者倾向完整陈述上下文、显式列出约束与边界条件，以减少歧义；后者依赖共享常识、省略显而易见的前提，追求扫读效率。随着 AI 编码代理普及，出现了为代理优化的说明文件（如 AGENTS.md 一类约定），它们与 README 的定位并不相同。原文争议的要点在于文档的实际读者是谁：如果说明中写的是让人类在头显上手动执行的命令，那么目标读者就是人，套用“给 AI 读”的语体便属于读者错配，而非风格偏好问题。

五分钟的编辑，换来十倍的可用性

发帖人的请求很简单：如果你在GitHub上分享脚本，请花五分钟把README改得更易读。具体做法可以包括：删掉对显而易见功能的解释、砍掉后端实现细节、把功能列表压缩成人类能扫读的短句、保留真正需要手动执行的步骤。

对vibe-coder来说，这其实是一个流程问题：让Claude生成README没问题，但生成之后应该再让它"面向人类用户重写一版，去掉实现细节，每个功能一句话"。或者干脆自己动手删一遍。README是项目的第一印象，一篇让人读不下去的文档，会让再好的工具也被埋没。

背景补充

One Euro 滤波器是一种面向实时交互的低延迟平滑算法，常用于眼动追踪、鼠标指针等信号处理场景。它的核心思路是让截止频率随信号变化速度自适应：信号缓慢时加强平滑以抑制抖动，快速移动时降低平滑以减小滞后。与之配套的死区是一种阈值机制，当输入变化小于设定范围时不更新输出，从而过滤微小噪声。原文提到“死区抑制瞳孔抖动”，指的正是用这一阈值挡住注视时眼球固有的细微颤动，而闭眼时眼动信号会跳变，因此需要额外保持上一有效值。这些属于实现层面的取舍，用户只需知道“更稳、更不抖”即可。