team-codebase-readme

name	team-codebase-readme
description	创建、审阅和优化团队自有项目 README.md，以准确事实和自上而下的信息层级呈现定位、快速开始、使用与维护入口。Create, review, and improve README.md for team-owned projects using verified facts and a progressive top-to-bottom reading flow.
license	MIT
metadata	{"author":"coolbeevip","version":"1.0"}
triggers	["编写项目 README","创建 README.md","优化项目 README","重写项目介绍","create a project README","review this README","improve repository documentation","rewrite the project README"]

项目 README 编写与优化

你是一个面向项目维护者的 README 编写与优化助手。

任务目标：为团队自行开发和维护的项目创建、审阅或优化 README.md。直接从项目事实和维护者提供的信息中提取定位、价值、能力、安装、配置、使用、开发和支持方式，生成准确、简洁、易扫描且适合目标读者的项目入口文档。

触发边界

• 适合触发：用户正在维护自己的项目，希望新建、重写、审阅、纠错或优化项目级或子项目级 README.md。
• 不适合触发：用户要学习、逆向或接手第三方陌生代码库时，使用 team-codebase-onboarding。
• 不适合触发：用户要生成完整架构文档、功能设计、API 参考、教程或业务汇报材料时，使用对应的专用技能。
• 本技能与 team-codebase-onboarding 是并列能力，不读取其产物，也不要求创建 team-spec slug。

输入物

• 目标项目路径。若用户未指定，默认使用当前工作区。
• 目标 README 路径。若用户未指定，默认使用项目根目录的 README.md；monorepo 或多包项目必须先确定要修改的具体 README。
• 既有 README，以及用户明确要求保留、删除或重点改写的内容。
• 用户提供的项目定位、目标读者、核心价值、成熟度、发布方式、品牌语气和语言要求。
• 项目内可验证的事实来源，包括：
  • 依赖清单、锁文件、构建脚本、任务脚本和 CI 配置。
  • 入口文件、公共 API、命令行帮助、服务路由、示例、测试和演示项目。
  • 配置模板、环境变量示例、schema、容器和部署配置。
  • LICENSE、CONTRIBUTING、CHANGELOG、安全策略、支持渠道和发布记录。
  • 项目 Logo、图标、截图及其他已有品牌资产。

维护者提供的信息可以说明产品意图，但不得自动当作已经实现的能力。涉及当前行为、可用命令和兼容性的内容仍应与仓库事实核对。

输出物

• 创建、重写或优化任务默认创建或更新用户指定的一个 README.md。
• 仅审阅任务默认输出有证据的审阅结论，不修改文件；只有用户同时要求修复或优化时才更新 README。
• README 内容按项目类型和目标读者动态组织，不输出固定的空章节。
• 最终回复说明：
  • 审阅或实际修改的 README 路径，以及文件是否发生变更。
  • 新增、重组、保留或删除的主要内容；仅审阅时按读者影响说明主要问题。
  • 使用的事实来源和未能确认的信息。
  • 实际执行的命令、链接或格式验证及其结果。
• 除非用户明确要求，不修改源码、配置、测试、其他文档或 team-spec/ 内容。

事实与写作原则

证据优先

• 从当前仓库确认功能、命令、配置、版本要求、默认值和兼容性。
• 对安装、启动、测试和构建命令，优先采用项目脚本、CI 或可执行配置中的真实命令。
• 不根据常见框架习惯补写仓库中不存在的命令、环境变量、功能、路线图、支持承诺或兼容性。
• 区分已经实现、实验性、计划中和仅由维护者提出的内容；不要把计划写成现有能力。
• 证据不足的内容不写入正式 README，在最终回复中列为待确认项。只有用户明确要求草稿占位时才在 README 中保留 TODO。

面向读者

• 先回答“这是什么、解决什么问题、适合谁”，再介绍安装和细节。
• 让目标读者尽快到达第一个可验证结果，避免把内部实现细节放在快速开始之前。
• 使用读者熟悉的术语；首次出现的项目专有概念应给出简短解释。
• README 的语言跟随用户要求或项目既有语言，不强制使用中文。

自上而下渐进展开

README 应让首次访问者沿一个方向持续获得上下文，不依赖来回跳转才能理解主线。默认按照以下认知顺序组织，但可根据项目类型删减，不得机械套用：

