creekmoon 项目 README 分场景写作技能
这个技能只做一件事：按读者真实问题写对根目录 README——让人打开 README 的第一问尽快得到回答。
写之前必须先判读者，再从对应 reference 里选内容块组织正文。reference 是素材库，不是固定骨架：块可省、可并、可重排、可改名。
如果仓库已经有 README.md，默认做 增强式重构，保留有价值内容，不推倒重写。
适用场景
- 用户要新建、重构、补强或精简根目录 README
- 业务侧：项目总览、功能模块、核心流程、模块边界、新人接手入口
- 工具侧：安装、启动、配置、调用示例、能力边界（能做什么 / 不能做什么）
- 用户说 README 看完仍不知道项目做什么，或不知道怎么跑起来
- 用户觉得 README AI 味重、像模板或知识图谱，需要压成高价值引导
不适用场景
- 只写接口字段与请求/响应示例的完整 API 文档（用专门的 API 文档技能）
- 只写运维部署手册、排障大全、环境变量百科（可作 README 的一小块，但不能单独膨胀成运维书）
- 单个模块的详细设计、类图、对象生命周期、项目知识图谱 / 项目记忆
- 需要跨仓库做完整业务归因的深度研究报告
- 逐行解释代码实现细节
这些内容可以存在于仓库其它文档，但不应该抢走根 README 的主轴。
第一步：判读者，不贴标签（第一闸门）
动手前只回答一个问题：谁会在什么场景打开这份 README，他的第一问是什么？ 不要给仓库贴「业务 / 工具」的类型标签——同一个仓库可以有多类读者，内容按读者问题组合。
读者要「马上用起来」
典型：CLI、MCP Server、SDK、脚手架、开箱即用的服务，或使用者按「调用面」理解的组件。
→ 立即 Read references/tool.md，以其内容块为主轴。
读者要「看懂业务并接手改代码」
典型：后台/中台、有业务主线的应用、多模块业务聚合工程。
→ 立即 Read references/business.md，以其内容块为主轴。
两者都要（很常见，别硬塞进一类）
典型：对内应用服务、集成适配层、facade、网关——联调方要把它跑起来，接手者要看懂上下游边界。
→ 以一类为主轴，从另一份 reference 借块。例如服务类仓库：上下游与边界叙事为主，同时保留一块精简的「运行与配置」。不要为了像某种"标准 README"而删掉另一类读者需要的内容。
模糊时
- 先补问 1 个问题：这份 README 更希望读者「马上用起来」，还是「理解业务并接手改代码」？
- 用户暂时无法补充时：有清晰「安装 / 启动 / 配置 / 调用」主路径 → 以 tool.md 为主；否则 → 以 business.md 为主。
- 既像业务系统又像集成适配层时，优先写「本仓库直接拥有的能力」，不替其它系统补全业务闭环。
共享原则（所有 README 都遵守）
- 结论强度不超过证据强度：先写代码和现有文档已证明的，再写保守判断
- 目录名、类名、DTO 字段、注释、行业术语只能作线索，不能单独证明定位或完整业务域
- 重构红线：原文中的可操作内容（命令、配置、端口、示例）只能保留或迁移，不得删除——删了读者就跑不起来；迁移要在 README 留指针
- 同一信息全篇只出现一次：主链路、模块关系、流程，选一个最合适的位置呈现，其它地方用文字回指，不重复画图/列表
- 每个论断带具体锚点：真实项目名、模块名、数字、机制；通篇写不出锚点的段落多半可删
- 表格全篇默认 ≤2 张：一张表只解决一个问题；某一列填不出真内容就删列，不凑单元格
- 章节名从项目内容长出来：写「一条消息怎么走到用户手里」，不写「快速总览」「核心业务流程」这类通用名
- 判断不清时用中性表述；必要时只补 1–2 行待确认，不强定性
- 用户点名要的内容（如"专门梳理上下游"）往往就是读者最关心的——放前面、写足，不要被其它章节稀释
信息收集（先判读者，再按表收集）
两边都先看：现有 README.md、根构建文件、顶层目录、Docker / CI。然后分岔：
以 business.md 为主时（详见该文件）：
| 优先级 | 目标 | 读什么 |
|---|---|---|
| 1 | 定位与类型 | README、构建文件、顶层目录 |
| 2 | 功能模块 | 子模块、模块 README、核心功能入口 |
| 3 | 接手锚点 | 启动模块、主链路入口、少量稳定入口类 |
| 4 | 核心业务流程 | 最短可解释的端到端路径 |
| 5 | 外部边界 | 依赖的外部系统、协议、存储 |
以 tool.md 为主时（详见该文件）：
| 优先级 | 目标 | 读什么 |
|---|---|---|
| 1 | 能力与边界 | README、对外 tools/commands/API、安全/只读声明 |
| 2 | 首选启动路径 | Docker/compose、发布镜像、一键安装脚本 |
| 3 | 配置与接入 | 环境变量、客户端配置示例、端口/健康检查 |
| 4 | 最小可跑示例 | 官方示例、inspector、调用顺序 |
| 5 | 架构点到为止 | 入口文件、顶层目录（仅二次开发需要时） |
命名只作辅助线索。在能说清读者第一问的答案之前，不要开始写正文。
写正文前
- 整理候选结论（可只在思考中完成，不必输出给用户）：
| 候选结论 | 证据类型 | 当前判断 | README 写法 |
|---|---|---|---|
| 读者是谁、第一问是什么 | 直接证据 / 弱线索 | 可直接写 / 需保守 | 决定主轴与选块 |
| 项目定位 / 一句话能力 | 同上 | 同上 | 开场陈述 |
| 主路径（业务主线 或 启动/调用路径） | 同上 | 同上 | 主轴内容块 |
| 边界（不做什么 / 外部能力） | 同上 | 同上 | 必须写清易混边界 |
- 直接证据：现有 README、主流程、运行配置、对外工具表、模块协作
- 弱线索：目录名、包名、类名、注释、单个 adapter
- 激进与保守解释并存时，选保守；证据不足且不影响主线则宁可不写
- 快速过一遍
references/examples.md的正反对照，确认自己没在写同款模板话。
输出前：阅读测试（替代结构合规检查）
- 换名测试：把项目名遮掉，这段话还成立吗？成立 → 是模板话，改具体或删
- 抽删测试：随机删掉一节/一表/一图，读者会察觉吗？不会 → 本来就多余
- 首屏测试：读者第一问在一屏内有答案吗？
- 保留测试：原文的可操作内容还在吗（或明确迁到哪、留了指针）？
- 重复测试：同一信息（主链路/流程/关系）出现了几次？多于一次就合并
- 锚点测试：每个论断都能指出一个真实名字/数字/机制吗？
建议输出风格
- 默认输出根目录
README.md - 标题简短、具体，章节层级不超过两层
- 长度与项目体量挂钩：小项目允许一屏 README，不为撑结构硬写章节
- 先判读者 → Read 对应 reference → 过一遍 examples.md → 再写正文
示例触发语句
读者要接手：
- 「帮我重写项目 README，让新同学快速了解项目是做什么的。」
- 「README 看完还不知道有哪些模块，改成项目总览。」
- 「补接手入口：改某类能力先从哪里看。」
读者要用起来：
- 「按开箱即用重写这个 MCP/CLI 的 README。」
- 「README 重点写怎么 Docker 启动、怎么接到 Cursor、有哪些工具。」
- 「用法说明太散，收成一份能直接跑起来的根 README。」