让 README 同时方便开发者上手和智能体验证
作者检查了 69 个仓库的 README,其中 63 个设有面向智能体的专节,前置的人类导读中位数为 17 行。导读交代项目用途和启动方式,专节提供安装、配置、运行和验证所需的技术细节。
AI 深度解读
Anton 原本想让 Claude Code 和 Codex 搭档,把自己 GitHub 上的 README 全部过一遍。要求很具体:开头用 10–30 行回答人最关心的问题,后面给编码 Agent 足够的技术细节,让它能自行安装、配置、运行和验证。
作者先用 GitHub API 盘了 69 个非 Fork 仓库,发现 63 个已经采用这套结构,给人看的部分中位数是 17 行。真正要改的集中在两个仓库和五个缺安装说明的项目。更难回答的问题还留着:换台机器,照着 README 真能跑起来吗?
一份 README 怎么同时服务人和 Agent
给人看的前 10–30 行回答三个问题:项目是什么、为什么做、怎么开始。Agent 段接着交代执行细节。63 份 README 都有 Preconditions、Verify、Uninstall / rollback 和 Rules for the agent,分别覆盖运行前提、结果验证、卸载或回滚,以及 Agent 应遵守的规则。回滚甚至超出了 Anton 最初的要求。
这 63 份 README 的人工导读都在 17–21 行之间,差距很小。作者据此推断,它们很可能套用了模板。统一结构方便人和 Agent 在不同仓库里找到同一类信息,也方便批量盘点。至于前 17 行有没有讲清项目能解决什么,还得读正文。
69 个仓库,实际该改哪些?
作者在 11 月 18 日通过 GitHub API 读取到 256 个公开仓库,其中 69 个是非 Fork 仓库,并抓取了这 69 份 README。66 个仓库在过去 7 天内有推送,其余 3 个更久,最久也没超过 90 天。全部仓库都有描述。这个快照能回答仓库最近有没有推送,但推送日期本身无法说明产品当前是否可用。
6 份缺 Agent 段的 README 里,作者排除了 4 个用途不同的仓库:个人主页 tonydzi(168 行)、站点 tonydzi.github.io、组织模板 .github 和简历 cv。剩下两个才需要具体处理。vault-recall 是个产品,README 有 114 行,缺整段 Agent 文档。github-evidence 已有 31 天没推送,README 长达 1,220 行、175,165 字节,得先决定怎么让读者迅速找到入口。
另有 24 个仓库已经有 Agent 段,却缺 ### Install。clawrush、deep-research、dashboards 和 the-journey 这类合集没有安装步骤也合理。作者点出的 5 个例外是 harness-abc-bench、agent-leash、verbatim-citation-gate、persona-portability-benchmark 和 agent-runtime-integrity-bench,它们是工具或基准项目,安装这一步需要交代。
星标靠前的仓库大多通过了结构检查。clawrush 是 18 星、17 行导读,sqlite-graph-memory 是 17 星、21 行,second-brain-starter-kit 是 15 星、21 行,claude-bible 是 13 星、17 行,whatsapp-mcp-kit 是 13 星、19 行。前十里唯一缺 Agent 段的是个人主页 tonydzi。星标和推送时间都会变,这些数字只对应盘点当天。
我的判断
先按仓库用途筛一遍,再决定哪些值得精读,比挨个重写更贴合这次任务。靠标题做批量检查,适合找漏项,但 ### Verify 下面即使放了一条验不出结果的命令,统计照样会记为通过。作者实测了章节是否存在、位置在哪里。至于 10–30 行是否更好读、Agent 能否独立跑通,原文没有对照数据,这部分仍是经验之谈。
逐份做干净环境验证费时,却能回答标题扫描答不了的问题。作者提到,second-brain-starter-kit 的 issue #2 从 9 月 22 日起就提出一个很实在的验收方式:找一台团队之外的机器,克隆仓库,再按文档从头走一遍。对前端或 Node 项目,这也能暴露维护者平时感觉不到的隐含前提,比如本机早就配好了环境变量。
能拿来做什么
- 盘点一组仓库时,先拉取 README 和最近推送时间,按可安装项目、站点、内容合集等用途筛选,再检查缺失的章节。
- 给前端或 Node 工具补
### Install时,把安装前提和执行顺序写进去,并在### Verify里写清跑成功后应该看到什么。 - 想知道 README 能否交给 Claude Code 或 Codex 独立执行,就挑一个项目在干净环境里只按文档操作,记下第一次需要人工补充的信息。