README 生成器
通过分析实际代码库并询问针对性的澄清问题,为内部/公司代码仓库创建精美、全面的 README.md 文件。
为什么需要此技能
优秀的 README 是代码库的门户。对于内部项目尤其如此,缺失或内容单薄的 README 意味着每个新团队成员都要花费数小时来了解项目功能、运行方法和代码结构。此技能自动化了繁重的工作——它读取代码,推断它所能推断的内容,询问它无法确定的部分,并生成一个能让开发人员快速上手的 README。
工作流程
第 1 步:分析代码库
在询问用户任何问题之前,先执行结构化的四阶段分析,以收集尽可能多的上下文信息。这减轻了用户的负担——他们只需要填补空白,而不是描述您已经可以看到的内容。
为每项发现标记置信度级别:[confirmed](从源代码读取)、[inferred-high](强证据)、[inferred-low](部分证据)或 [unknown]。低置信度和未知的发现将成为第 2 步中的澄清问题。
有关详细的工具操作、grep 模式、提取清单和记录模板,请参见 references/analysis-phases.md。
阶段 1 — 项目元数据扫描: 全局搜索包管理器文件(pyproject.toml、package.json 等)、环境模板、Dockerfile、CI/CD 配置和工具链文件。读取每个文件并提取:项目名称/版本、语言、依赖项(分类并注明用途)、脚本/命令、环境变量(必需与可选)、CI 阶段、许可证。
阶段 2 — 架构扫描: 全局搜索所有源文件以映射目录结构。使用 grep 搜索入口点标记(if __name__、main() 等)并读取每个入口点。通过在所有源文件中使用 grep 搜索 import 语句来构建导入图——将模块分类为核心(高入度)、叶节点或编排器。使用指标清单识别架构模式(管道、MVC、分层、微服务、事件驱动、CLI、单体)。使用 grep 搜索配置加载模式以查找运行时配置文件。
阶段 3 — 深度模块分析: 读取每个重要的源文件(优先级:核心 → 入口点 → 最大 → 其余)。对每个文件,提取:用途(一句话)、关键导出及其签名、设计说明(非显而易见的决策、边界情况、约定)以及内部依赖项。通过导入图端到端追踪主要工作流,标记模块之间流动的数据类型。对于包含 8 个以上源文件的代码库,按依赖集群分发并行子代理。
阶段 4 — 支持基础设施扫描: 全局搜索测试文件和 fixture。读取每个测试文件的前 30-50 行以构建测试到模块的映射。使用 grep 搜索自定义异常类和 raise 语句以映射错误层次结构。扫描模板、资源和现有文档。提取常见错误场景以用于故障排查表。
第 2 步:询问澄清问题
分析后,就您无法自信推断的事项向用户提问。保持重点——不要询问您已知的内容。常见的空白点包括:
- 项目用途:此项目解决什么问题?谁使用它?(如果代码中不明显)
- 设置陷阱:是否存在非显而易见的先决条件、VPN 要求、内部包注册表或数据库设置步骤?
- 关键工作流:开发人员使用此项目最常做的 2-3 件事是什么?
- 部署:此项目如何/在哪里部署?(如果 CI/CD 配置中不明确)
- 团队约定:需要指出的任何命名约定、分支策略或模式?
- 联系信息:谁拥有/维护此项目?(联系方式部分的姓名 + 电子邮件)
简洁地呈现您的问题。如果代码库简单明了,并且您对分析有信心,您可能只需要 1-2 个问题——或者甚至不需要。请自行判断。
第 3 步:生成 README.md
使用下面的结构和指南编写 README。
README 结构
使用此作为模板。包含所有部分,但根据项目复杂性调整深度。在每一大部分之间使用 --- 水平线以增加视觉呼吸感。
# 项目名称
  
