qiao-925 技术项目 README 结构
这个 skill-unit 处理的是“技术仓库入口文档”问题。它只适用于技术项目 README，不适用于公司介绍、产品宣传页、个人主页或通用文案型简介。
核心原则
1. 技术边界 —— 它是技术入口，不是通用介绍页
- README 的目标是让技术读者快速理解项目是什么、怎么启动、系统如何组织。
- 这个 skill 默认面向代码仓库、工程项目、框架、工具、服务或平台型仓库。
- 如果目标文档主要是品牌介绍、市场表达、业务方案或对外宣传，这个 skill 就不应主导。
2. 入口优先 —— 先解决首次上手问题
- README 首先要回答：项目是什么、怎么启动、最小验证是什么。
- 关键信息应尽量留在 README 中，不把首次上手必须知道的内容散落到多个外部文档。
- 对首次读者最关键的是最短闭环，而不是信息面面俱到。
3. 结构稳定 —— 必要模块不能缺位
- 技术 README 应保持稳定的高价值结构，避免每次都凭感觉组织。
- 可补充部署、测试、FAQ、贡献方式等，但不能替代入口核心模块。
- 缺信息时可以标注缺口，但不能假装结构完整。
4. 内容可核对 —— 不臆造，不拼凑
- 命令、目录、技术栈、配置项、架构说明必须能从仓库实际内容中核对。
- 若现状不完整，应明确写出“待补充”或“不确定”，不要靠猜测补齐。
- README 的可信度，优先于“看起来完整”。
AI Agent 行为要求
默认适用场景
| 场景 | 最低要求 | 不该做什么 |
|---|---|---|
| 新建技术 README | 建立稳定入口结构并补最小启动闭环 | 写成品牌介绍页或概念长文 |
| 补齐现有 README | 先核对仓库事实，再补缺失模块 | 用猜测补命令、配置和架构 |
| 重写 README | 保留入口文档职能，压缩噪音 | 把 README 扩成完整内部手册 |
| README 审查 | 判断入口能力和结构完整度 | 只看排版，不看可用性 |
必选模块
| 模块 | 最低要求 |
|---|---|
| 一句话描述 | 标题下方用 1-2 句话说明项目解决什么问题、为谁服务、核心价值是什么 |
| 快速开始 | 给出最短可运行路径：环境前置、安装、启动、最小验证 |
| 核心特性 | 列出 3-7 项关键能力，强调技术价值或使用收益 |
| 技术栈 | 说明主要语言、框架、中间件、存储、构建或部署工具 |
| 架构图 | 提供系统结构图，并补 2-5 句解释核心组件与主路径 |
| 目录结构说明 | 展示主要目录或关键文件，并说明职责 |
| 工作流程 | 说明核心业务流、数据流、调用链或研发使用流程 |
| 配置说明 | 说明配置文件、环境变量、默认值策略与敏感项处理方式 |
默认执行方式
- 先确认当前 README 是不是技术项目入口文档，而不是其他类型文案。
- 核对仓库中的启动命令、目录结构、技术栈、配置来源与架构事实。
- 先补一句话描述、快速开始和最小验证，再扩展后续模块。
- 对架构图、目录树和配置项补充解释，避免只有“图”或“树”。
- 若信息不足，显式写出缺口，不用猜测补齐。
不适用场景
以下情况不应由本 skill 主导：
- 产品官网式介绍页
- 公司或团队介绍 README
- 偏商业表达的方案文档
- 个人主页型仓库简介
场景化展开
- 需要快速套一个稳定骨架时，读取
references/recommended-outline.md - 需要判断什么算技术 README、什么不算时，读取
references/boundaries.md
与其他 skill 的协同边界
- 与
source-quality-control：当 README 包含较强事实性结论、外部依赖说明或版本信息时联动。 - 与
core-first-simplicity：当 README 信息过多、主线不清、需要收敛入口结构时联动。 - 与
architecture-governance：当架构说明需要准确描述分层、依赖方向或组件职责时联动。
判断标准
- 一个陌生技术读者能否只看 README 就完成基础启动。
- 是否能快速理解项目定位、核心能力和主要技术组成。
- 是否能看懂系统高层结构、目录职责和核心工作流程。
- 是否知道配置从哪里来、哪些是敏感项、哪些是默认值。
- 是否保持了“技术入口文档”定位，而没有滑向宣传文案。
反模式
- 把 README 写成公司、产品或个人宣传页。
- 用长篇背景叙述替代一句话描述和快速开始。
- 只有安装命令，没有启动与验证步骤。
- 只贴架构图和目录树，不解释语义。
- 把配置说明压缩成“见
.env.example”而不解释关键项。 - 为了完整感用猜测补齐仓库里不存在的信息。
参考资料
references/recommended-outline.md- 技术 README 推荐骨架与填写提示references/boundaries.md- 技术 README 的适用边界与排除场景