技术项目 README 结构规范

技术项目 README 必须优先回答：项目是什么、怎么启动、核心价值是什么、系统如何组织、如何配置。

---

核心原则

1. 先让首次读者看懂

• 读者应在 1 分钟内理解项目定位与启动方式。
• README 优先解决入口问题，不把关键信息藏到其他文档。

2. 结构完整且顺序稳定

• 技术性项目 README 至少包含本 skill 规定的 8 个必选模块。
• 可补充部署、测试、FAQ、贡献指南等，但不得替代必选模块。

3. 内容必须可核对

• 命令、目录、配置项、技术栈必须与仓库实际内容一致。
• 缺失信息时明确标注“待补充”与缺口，不得臆造。

行为要求

必选模块

模块	强制要求
一句话描述	位于标题下方，1-2 句话说明项目目标、主要用户或核心价值
快速开始	给出最短可运行路径：环境前置、安装、启动、最小验证
核心特性	列出 3-7 项关键能力，强调差异化与用户收益
技术栈	说明主要语言、框架、中间件、存储、构建或部署工具
架构图	必须提供系统结构图，可用 Mermaid、ASCII 或图片；图下补 2-5 句解释
目录结构说明	展示主要目录或文件，并说明职责，避免只贴树不解释
工作流程	说明核心业务流、数据流、调用链或研发使用流程
配置说明	说明配置文件、环境变量、默认值策略、敏感信息处理方式

推荐顺序

1. 项目标题
2. 一句话描述
3. 快速开始
4. 核心特性
5. 技术栈
6. 架构图
7. 目录结构说明
8. 工作流程
9. 配置说明

创建或更新 README 时

• 先核对实际启动命令、目录结构、配置来源与技术栈。
• 架构图需反映当前实现；若架构尚未稳定，明确标注当前版本范围。
• 快速开始必须以新读者最短路径为准，而不是罗列全部操作。
• 配置说明必须区分必填项、可选项与敏感项。

审查 README 时

• 若缺少任一必选模块，应判定为结构不完整。
• 若存在章节但只有标题、没有有效信息，应判定为未满足要求。
• 若关键信息散落在其他文档且 README 无法独立完成入门，应判定为入口能力不足。

判断标准

• 一个陌生开发者能否仅凭 README 完成基础启动？
• 能否快速看出项目边界、核心能力和主要技术组成？
• 能否理解系统高层结构、目录职责和典型工作流？
• 能否知道有哪些配置、哪些敏感、从哪里修改？

反模式

• 用长篇背景介绍替代一句话描述。
• 只有“安装依赖”而没有启动与验证步骤。
• 只有技术名词堆砌，没有核心特性说明。
• 只贴架构图，不解释组件职责或关系。
• 只贴目录树，不说明各目录用途。
• 将配置说明简化为“见 .env.example”，不解释关键项。
• 用猜测补全 README 中缺失的信息。

参考资料

• references/recommended-outline.md - 技术项目 README 推荐骨架与填写提示