简要清晰的描述。使用**粗体**突出关键技术或产品类型。
---
## 目录
生成一个详尽的嵌套目录,包含所有 ## 和 ### 标题。将子部分在其父部分下方缩进,以便读者一目了然地看到完整结构。对于较长的 README 尤其重要——TOC 既是导航工具也是整个文档的大纲。
预期的深度示例:
- [概述](#概述)
- [架构](#架构)
- [高层架构](#高层架构)
- [目录结构](#目录结构)
- [模块依赖图](#模块依赖图)
- [入门指南](#入门指南)
- [先决条件](#先决条件)
- [安装](#安装)
- [运行测试](#运行测试)
- [环境变量](#环境变量)
- [使用方法](#使用方法)
- [示例:主要用例](#示例主要用例)
- [示例:次要用例](#示例次要用例)
- [API 参考](#api-参考)
- [资源 A](#资源-a)
- [资源 B](#资源-b)
- [故障排查](#故障排查)
- [联系方式](#联系方式)
- [许可证](#许可证)
文档中的每个 ### 标题都应在父 ## 标题下作为缩进条目出现。不要跳过子部分——详尽 TOC 的要点在于读者可以直接跳转到文档的任何部分。
---
## 概述
扩展描述。使用粗体标记关键术语。对于多步骤流程使用编号列表。
---
## 架构
### 高层架构
```mermaid
graph TD
...
```
目录结构
project-root/
├── src/ # 简要注释
├── tests/ # 简要注释
└── ...
[数据流 / 管道 / 模块依赖 — 附加图表]
...
入门指南
先决条件
安装
运行测试
环境变量
| 变量 | 必需 | 描述 |
|---|---|---|
DB_URL | 是 | PostgreSQL 连接字符串 |
使用方法
针对 2-3 个最常见操作的真实代码示例。
API 参考
故障排查
| 症状 | 可能原因 | 修复方案 |
|---|---|---|
错误消息 | 出了什么问题 | 如何修复 |
联系方式
如有疑问或支持,请联系:
- 姓名 — [email protected]
许可证
仅限内部使用 – 公司名称 专有软件。© [年份] [公司]。保留所有权利。
## Shields.io 徽章
始终在 `# 标题` 之后立即包含 shields.io 徽章(3-6 个徽章,涵盖语言、框架、关键库、包管理器、数据库、基础设施)。有关格式、示例和按类别的颜色建议,请参见 [references/badge-reference.md](references/badge-reference.md)。
## Mermaid 图指南
大量使用 mermaid 图——它们使架构、数据流和流程立即可理解。典型的 README 应包含 **3-6 个图**;复杂项目(数据管道、多服务系统)可能包含 **6-10+ 个**。有关何时使用每种图类型、最佳实践以及按项目类型的建议,请参见 [references/mermaid-guidelines.md](references/mermaid-guidelines.md)。
## 编写指南
- **具体胜过通用。** “运行 `npm run dev`” 优于“启动开发服务器。” 包含实际命令、文件路径和变量名。
- **为新团队成员编写。** 假设具备通用工程技能,但零项目上下文。
- **在首次提及和概述中**使用粗体标记关键术语和产品名称**。这有助于读者浏览。
- **对顺序流程使用编号列表。** “1. **提取**自 X 的数据。2. **转换**它。3. **加载**到 Y。”——动词加粗。
- **代码示例应可运行。** 尽可能从实际代码库复制。
- **环境变量表是必须的。** 列出每一个。
- **采用表格格式的故障排查**(症状 | 可能原因 | 修复方案)——易于浏览且一致。
- **目录结构注释应简短。** 每个目录一个简短短语。
- **始终包含联系方式部分。** 询问用户谁维护项目。格式:`**姓名** — [email protected]`。
- **在主要部分之间使用 `---` 水平线**以增强视觉结构。
## 输出
将 README 保存为仓库根目录(如果无法识别仓库根目录,则保存为当前工作目录)下的 `README.md`。如果已存在 README.md,请在覆盖前与用户确认——他们可能希望保留部分内容。