readme-authoring

name	readme-authoring
description	README 写作规范 — 为 README / 用户使用文档收口用户视角、章节顺序、示例策略与 consumer map

Readme Authoring Skill

职责

当任务目标是 README.md 或项目主用户使用文档时，本 Skill 负责把“写什么、先写给谁看、哪些内容必须后置”收口为一套稳定规则。

它不新增 workflow 子类型，仍由 dev-docs / dev-init 触发。站点文档、最终用户手册、接入手册和公开能力页的主入口由 user-manual-authoring 承担；本 Skill 是其中的 README 专项分支。

触发条件

场景	是否触发
新建或改写 README.md	🔴 必须
初始化项目时生成 README	🔴 必须
面向真实使用者且落点为 README / 项目主文档	🔴 必须
站点文档、最终用户手册、接入手册、公开能力页	先触发 user-manual-authoring，落点为 README 时再叠加本 Skill
CONTRIBUTING / 架构文档 / 纯开发指南	N/A

默认受众模型

README 的默认第一受众必须是用户 / 使用者，而不是维护者。

这里的“用户 / 使用者”指真实依赖这份文档完成理解、安装、启动、接入、使用或排错的人；可以是外部用户，也可以是内部同事。

字段	默认值	说明
primaryAudience	用户 / 使用者	README 主叙事默认面向真实读者
secondaryAudience	开发者 / 贡献者 / 维护者	仅作为后置补充受众
developerInfoPlacement	后置	开发、贡献、维护内容不得抢占主叙事

README 写作契约

字段	必填	说明
primaryAudience	✅	默认 用户 / 使用者
secondaryAudience	条件	可选 开发者 / 贡献者 / 维护者
projectType	✅	library / service / application / tool
userJourney	✅	理解 -> 安装/接入 -> 启动/运行 -> 使用 -> 配置 -> 排错
targetSurface	✅	public-docs-site / project-readme-docs / requirement-deliverable / maintainer-only，不得未确认就把需求交付文档挂入项目 README/docs
primarySurfaceCheck	✅	首页首屏、quick start、nav/sidebar 前两组、CTA、reference、配置、常见任务和排错是否服务用户使用路径
immediateComprehension	✅	功能完整性、配置易懂性、首次读者即时理解三轴结论
deliveryChain	条件	docs-first / 最终用户手册场景填写 UserFacingDeliveryChainGate：确认需求事实源、用户最终文档、条件契约文档、技术方案输入和 ECR 用户文档符合性
siteInformationArchitecture	条件	文档站填写 DocsSiteInformationArchitectureGate：用户手册、reference、operations、compatibility、implementation、maintainer 面各归其位
flowAndFailurePath	条件	最终用户手册填写 UserManualFlowAndFailureGate：整体流程、关键角色、第一次成功、失败分流、排查命令、恢复/降级
realWorkflowExample	条件	队列 / 任务 / 异步 / 批处理类 quick start 填写 QueueDocsRealWorkflowGate，不能用单个硬编码 job 代替主路径
developerInfoPlacement	✅	必须晚于快速开始、常见用法、配置与排错
consumerMap	✅

章节顺序规则

推荐主顺序：

1. 这是什么
2. 适合谁、何时使用
3. 如何快速开始
4. 常见用法 / 最短可成功路径
5. 配置 / 运行要求
6. 常见问题与排错
7. 进一步文档
8. 开发 / 贡献 / 维护说明

docs-first 最终用户手册的顺序必须服务目标版本最终可执行路径；未实现、preview 或内部开发状态只能放在发布状态、限制说明或维护者区域，不能成为首屏、quick start 或 reference 主叙事。

禁止把以下内容前置为主叙事：

• 维护者内部流程
• 贡献约定
• 大段架构设计
• 与使用者无关的目录说明

项目类型差异

项目类型	用户最关心的信息	写作重点
library	怎么安装、怎么 import、最小示例	依赖、最短调用、返回值示例
service	怎么启动、端口/依赖、调用入口	启动命令、环境要求、运行方式
application	怎么进入界面、登录/前置条件、核心操作	快速体验路径、主要页面或操作
tool	怎么执行命令、输入输出、常见任务	CLI/脚本入口、常见命令、输出示例

性能 / 语法 / 能力矩阵写法

• README 面向使用者时，性能表、语法说明、能力矩阵或路由/匹配模式说明必须先给“如何选择”的结论，再解释字段和内部术语。
• 语法、路由、匹配、配置能力类章节默认同时包含：支持的形式、明确不支持的形式、优先级或冲突示例。
• 性能数据不得只给 benchmark 术语；应说明每一列对用户选择的含义，并标明测试条件或 N/A 理由。

执行步骤

1. 判断 projectType。
2. 确认真实 primaryAudience 是否为外部用户、内部使用者或协作方。
3. 执行 UserDocsPrimarySurfaceGate：冻结 targetSurface、documentLocation、首页/quick start/nav 主面和开发/维护内容后置策略。
4. 执行 UserDocsImmediateComprehensionGate：写出功能覆盖、配置易懂、首次读者即时理解的三轴检查。
5. docs-first / 最终用户手册场景执行 UserFacingDeliveryChainGate 与 FinalUserManualFirstGate，确认 README / 文档站内容来自已确认需求或产品需求，而不是未确认的整理草稿。
6. 文档站执行 DocsSiteInformationArchitectureGate；最终用户手册执行 UserManualFlowAndFailureGate；队列/任务/异步/批处理类 quick start 执行 QueueDocsRealWorkflowGate。
7. 按 userJourney 组织章节，不要从开发命令开始。
8. 只保留与当前项目类型相关的快速开始与示例块。
9. 建立 consumerMap，核对 README 与 package.json、CLI、website、examples、changelog、Profile 是否一致；公开能力页追加 UserPathContractSweep。
10. 交付后若任务要求 review，再调用 audit-readme。

与其他 Skill 的关系

• user-manual-authoring：站点文档、最终用户手册、接入手册和公开能力页的优先入口；README 是其专项分支。
• dev-docs：判断当前文档是否需要进入 user-manual-authoring 或 README 专项分支。
• dev-init：初始化项目时默认用本 Skill 生成 README。
• document-sync：代码/规范变更后检查 README 当前消费者与 consumerMap。
• audit-readme：实施完成后对 README / 用户使用文档做专项 review。

禁止

• 禁止把 README 默认写成“维护者操作手册”。
• 禁止让开发/贡献章节出现在快速开始之前。
• 禁止只写架构或目录而不给真实使用路径。
• 禁止把“站点文档 / 用户使用文档”写成开发契约、目标 API、数据模型或实现验收主叙事；这些内容只能后置或标为 developer/maintainer-only。
• 禁止把 docs-first 最终用户手册写成当前 preview / 当前不可用说明，也禁止把最终用户手册当成整站全部内容容器。
• 禁止队列、任务、异步处理、推送、导入导出或批处理类 quick start 只写单个硬编码 job；单 job 只能作为 API micro example，不能替代真实批量工作流。
• 禁止用内部分类名、benchmark 术语或 provider/adapter 实现名抢占用户主叙事；应先写用户场景与选择建议，再引出 API / 模式名称。