| name | creekmoon-trailblazer-readme |
| version | 2.1.0 |
| description | 为代码仓库生成或重构根目录 README 的项目总览技能。只要用户提到 README、项目介绍、项目文档、架构说明、新人接手、仓库导览、模块边界、模块协作，就应该优先使用本技能。特别适合把零散工程结构整理成“读者 3 分钟能建立心智模型”的根 README：准确说明项目是什么、包含哪些功能模块、核心业务流程怎么走。生成时默认从代码证据出发，代码细节只作为理解功能边界的线索，不把 README 写成业务说明书、接口文档、代码说明书或深度研究报告。 |
项目 README 总览写作技能
这个技能只做一件事：把仓库理解结果整理成一份适合放在根目录的项目级总览 README。
目标不是写业务 PRD，也不是写代码说明书，而是让第一次接触项目的人尽快建立心智模型，回答下面几个问题：
- 这个仓库在整个系统里承担什么职责，边界在哪里
- 它包含哪些功能模块，每个模块直接做什么、不做什么
- 核心业务流程按什么先后顺序推进
如果仓库已经有 README.md，默认做 增强式重构，保留有价值内容，不直接推倒重写。
整体结构：先业务，后技术
本技能要求生成的 README 采用两段式结构：
- 前半部分（业务篇）：完全面向业务，回答“这个系统解决了什么问题、承担什么业务职责、核心业务主线是什么”。不出现技术栈、包结构、启动命令、架构分层等任何技术细节。
- 后半部分（技术/工程篇）：保留项目级技术总览，说明功能模块边界、核心流程、模块关系等，帮助读者建立工程心智模型。
前半部分至少包含：标题与一句话定位、一屏摘要、业务背景与主线。后半部分至少包含：功能模块清单、核心业务流程。
业务背景与主线是帮助读者理解“为什么要有这个系统”的关键章节，应前置到业务篇，而不是放在附录。
适用场景
- 用户要新建项目 README
- 用户要重构、补强、精简现有 README
- 用户想补充“项目总览 / 功能模块 / 核心流程 / 模块边界”
- 用户说“这个 README 看完还是不知道项目是做什么的”
- 用户希望沉淀项目级顶层视野文档
- 用户希望 README 解释“项目定位、功能边界、核心流程怎么走”
不适用场景
- 只写接口字段、请求响应示例的 API 文档
- 只写部署步骤、运维参数、环境变量说明
- 只做某一个模块的详细设计文档
- 代码层面的包结构说明、类图、对象模型
- 对象流转、生命周期状态机、对象谱系树
- 工程操作手册（启动命令、配置 key、调试入口、排查路径）
- 需要逐行解释代码实现细节
- 需要跨仓库、跨上下游做完整业务归因的深度研究报告
这些内容可以存在于仓库里，但不应该占据根目录 README 的主轴。
第一原则
- README 前半部分先回答“这个系统解决什么业务问题、承担什么业务职责”，后半部分再回答“包含哪些功能模块、核心业务流程怎么走”；不展开代码结构、启动命令、配置项、调试入口等操作性细节
- README 是项目级顶层视野，不是代码说明书，也不是详细设计文档；代码包结构、对象流转、生命周期、工程操作手册等深度内容应留给二次提问或专门文档
- 优先讲 业务职责与功能边界，代码细节只作为理解功能边界的线索
- 在业务篇（
### 1 ~ ### 3）里，必须先建立读者心智模型：项目定位、业务职责、核心业务主线
- 只写功能层与模块边界，不写包名、类名、方法、SQL、字段校验、装配细节
- 信息要能支撑新人快速建立项目认知，而不是堆满业务名词或技术名词
- 图和表都要短，默认只保留最关键的一层
- 结论强度不能超过证据强度
- 先写“代码和现有文档已经证明了什么”，再写“基于证据可做的保守判断”
- 目录名、类名、DTO 字段、注释、行业术语只能作为线索，不能单独证明项目定位、系统边界或完整业务域
- 功能模块清单和核心流程是 README 的主叙事，不要后置到附录
- 启动命令、环境变量、接口地址、Topic 清单、包结构图等操作细节不纳入根目录 README
- 判断不清时，优先使用更中性的定位句；必要时只补 1-2 行待确认说明，不把 README 写成审计报告
开始前先判断 README 主轴
先判断这个 README 应该采用哪种总览主轴。类型只影响叙事重心，不要把它写成模板分类标签。
1. 应用服务型
适用于有明确运行进程的后端服务、后台系统、定时任务、消息消费等仓库。
主轴优先级：
- 仓库定位与项目类型
- 功能模块清单
- 核心业务流程
2. 能力平台 / SDK 型
适用于框架、SDK、平台能力层、中间件、脚手架、通用组件等仓库。
主轴优先级：
- 能力边界与接入方式
- 使用方如何调用
- 内部模块分层与扩展点
3. 多模块 / 聚合工程型
适用于多模块、多个子项目共存、多个子服务共仓等结构。
主轴优先级：
- 子模块职责地图
- 模块间依赖方向
- 可独立运行的模块与共享模块的区分
4. 暂未定型 / 证据不足
当定位不清时，不要强行包装成完整业务系统。优先写成：
- 当前代码显示它直接拥有的能力
- 主要功能模块和各自边界
- 核心业务流程的可证实事实
- 待确认的业务上下游关系
判断规则：
- 先看 README、构建文件、顶层目录结构，再看目录名和业务术语；不优先读具体代码文件
- 如果去掉命名暗示后，项目定位仍然成立，才使用较强定性
- 如果项目既像业务系统又像集成适配层，优先从“本仓库直接拥有的能力”描述，不替其它系统补全业务闭环
- 当 README 主轴依赖关键边界判断但证据不足时，先补问 1 个问题；如果用户暂时无法补充，就采用更中性的表述
信息收集与探索优先级
先按优先级收集能决定 README 主轴的信息，不要一上来就沉进代码细节或底层工具类：
| 优先级 | 目标 | 读什么 |
|---|
| 1 | 仓库定位与项目类型 | 现有 README.md、根构建文件、顶层目录结构、Docker / CI 配置 |
| 2 | 功能模块划分 | 顶层目录 / 子模块、模块级 README、核心功能入口 |
| 3 | 核心业务流程 | 从外部请求到核心业务处理再到结果返回的最短可解释路径 |
| 4 | 外部依赖与边界 | 本仓库依赖的外部系统、协议、存储 |
补充规则：
- 命名只能作为辅助线索，不能替代项目文档和模块职责证据
- 如果项目很大，先找“贯穿全链路的核心功能入口”和“顶层模块划分”，不要先读最底层工具类
- 在能说明“项目定位、模块分工、核心流程”之前，不要开始写正文
- 不要求把所有业务背景讲完整；README 的边界是帮助读者建立项目心智模型，深层业务可留给二次提问或深度研究
写正文前必须先完成候选结论审查
在信息收集完毕后、第一段正文落笔前，必须先完成下面这些结论的审查，再开始写正文：
- 项目定位
- 项目类型
- 功能模块边界
- 核心流程顺序
- 对外系统关系
先整理一个轻量表：
| 候选结论 | 证据类型 | 当前判断 | README 写法 |
|---|
{结论} | 直接证据 / 弱线索 | 可直接写 / 需保守改写 / 暂不写入 | 主结论 / 保守表述 / 待确认说明 |
证据判断规则：
- 直接证据：现有 README、架构文档、主流程、核心模块协作、运行配置
- 弱线索：目录名、包名、类名、DTO 字段、注释、第三方协议名、单个模块 / adapter
审查规则：
-
事实审查
- 如果去掉命名暗示后，这个结论仍然成立，才可以保留较强表述
- 只有弱线索时，不能直接写“本系统就是某类完整业务系统”或“该模块负责完整业务域”
-
边界审查
- 我写的是“本仓库直接拥有的能力”，还是“本仓库对接 / 适配 / 消费的外部能力”？
- 我是不是把外部系统术语、回调协议、DTO 命名误写成了内部业务边界？
- 我是不是把某个局部模块写成了整个系统的主线？
-
反向否证
- 如果同时存在激进解释和保守解释，优先选择保守解释
- 证据不足但又影响读者理解时，只补 1-2 行待确认说明；如果不影响主线，宁可不写
-
叙事顺序审查
- 业务篇（
### 1 ~ ### 3）的首句应该先让读者知道“项目职责、业务痛点、核心主线”
- 如果目前只能列目录，还说不清业务职责和核心主线，先回去补判断，不要直接落正文
推荐改写方式：
- 可直接写：证据充分，且能回到主流程、模块关系或现有项目文档
- 保守改写：写成“按当前结构看更像…”、“当前更接近…”、“从模块协作看主要承担…”
- 暂不写入：只有命名、注释、局部接口、第三方术语，没有更强证据支撑
输出结构
默认按下面顺序组织 README。采用先业务后技术的两段式结构。
业务篇（前半部分）：完全面向业务，不说技术实现。
技术/工程篇（后半部分）：功能边界与流程，帮助建立工程心智模型。
除非项目类型明显不适配，否则不要轻易跳过前 5 节。
1. 标题与一句话定位
这是 README 的业务入口，必须完全面向业务，不讲技术栈。
必须包含：
- 项目名称
- 1 句话说明它解决什么业务问题（用业务语言描述痛点或场景）
- 1 句话说明它在系统中承担什么业务职责：服务平台、业务系统、能力中心、适配网关、聚合工程等
- 1 句话说明它直接拥有的业务能力和不直接拥有的外部能力
可选：极短的技术栈摘要（仅 1 个短语，不能盖过项目定位）。
推荐写法（业务视角）：
xxx 是一个面向 {业务场景} 的 {项目类型}，核心解决 {业务痛点} 的问题。系统围绕 {核心业务主线} 运转，同时承担 {主要业务职责 1} 和 {主要业务职责 2}。
xxx 是一个 {项目类型} 的 {项目定位}，主要负责 {本仓库直接拥有的能力}；它通过 {协议/渠道} 接收输入，由 {功能模块} 推进处理，并把结果输出给 {下游系统/用户}。
2. 一屏摘要（项目总览）
这一节是整个 README 的核心入口，必须做到一屏内让读者知道系统是做什么的。
建议包含：
- 一句话方案：用业务语言描述端到端的主链路，写成
输入/触发 -> 核心处理 -> 输出/结果 的连贯句式
- 1 张极简主链路图（可选）：只画 3-5 个业务阶段节点，不画所有分支，不使用代码术语
- 1 张项目事实表
事实表推荐列：
| 项 | 说明 |
|---|
| 系统形态 | 一句话描述系统类型（如运营后台、中台服务、聚合工程等） |
| 核心主线 | 1 句话概括端到端业务主线 |
| 主要场景 | 1-3 个核心使用场景 |
| 主要对象 | 2-4 个贯穿系统的核心业务对象 |
事实表里不出现技术细节列（技术栈、主要入口、包域、关键依赖）；它们不属于业务篇。
3. 业务背景与主线
这一节回答“为什么要有这个系统”和“它在业务大图里承担什么角色”。
必须包含：
- 系统承担的业务职责：分点说明系统当前主要承担哪几类业务职责（如面向用户的业务闭环、面向第三方的集成适配等）
- 业务定位判断：按当前代码结构，系统更像什么业务形态（如“业务中台 + 运营后台的混合形态”）
- 核心业务主线表：用阶段表展示业务主线的关键环节
核心业务主线表推荐格式：
写法要求：
- 阶段名使用业务阶段名，如“询价比价”“下单预约”“在途跟踪”“账单结算”
- 核心动作描述用业务语言，不出现技术实现细节
- 只列主线阶段，不列异常处理、技术校验、数据转换等分支
4. 功能模块清单
这是本技能的重点章节。它不是目录树，也不是代码包清单，而是让读者快速知道“这个项目由哪些功能模块组成，每个模块直接做什么”。
推荐格式：简洁列表，每个模块一行说明。
写法要求：
一句话职责 写成完整职责句，不要只写名词；控制在 20 字以内不做什么 只写最容易混淆的边界，不需要每行硬凑；没有明显混淆时留空- 如果一个模块只是通用支撑（如公共工具、配置中心），不要把它提升成主模块
- 禁止出现代码层面的列（包名、类名、接手入口、改代码时先看哪里）
- 禁止使用“上游输入 / 下游输出 / 对接方式 / 架构角色 / 不重点负责”这种碎片化宽表
如果模块间有清晰的层次关系，可以可选地在前面加一张极简层次图，但图不是必选项。图中只使用功能职责名，不出现代码术语。
5. 核心业务流程
这一节说明“一个典型业务请求 / 事件 / 任务进入后，按什么大阶段推进”。
只保留一张极简流程图，不另配阶段表。
流程图规则：
- 默认
3-5 个节点，硬上限 7 个
- 节点优先使用业务阶段名，例如“请求接入”“规则校验”“核心处理”“结果输出”“异步通知”
- 可以在节点里补充负责该阶段的功能模块名，但不要让图变成模块清单
- 只画主干流程，不画所有异常、鉴权、参数校验、数据转换等分支
- 不展开“哪个模块调用哪个模块、哪个对象在哪个包被改变”这类实现细节
如果必须在图外补充文字，用 1-2 句话概括即可，不要写成宽表。
更新已有 README 的规则
如果仓库已经有 README.md，遵守下面的默认策略：
- 保留原有有价值内容
- 优先前置新增“项目总览”章节
- 旧的工程说明、仓库导航、接口入口、包结构说明等操作性或代码级细节，如果存在，建议迁移到专门的开发文档或 wiki，不要在 README 中保留
- 如果旧章节比较窄，可以改名为
局部说明 或 补充信息
- 启动方式、接口文档、运行入口、包结构图等不保留在根目录 README
- 只在明显重复、冲突或失效时做删改
不要因为想追求“统一风格”就把原文全部重写掉。
图表约束
图的约束
- 默认
1-2 张图足够：一张项目结构图（可选）、一张核心流程图
- 单张图优先不超过
7 个节点，硬上限 10
- 只表达主干流程和模块层级，不表达所有分支
- 节点使用功能职责名，不出现代码术语（如 Controller、Service、DAO）
- 解释优先放在图下方 1-3 行，不把整段说明塞进图里
表的约束
- 一张表只解决一个问题
- 默认
4-6 行最佳
- 字段少而准，避免把表写成“压缩版设计文档”或碎片化信息仓库
- 表格必须让读者形成关系：职责边界、先后顺序至少命中一种
- 不要使用过宽的模块对接表；超过 4 列时先问自己能否拆成两张更清楚的表
语言与表达规则
- 先结论，后展开
- 业务篇（
### 1 ~ ### 3）的首句优先写项目职责、业务痛点和核心主线，不要先写业务愿景或技术栈清单
- 段落短，句子直
- 使用功能视角的词汇（模块、流程、处理、校验、输出等），不使用代码视角的词汇（包域、入口、应用层、领域层、适配层、持久化、DTO 等）
- 可以点名模块名，但不要展开包名、类名、方法、SQL、字段校验、配置 key
- 不重复同一个信息在图、表、段落里各讲一遍
- 对存在歧义的地方，要明确写“当前按 X 理解”
- 项目定位、模块角色要能回到具体证据，不要只因为名字“像”就下结论
- 推断型表述要带保守措辞，例如“按当前结构看更像…”、“当前更接近…”
- 把“本仓库直接拥有的能力”和“本仓库对接 / 适配 / 消费的外部能力”分开写
- 第三方协议名、行业术语、外部系统字段可以作为背景线索，但不能自动补全成完整业务边界
- 业务背景只保留帮助理解功能边界的部分；不要把 README 写成业务介绍稿
- 功能模块说明应该靠前；目录树、启动命令、接口地址、包结构图等操作清单不纳入根目录 README
常见反模式
- README 写成业务介绍，读者看完不知道项目有哪些模块
- README 只剩目录列表，看不出模块职责和流程
- 业务篇（
### 1 ~ ### 3）一上来就是业务愿景、产品术语或技术栈大段说明
- 模块划分只列代码包名（如
controller/service/dao/client），没有说明它们承担什么功能
- 核心流程只有抽象阶段名，没有说明先后顺序
- 图太大，把所有模块全画进去
- 表太密或太宽，读者 30 秒内抓不到结论
- 写成“详细设计”或“代码说明书”而不是“项目总览”
- 在 README 中展开代码包结构、对象流转、生命周期阶段
- 在 README 中写入启动命令、配置 key、环境变量、调试入口等工程操作细节
- 在读者还没建立项目心智前，就展开完整启动命令、接口地址、Topic 清单
- 只因为目录名、类名、DTO 字段，就把项目直接写成某类系统
- 把外部接口、SDK、回调协议、适配层痕迹写成本仓库自有核心能力
- 为了让 README 更完整，脑补出代码里并没有闭环证明的业务主线
- 使用“上游输入 / 下游输出 / 对接方式 / 架构角色 / 不重点负责”这种宽表，把本该连贯的模块关系拆成碎片
- 把模块职责、对接关系、代码入口、阅读顺序全部塞进一张宽表，导致读者看不出主次
输出前检查清单
完成 README 前，至少检查下面这些问题：
整体视角收尾
如果答案不够明确，继续压缩细节，补强功能主线。
建议输出风格
如果用户没有指定格式，优先输出为：
- 根目录
README.md
- 标题简短
- 章节层级不超过两层
- Mermaid 图简洁（节点用功能名，不用代码术语）
- 表格简洁
- 以“先业务后技术”为默认定位：先定位与摘要，再业务背景与主线，然后功能模块清单，最后核心业务流程
示例触发语句
下面这些请求都应该优先触发本技能：
- “帮我重写一下项目 README，让新同学能快速了解项目是做什么的。”
- “这个 README 看完还是不知道有哪些模块、做什么的，帮我改成项目总览。”
- “补一版根目录 README，重点讲项目定位、功能模块和核心流程。”
- “这个仓库的 README 不要写成业务介绍，要让人快速知道它有什么模块、主流程怎么走。”
- “帮我把 README 里的上游输入、下游输出那种表改掉，读起来太碎了。”
