# Creekmoon Trailblazer Readme

> 为代码仓库生成或重构根目录 README。只要用户提到 README、项目介绍、项目文档、架构说明、新人接手、仓库导览、模块边界、模块协作，或工具/CLI/MCP/SDK 的安装、启动、用法、开箱即用、配置说明，就应该优先使用本技能。先判读者再选内容：读者要用起来就用法优先，读者要接手就边界与流程优先，两者都要就混合组织；章节与详略从项目实际长出来，不套固定骨架。不要写成业务说明书、项目知识图谱、项目记忆、完整 API 文档、代码说明书或深度研究报告。

- Skill: `creekmoon/creekmoon-trailblazer-readme` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add creekmoon/creekmoon-trailblazer-readme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/creekmoon/creekmoon-trailblazer-readme/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: creekmoon (https://skillmd.com/u/creekmoon)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/creekmoon/creekmoon-trailblazer-readme

---


# 项目 README 分场景写作技能

这个技能只做一件事：**按读者真实问题写对根目录 README**——让人打开 README 的第一问尽快得到回答。

写之前必须先判读者，再从对应 reference 里选内容块组织正文。reference 是素材库，**不是固定骨架**：块可省、可并、可重排、可改名。

如果仓库已经有 `README.md`，默认做 **增强式重构**，保留有价值内容，不推倒重写。

## 适用场景

- 用户要新建、重构、补强或精简根目录 README
- 业务侧：项目总览、功能模块、核心流程、模块边界、新人接手入口
- 工具侧：安装、启动、配置、调用示例、能力边界（能做什么 / 不能做什么）
- 用户说 README 看完仍不知道项目做什么，或不知道怎么跑起来
- 用户觉得 README AI 味重、像模板或知识图谱，需要压成高价值引导

## 不适用场景

- 只写接口字段与请求/响应示例的完整 API 文档（用专门的 API 文档技能）
- 只写运维部署手册、排障大全、环境变量百科（可作 README 的一小块，但不能单独膨胀成运维书）
- 单个模块的详细设计、类图、对象生命周期、项目知识图谱 / 项目记忆
- 需要跨仓库做完整业务归因的深度研究报告
- 逐行解释代码实现细节

这些内容可以存在于仓库其它文档，但不应该抢走根 README 的主轴。

## 第一步：判读者，不贴标签（第一闸门）

动手前只回答一个问题：**谁会在什么场景打开这份 README，他的第一问是什么？** 不要给仓库贴「业务 / 工具」的类型标签——同一个仓库可以有多类读者，内容按读者问题组合。

### 读者要「马上用起来」

典型：CLI、MCP Server、SDK、脚手架、开箱即用的服务，或使用者按「调用面」理解的组件。

→ **立即 Read** [`references/tool.md`](references/tool.md)，以其内容块为主轴。

### 读者要「看懂业务并接手改代码」

典型：后台/中台、有业务主线的应用、多模块业务聚合工程。

→ **立即 Read** [`references/business.md`](references/business.md)，以其内容块为主轴。

### 两者都要（很常见，别硬塞进一类）

典型：对内应用服务、集成适配层、facade、网关——联调方要把它跑起来，接手者要看懂上下游边界。

→ 以一类为主轴，从另一份 reference 借块。例如服务类仓库：上下游与边界叙事为主，同时保留一块精简的「运行与配置」。**不要为了像某种"标准 README"而删掉另一类读者需要的内容。**

### 模糊时

1. 先补问 1 个问题：这份 README 更希望读者「马上用起来」，还是「理解业务并接手改代码」？
2. 用户暂时无法补充时：有清晰「安装 / 启动 / 配置 / 调用」主路径 → 以 tool.md 为主；否则 → 以 business.md 为主。
3. 既像业务系统又像集成适配层时，优先写「本仓库直接拥有的能力」，不替其它系统补全业务闭环。

## 共享原则（所有 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 | 架构点到为止 | 入口文件、顶层目录（仅二次开发需要时） |

命名只作辅助线索。在能说清读者第一问的答案之前，不要开始写正文。

## 写正文前

1. 整理候选结论（可只在思考中完成，不必输出给用户）：

| 候选结论 | 证据类型 | 当前判断 | README 写法 |
|---------|----------|----------|-------------|
| 读者是谁、第一问是什么 | 直接证据 / 弱线索 | 可直接写 / 需保守 | 决定主轴与选块 |
| 项目定位 / 一句话能力 | 同上 | 同上 | 开场陈述 |
| 主路径（业务主线 或 启动/调用路径） | 同上 | 同上 | 主轴内容块 |
| 边界（不做什么 / 外部能力） | 同上 | 同上 | 必须写清易混边界 |

- **直接证据**：现有 README、主流程、运行配置、对外工具表、模块协作
- **弱线索**：目录名、包名、类名、注释、单个 adapter
- 激进与保守解释并存时，选保守；证据不足且不影响主线则宁可不写

2. **快速过一遍** [`references/examples.md`](references/examples.md) 的正反对照，确认自己没在写同款模板话。

## 输出前：阅读测试（替代结构合规检查）

- **换名测试**：把项目名遮掉，这段话还成立吗？成立 → 是模板话，改具体或删
- **抽删测试**：随机删掉一节/一表/一图，读者会察觉吗？不会 → 本来就多余
- **首屏测试**：读者第一问在一屏内有答案吗？
- **保留测试**：原文的可操作内容还在吗（或明确迁到哪、留了指针）？
- **重复测试**：同一信息（主链路/流程/关系）出现了几次？多于一次就合并
- **锚点测试**：每个论断都能指出一个真实名字/数字/机制吗？

## 建议输出风格

- 默认输出根目录 `README.md`
- 标题简短、具体，章节层级不超过两层
- 长度与项目体量挂钩：小项目允许一屏 README，不为撑结构硬写章节
- **先判读者 → Read 对应 reference → 过一遍 examples.md → 再写正文**

## 示例触发语句

**读者要接手：**

- 「帮我重写项目 README，让新同学快速了解项目是做什么的。」
- 「README 看完还不知道有哪些模块，改成项目总览。」
- 「补接手入口：改某类能力先从哪里看。」

**读者要用起来：**

- 「按开箱即用重写这个 MCP/CLI 的 README。」
- 「README 重点写怎么 Docker 启动、怎么接到 Cursor、有哪些工具。」
- 「用法说明太散，收成一份能直接跑起来的根 README。」