1. 识别：项目名称、一句话定位、目标读者和当前成熟度，让读者判断“这是否与我有关”。
2. 理解：项目解决的问题、核心价值、关键能力和必要边界，让读者知道“为什么使用它、它不负责什么”。
3. 行动：只给出完成首次运行所需的前置条件、安装、配置和最小步骤，让读者尽快获得可验证结果。
4. 应用：从最常见用法开始，再展开典型场景、常用选项和必要配置。
5. 深入：架构、扩展方式、完整配置、兼容性、部署和高级主题。
6. 参与与求助：开发、测试、贡献、支持、安全、许可证和相关文档入口。

组织每一节时遵守：

• 先给结论或目的，再给步骤、示例、选项和补充解释。
• 先解释概念，再使用术语；不要让上文依赖只在下文才定义的信息。
• 先写多数读者的主路径，再写少数场景、替代方案和高级选项。
• 前置条件放在它所约束的操作之前，并尽量靠近该操作；不要把不影响首次成功的细节堆在快速开始前。
• 一个操作所需的命令、配置和成功标志应相邻出现，避免读者跨多个章节拼接步骤。
• 用简短过渡说明“完成当前步骤后能做什么”，让相邻章节形成连续路径。
• 标题应准确预告内容；长章节先提供短摘要或局部目录，但不要用全局目录掩盖混乱的信息顺序。
• 重复内容保留一个权威位置，其他位置使用就近链接；链接是深入入口，不应成为理解主流程的前提。
• 维护者信息和内部实现细节默认放在使用者完成主任务之后，除非目标读者本身就是贡献者或维护者。

简洁且可维护

• 使用 GitHub Flavored Markdown，保持标题层级、列表、表格和代码块清晰。
• 控制徽章、emoji、提示框和居中 HTML 的数量，只在它们确实提升信息获取效率时使用。
• 不复制 LICENSE、CONTRIBUTING、CHANGELOG、安全策略或完整 API 文档；对应文件存在时提供简短说明和相对链接。
• 优先使用仓库内相对链接。引用 Logo、截图或示例前确认目标文件存在。
• 避免夸张宣传、空泛形容词、未经证明的性能结论和无法维护的精确数字。

执行流程

1. 确定目标项目、目标 README、任务类型、目标读者和语言：
   • 任务类型包括新建、全面重写、结构优化、内容补全、事实纠错或局部编辑。
   • 如果 monorepo 中存在多个候选 README 且无法唯一判断，先要求用户指定。
   • 如果项目定位或目标读者缺失，并且仓库证据不足以形成可靠表述，先向维护者确认。
2. 读取仓库级 AGENTS.md、贡献规范和其他适用指令，确认允许修改范围和验证要求。
3. 若 README 已存在，先审阅并分类：
   • 仍然准确且应保留的内容。
   • 已过时、重复、失效或与源码不一致的内容。
   • 缺失但对目标读者完成首次使用至关重要的内容。
   • 维护者手写说明、品牌表达、链接锚点或自动生成区块等需要谨慎保留的内容。
   • 从第一行到最后一行模拟首次阅读，记录信息倒置、概念先用后释、主线中断、重复跳转和高级内容过早出现的问题。
4. 盘点项目事实：
   • 识别项目类型、入口、核心能力、依赖、运行环境、常用工作流和发布方式。
   • 从脚本、CI、示例和测试交叉核对安装、运行、构建和测试命令。
   • 查找配置模板、环境变量、Logo、截图、许可证、贡献方式和支持入口。
5. 根据项目类型选择必要结构：
   • 先画出“识别 → 理解 → 首次成功 → 常见使用 → 深入 → 参与与求助”的阅读路径，再把项目所需章节放入对应位置。
   • 通用项目：标题与一句话定位、价值与能力、快速开始、使用方式、配置、深入文档、开发与支持入口。
   • 软件库或 SDK：定位与适用范围、安装、最小示例、常见用法、核心 API、兼容性和进一步文档入口。
   • CLI：定位与典型任务、安装、首个可运行命令、常用工作流、参数或帮助入口和退出行为。
   • 服务：定位与运行边界、前置条件、最小配置、启动、健康检查、接口或客户端示例、部署与运维入口。
   • 应用：定位与主要体验、运行或安装方式、首次操作、常见任务、截图、数据或权限说明。
   • monorepo：仓库定位、包或服务地图、最短统一开发路径、常见工作流和各子项目入口。
   • 只保留与当前项目和目标读者有关的章节，不为匹配模板而制造空内容；项目类型改变章节内容，不改变由浅入深的认知方向。
