# Technical Readme Structure

> 技术项目 README 结构能力单元，帮助 Agent 在新建、补齐、重写或审查技术型仓库 README 时，围绕项目定位、快速开始、核心特性、技术栈、架构、目录、工作流与配置说明构建稳定入口，不将其误用为通用宣传文案或非技术文档模板。关键词：README、技术文档、项目入口、快速开始、架构图、目录结构、配置说明。

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

---


# 技术项目 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 句解释核心组件与主路径 |
| 目录结构说明 | 展示主要目录或关键文件，并说明职责 |
| 工作流程 | 说明核心业务流、数据流、调用链或研发使用流程 |
| 配置说明 | 说明配置文件、环境变量、默认值策略与敏感项处理方式 |

### 默认执行方式

1. 先确认当前 README 是不是技术项目入口文档，而不是其他类型文案。
2. 核对仓库中的启动命令、目录结构、技术栈、配置来源与架构事实。
3. 先补一句话描述、快速开始和最小验证，再扩展后续模块。
4. 对架构图、目录树和配置项补充解释，避免只有“图”或“树”。
5. 若信息不足，显式写出缺口，不用猜测补齐。

### 不适用场景

以下情况不应由本 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 的适用边界与排除场景