repository-readme-writer

仓库 README 编写指南

创建或改进仓库 README，帮助人类和 Agent 快速了解项目，同时避免过度依赖脆弱的实现细节。

决策树

这属于哪类 README 工作？

• 根据仓库创建新的 README 检查相关仓库证据；必要时参考 references/repository-audit.md，并根据需要调整 templates/repository-readme.md。

• 改进现有 README 阅读 references/rewrite-patterns.md，然后保留有用的章节，删除过时或过于具体的内容。

• 仅修复安装流程 阅读 references/quickstart-design.md，让快速入门成为从克隆到获得有用本地反馈的最短、经过验证的路径。

• 仅审查 README 质量，暂不编辑 根据仓库证据审查用户要求的范围。对于更广泛的审查，探测脚本和 templates/readme-review.md 是可选辅助工具，并非措辞或链接审查的前置要求。

• 不确定适用哪条路径 从 references/foundations.md 开始，然后先检查仓库再动笔。

快速参考

任务	操作	阅读
起草新的 README	写作前检查项目用途、包管理器、命令、配置、检查项和部署信号	references/repository-audit.md
改进现有 README	保留准确且重要的内容，删去脆弱的清单，补充或修复快速入门	references/rewrite-patterns.md
设计快速入门	用尽可能少的命令完成安装、配置、运行和验证	references/quickstart-design.md
避免文档过度详尽	除非实现细节会影响第一天的使用，否则不要写入	references/foundations.md
发现常见问题	检查版本固定、路径清单、过时命令和不利于 Agent 使用的措辞	references/gotchas.md
快速获取仓库信号	运行 python3 scripts/repo_readme_probe.py <repo>	references/repository-audit.md

操作约定

1. 先检查，再写作。对命令、包管理器、端口或部署方式靠猜测的 README，还不如没有。
2. 围绕读者的第一个有效操作来写。应用可能需要可运行的安装流程；库需要使用方法；数据集需要访问方式和架构说明；归档仓库则可能需要状态和迁移指南。
3. 说明各部分的职责和边界；有助于导航时，使用经过验证且稳定的源代码路径。避免罗列目录，保留有用的路径。
4. 必要时说明受支持的版本范围。精确版本优先以清单文件、锁定文件、版本管理器文件或 CI 为准；如果在正文中重复精确要求确实有帮助，就附上其权威来源链接。
5. 示例应少而可执行。README 应展示顺利完成任务的路径和主要验证命令，而非项目中的每个脚本。
6. 便于 AI Agent 使用。不要用脆弱的规则、详尽的清单或过时的假设过度约束未来的 Agent，以免它们原样照搬。

README 默认结构

对于可运行的应用，这只是起点，并非必须采用的九段结构。请遵循用户要求的形式，并只纳入对当前仓库有用的章节。

1. 标题
2. 一句话项目简介
3. 快速入门
4. 项目结构或架构边界
5. 配置
6. 本地开发
7. 质量检查
8. 可查明时添加部署或发布说明
9. 仅在存在常见初次使用问题时添加故障排查

对于小型仓库，合并相关章节。对于大型仓库，根目录 README 应保持概述性，并链接到专门的文档，而不是复制其内容。

章节规范

简介

用一到两句话说明项目是什么、用途是什么。不要以内部工具开篇，除非该工具本身就是产品。

快速入门

首次使用需要执行步骤时，请提供快速入门。快速入门应通过有证据支持的命令，引导读者完成可见的验证，并且只包含必要的配置。如果是库，请提供导入示例；如果是数据，请提供访问或架构说明，以更好地帮助读者。对于静态或已归档的仓库，不要臆造命令或构建系统。

项目结构

说明各部分的边界和职责。例如，“CMS 负责管理内容，网站通过服务端 API 路由读取内容”这样的句子，可以附上稳定的源代码链接，帮助读者找到相关组件。

配置

仅在本地使用或部署确有必要时，列出必需的环境变量或配置组。避免罗列所有变量。

质量

先给出唯一的通用质量检查门槛。只有在有助于常见工作流时，才补充针对性的命令。

部署

说明部署模式和必需服务。除非仓库明确依赖特定提供商，否则不要详述提供商相关的细节。

模板

• templates/repository-readme.md 可选的、面向应用的起始模板；可省略、调整顺序或替换不相关的章节。

• templates/readme-review.md 可选的评审大纲；评审结果应限定在请求范围内。

指引不足时

如果指引已过时、不完整或与仓库冲突，请先检查其清单文件、源代码、测试和维护中的文档。只有在问题仍未解决时，才查阅当前官方工具文档。使用经过验证且与用户权限相符的命令；区分已检查和已执行的检查，并说明存在的缺口。提出对规范技能的修正，并附上来源及示例或可复现的检查；不要悄悄更改已安装的副本，也不要为了常规措辞修改而浏览网页。

注意事项

1. 路径清单第一天看起来很有用，但第一次重构后就会过时。
2. 精确的版本说明比清单文件、锁文件、版本管理器文件和 CI 配置更容易过时。
3. 冗长的命令目录会掩盖新贡献者真正需要的那一条命令。
4. 只为人类编写的 README 可能会遗漏对机器有用的命令；只为 Agent 编写的 README 则可能过于字面化，缺乏灵活性。
5. 如果快速入门中的命令未经验证，请标明不确定性，或先进一步检查，再将其作为权威内容呈现。

阅读指南

需求	阅读
README 的核心理念和章节规则	references/foundations.md
仓库检查工作流和证据优先级	references/repository-audit.md
快速入门结构、命令选择和验证	references/quickstart-design.md
重写现有 README 的方法	references/rewrite-patterns.md
失败模式和恢复方法	references/gotchas.md