tech-docs-generator

技术文档生成器

概述

通过分析实际代码库，生成全面的技术文档。生成 API 参考、架构概览、入门指南和组件文档，并使用从项目代码中提取的真实示例，而非编造的示例。

开始时宣布：“我正在使用 tech-docs-generator skill 创建文档。”

第 1 阶段：代码库分析

扫描代码库，确定需要记录哪些内容。通过 Agent 工具并行部署子 Agent（最多 500 个，使用 subagent_type="Explore"）进行分析：

分析目标	需要记录的内容
导出的函数/类	公共 API 范围、签名、返回类型
API 路由/端点	REST、GraphQL、tRPC 定义及其方法
配置	环境变量、配置文件、功能标志
数据库架构	模型、迁移、关系
组件层级	UI 组件及其 props/接口
类型定义	接口、类型、Zod 架构、枚举
入口点	CLI 命令、主文件、服务器引导程序
依赖项	外部包及其作用

分析结束后停止——展示发现内容的摘要，并询问需要哪些类型的文档。

第 2 阶段：选择文档类型

类型	适用场景	输出路径	典型篇幅
API 参考	记录端点或公共函数	docs/api-reference.md	200-1000 行
架构概览	解释系统设计和数据流	docs/architecture.md	100-300 行
入门指南	帮助新开发者入门	docs/getting-started.md	50-150 行
组件文档	记录 UI 组件	docs/components/[name].md	50-200 行
贡献指南	说明如何参与贡献	docs/contributing.md	50-100 行
配置指南	记录配置选项	docs/configuration.md	50-200 行
迁移指南	记录版本升级	docs/migration/v[X]-to-v[Y].md	50-150 行

如果用户未指定，请询问需要哪种类型。如果用户请求多种类型，则通过 Agent 工具并行分派子 Agent，每种文档类型分派一个。

第 3 阶段：生成文档

分派 doc-generator Agent，并提供：

• 第 1 阶段的文件分析结果
• 第 2 阶段选定的文档类型
• 现有文档（用于更新，而非替换）
• 来自记忆文件的项目背景

生成后停止——逐节展示内容以供审阅，然后再保存。

文档格式规范

API 参考格式：

## `functionName(param1, param2)`

Description of what this function does.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | `string` | Yes | What it does |
| param2 | `Options` | No | Configuration options |

**Returns:** `Promise<Result>`

**Example:**
```typescript
const result = await functionName('value', { option: true });

**抛出：**如果 param1 为空，则抛出 ValidationError

**Architecture Overview format:**

```markdown
## System Architecture

### Overview
[High-level description with ASCII diagram]

### Components
| Component | Responsibility | Key Files |
|-----------|---------------|-----------|

### Data Flow
[How data moves through the system — request lifecycle]

### Key Decisions
| Decision | Rationale | Alternatives Considered |
|----------|-----------|------------------------|

入门指南格式：

## Prerequisites
[Required tools, versions, accounts]

## Installation
[Step-by-step with copy-pasteable commands]

## Configuration
[Required env vars and config]

## First Run
[How to start the app and verify it works]

## Next Steps
[Links to deeper documentation]

第 4 阶段：审阅并保存

逐节展示文档：

1. 每节结束后询问：“这是否准确描述了代码？”
2. 与实际代码交叉核对，验证准确性
3. 包含代码库中的真实示例，绝不编造示例
4. 获得批准后，保存到 docs/ 目录
5. 使用提交消息：docs(<scope>): add/update <doc-type>

准确性验证清单

检查项	验证方法
函数签名与代码一致	阅读源文件
示例确实可运行	跟踪代码路径
配置选项为最新	检查实际配置文件
列出的依赖项已安装	检查 package.json / requirements
引用的文件路径确实存在	使用 glob 查找文件

反模式 / 常见错误

错误	错误原因	应该怎么做
编造代码示例	读者复制粘贴后会遇到错误	从代码库中提取真实示例
记录内部 / 私有 API	会导致与实现耦合	只记录公开 / 导出的接口
编写与源代码重复的文档	很快就会过时	说明行为，而非实现
编写庞大的单体文档	难以浏览和维护	按关注点拆分（API、架构、配置）
记录尚未实现的行为	会误导用户当前具备的功能	记录目前实际可用的功能
跳过分析阶段	可能遗漏重要 API，或弄错签名	始终先分析代码
不验证示例能否编译 / 运行	有错误的文档比没有文档更糟	测试每个代码示例

防止自我合理化的检查项

• 不要在分析实际代码之前生成文档
• 不要编造示例——每个代码片段都必须来自代码库或经过代码库验证
• 不要记录私有 / 内部 API，除非用户明确要求
• 不要跳过审核阶段——将每个章节提交给用户核验
• 不要重复其他文档中已有的信息——应通过引用指向相关内容

集成点

技能	关系
prd-generation	上游：PRD 定义需要记录哪些内容
self-learning	并行：两者都会分析代码库；self-learning 会填充此处使用的记忆文件
api-design	上游：API 设计规范为 API 参考文档提供依据
spec-writing	并行：规范定义行为；文档说明用法
reverse-engineering-specs	上游：逆向工程得出的规范提供对行为的理解
code-review	下游：审核者检查代码变更是否同步更新了文档

验证关卡

在声称文档已完成之前：

1. 验证所有公开 API 均已记录，且签名正确
2. 验证代码示例确实可用（不是编造的）
3. 验证交叉引用指向现有内容
4. 验证文档与当前代码状态一致
5. 验证用户已批准每个章节
6. 运行文档中记录的命令，确认其可用

具体示例：API 参考条目

给定以下源代码：

export async function createUser(data: CreateUserInput): Promise<User> {
  // validates, hashes password, inserts into DB
}

生成以下文档：

## `createUser(data)`

Create a new user account with the provided details.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| data | `CreateUserInput` | Yes | User registration data |

**`CreateUserInput` shape:**
| Field | Type | Required | Constraints |
|-------|------|----------|-------------|
| email | `string` | Yes | Valid email format |
| password | `string` | Yes | Minimum 8 characters |
| name | `string` | Yes | 1-100 characters |

**Returns:** `Promise<User>` — the created user object (password excluded)

**Throws:**
- `ValidationError` — if input fails validation
- `ConflictError` — if email already exists

技能类型

灵活 — 根据项目需求调整文档的深度和格式，同时坚持先分析的原则并验证准确性。