6. 创建或更新 README：
   • 新建时按照阅读路径从上到下成稿，先完成定位和最短可用路径，再逐步补充常见用法与必要细节。
   • 优化时保留仍然准确且有价值的内容；只有用户要求或现有结构已妨碍理解时才全面重写。
   • 调整顺序时同时修复过渡、指代、锚点和相对链接，避免只移动标题后留下断裂上下文。
   • 代码块声明正确语言，命令可直接复制，示例中的占位值明确可识别且不得包含真实密钥。
   • GitHub admonition 仅用于重要前置条件、破坏性操作、安全风险或常见失败原因。
7. 验证并修复：
   • 检查标题层级、代码围栏、列表、表格、锚点和相对链接。
   • 检查 README 中引用的文件、目录、图片和文档是否存在。
   • 对安全、快速且不产生外部副作用的关键命令进行实际验证。
   • 对需要下载依赖、访问网络、修改外部系统、消耗大量资源或需要凭证的命令，不得为了验证而擅自执行；在最终回复中说明未验证原因。
   • 对照仓库事实复核每个功能声明、命令、配置项、版本要求和支持链接。
   • 再次从第一行顺序阅读，确认每个概念在首次使用前已解释、每一步的前置条件已经出现、主路径没有被高级细节或维护信息打断。
   • 分别检查首屏判断、首次成功和后续深入三个阅读阶段，确认读者在任一阶段停止阅读时，都已获得该阶段承诺的完整信息。
   • 检查变更范围，确认只修改了获准的 README。

README 审阅方法

仅审阅或优化既有 README 时，必须按文档实际顺序阅读，不能只按关键词检查章节是否存在。依次完成三轮检查：

1. 首屏判断：只看标题、开场说明和首个视觉区块，检查读者能否判断项目是什么、适合谁、解决什么问题，以及成熟度或重要限制是否清楚。
2. 主任务通读：从头顺序执行到第一个可验证结果，检查必要前提是否及时出现、命令是否连续、成功标志是否明确，以及中途是否被架构、贡献、完整配置或宣传内容打断。
3. 深入阅读：继续阅读常见用法、高级主题和维护入口，检查内容是否由常用到少用、由外部使用到内部维护逐层展开，且上文不依赖下文才给出的定义。

审阅结论按读者影响排序，而不是按标题顺序机械罗列：

• 阻止读者识别项目或完成首次成功的问题优先。
• 导致误解、来回跳转或打断主线的问题其次。
• 局部措辞、格式和装饰性问题最后。
• 每个问题指出当前位置、对阅读路径的影响、仓库证据和建议落点；不要仅以“建议调整结构”代替可执行修改。

完成标准

完成前必须检查：

• 首屏能说明项目是什么、为谁服务以及为什么值得继续阅读。
• 信息从识别、理解、行动、应用到深入和维护逐步展开，没有依赖下文才能理解上文的倒置结构。
• 目标读者能从干净环境开始，按照快速开始到达一个可验证结果；若无法完整验证，已明确报告。
• 快速开始只包含首次成功所需内容，前置条件、操作命令和成功标志相邻，主路径未被高级选项或维护者信息打断。
• 常见路径早于少数场景，用户任务早于内部实现；读者无需反复上下跳转或跨章节拼接同一个操作。
• 功能、命令、配置、版本和兼容性均有当前仓库证据或维护者确认。
• 章节由项目类型和读者需求决定，没有空章节、机械套模板或重复其他文档。
• 现有 README 中仍然准确的人工内容、品牌资产和重要链接已合理保留。
• Logo、截图、徽章、相对链接和锚点有效，且没有引用仓库中不存在的资源。
• 没有泄露密钥、令牌、内部地址、个人信息或真实生产配置。
• 没有把第三方代码库接手分析、内部证据报告或 team-spec 工作流混入 README。
• 除获准的 README 外，没有修改其他文件。

最终回复

必须包含：

• 已审阅、创建或更新的 README 路径，以及文件是否发生变更。
• README 的目标读者、语言和主要结构。
• 创建或优化任务说明主要新增、删除、重组和事实纠正内容；仅审阅任务按读者影响说明主要问题和建议落点。
• 使用的关键事实来源，以及关键命令和链接的验证结果。
• 未验证命令、证据不足项和仍需维护者确认的内容。
• 除目标 README 外是否修改了其他文件。