Back to Details

tech-docs-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Documentation Generator

技术文档生成器

Overview

概述

Generate comprehensive technical documentation by analyzing the actual codebase. Produces API references, architecture overviews, getting started guides, and component documentation with real examples extracted from project code, not invented ones.
Announce at start: "I'm using the tech-docs-generator skill to create documentation."
通过分析实际代码库生成全面的技术文档。可生成API参考、架构概览、入门指南和组件文档，所有示例均提取自项目代码，而非虚构内容。
开始时请声明："I'm using the tech-docs-generator skill to create documentation."

Phase 1: Codebase Analysis

阶段1：代码库分析

Scan the codebase to identify what needs documenting. Deploy parallel subagents via the 
Agent
tool (up to 500, with 
subagent_type="Explore"
) to analyze:
Analysis TargetWhat to Capture
Exported functions/classesPublic API surface, signatures, return types
API routes/endpointsREST, GraphQL, tRPC definitions with methods
ConfigurationEnv vars, config files, feature flags
Database schemasModels, migrations, relationships
Component hierarchyUI components and their props/interfaces
Type definitionsInterfaces, types, Zod schemas, enums
Entry pointsCLI commands, main files, server bootstrap
DependenciesExternal packages and their roles
STOP after analysis — present a summary of what was found and ask which documentation types are needed.
扫描代码库以确定需要记录的内容。通过
Agent
工具部署并行子Agent（最多500个，
subagent_type="Explore"
）来分析以下内容：
分析目标要采集的内容
导出的函数/类公共API层、签名、返回类型
API路由/端点REST、GraphQL、tRPC定义及请求方法
配置环境变量、配置文件、功能开关
数据库 schema模型、迁移文件、关联关系
组件层级UI组件及其属性/接口
类型定义接口、类型、Zod schemas、枚举
入口点CLI命令、主文件、服务启动文件
依赖外部包及其作用
分析完成后停止，展示发现的内容摘要并询问需要生成哪些类型的文档。

Phase 2: Documentation Type Selection

阶段2：文档类型选择

TypeWhen to UseOutput PathTypical Size
API ReferenceDocumenting endpoints or public functions
docs/api-reference.md
200-1000 lines
Architecture OverviewExplaining system design and data flow
docs/architecture.md
100-300 lines
Getting StartedOnboarding new developers
docs/getting-started.md
50-150 lines
Component DocsDocumenting UI components
docs/components/[name].md
50-200 lines
Contributing GuideExplaining how to contribute
docs/contributing.md
50-100 lines
Configuration GuideDocumenting config options
docs/configuration.md
50-200 lines
Migration GuideDocumenting version upgrades
docs/migration/v[X]-to-v[Y].md
50-150 lines
Ask the user which type(s) they need if not specified. If multiple types are requested, dispatch parallel subagents via the 
Agent
tool — one per doc type.
类型适用场景输出路径典型长度
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，每种文档类型对应一个子Agent。

Phase 3: Generate Documentation

阶段3：生成文档

Dispatch 
doc-generator
agent with:
  • File analysis results from Phase 1
  • Documentation type selected in Phase 2
  • Existing documentation (to update, not replace)
  • Project context from memory files
STOP after generation — present each section for review before saving.
部署
doc-generator
Agent并传入以下参数：
  • 阶段1的文件分析结果
  • 阶段2选择的文档类型
  • 现有文档（用于更新而非替换）
  • 内存文件中的项目上下文
生成完成后停止，在保存前展示每个部分供审核。

Documentation Format Standards

文档格式标准

API Reference format:
markdown
undefined
API参考格式：
markdown
undefined

functionName(param1, param2)

functionName(param1, param2)

Description of what this function does.
Parameters:
NameTypeRequiredDescription
param1
string
YesWhat it does
param2
Options
NoConfiguration options
Returns: 
Promise<Result>
Example:
typescript
const result = await functionName('value', { option: true });
Throws: 
ValidationError
if param1 is empty

**Architecture Overview format:**

```markdown
Description of what this function does.
Parameters:
NameTypeRequiredDescription
param1
string
YesWhat it does
param2
Options
NoConfiguration options
Returns: 
Promise<Result>
Example:
typescript
const result = await functionName('value', { option: true });
Throws: 
ValidationError
if param1 is empty

**架构概览格式：**

```markdown

System Architecture

System Architecture

Overview

Overview

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

Components

Components

ComponentResponsibilityKey Files
ComponentResponsibilityKey Files

Data Flow

Data Flow

[How data moves through the system — request lifecycle]
[How data moves through the system — request lifecycle]

Key Decisions

Key Decisions

DecisionRationaleAlternatives Considered

**Getting Started format:**

```markdown
DecisionRationaleAlternatives Considered

**入门指南格式：**

```markdown

Prerequisites

Prerequisites

[Required tools, versions, accounts]
[Required tools, versions, accounts]

Installation

Installation

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

Configuration

Configuration

[Required env vars and config]
[Required env vars and config]

First Run

First Run

[How to start the app and verify it works]
[How to start the app and verify it works]

Next Steps

Next Steps

[Links to deeper documentation]
undefined
[Links to deeper documentation]
undefined

Phase 4: Review and Save

阶段4：审核与保存

Present documentation section by section:
  1. Ask after each section: "Does this accurately describe the code?"
  2. Cross-reference with actual code to verify accuracy
  3. Include real examples from the codebase — never invented ones
  4. After approval, save to 
    docs/
    directory
  5. Commit with message: 
    docs(<scope>): add/update <doc-type>
逐节展示文档：
  1. 每展示完一节询问："Does this accurately describe the code?"
  2. 与实际代码交叉验证准确性
  3. 包含来自代码库的真实示例，绝对不能使用虚构内容
  4. 获得批准后，保存到
    docs/
    目录
  5. 提交信息格式为：
    docs(<scope>): add/update <doc-type>

Accuracy Verification Checklist

准确性验证检查清单

CheckHow to Verify
Function signatures match codeRead the source file
Examples actually workTrace the code path
Config options are currentCheck actual config files
Dependencies listed are installedCheck package.json / requirements
File paths referenced existGlob for the files
检查项验证方式
函数签名与代码匹配阅读源文件
示例可正常运行追踪代码路径
配置选项为最新版本检查实际配置文件
列出的依赖已安装检查package.json / requirements文件
引用的文件路径存在搜索对应文件

Anti-Patterns / Common Mistakes

反模式/常见错误

MistakeWhy It Is WrongWhat To Do Instead
Inventing code examplesReaders copy-paste and get errorsExtract real examples from the codebase
Documenting internal/private APIsCreates coupling to implementationOnly document public/exported surface
Writing docs that duplicate source codeGoes stale immediatelyReference behavior, not implementation
Giant monolithic doc fileHard to navigate and maintainSplit by concern (API, architecture, config)
Documenting aspirational behaviorMisleads users about current capabilitiesDocument what actually works today
Skipping the analysis phaseMiss important APIs or get signatures wrongAlways analyze code first
Not verifying examples compile/runBroken docs worse than no docsTest every code example
错误错误原因正确做法
虚构代码示例读者复制粘贴后会报错从代码库中提取真实示例
记录内部/私有API会与实现产生耦合仅记录公共/导出的接口
编写的文档与源代码重复会很快过时记录行为而非实现细节
庞大的单块文档文件难以导航和维护按用途拆分（API、架构、配置等）
记录规划中的功能会误导用户对当前能力的认知仅记录当前实际可用的功能
跳过分析阶段会遗漏重要API或签名错误始终先分析代码
不验证示例是否可编译/运行错误的文档比没有文档更糟测试每个代码示例

Anti-Rationalization Guards

反合理化规则

  • Do NOT generate documentation without first analyzing the actual code
  • Do NOT invent examples — every code snippet must come from or be verified against the codebase
  • Do NOT document private/internal APIs unless explicitly requested
  • Do NOT skip the review phase — present each section for user verification
  • Do NOT duplicate information already covered in other docs — reference instead
  • 禁止在未分析实际代码的情况下生成文档
  • 禁止虚构示例——每个代码片段必须来自代码库或经过代码库验证
  • 禁止记录私有/内部API，除非明确要求
  • 禁止跳过审核阶段——每个部分都要提交给用户验证
  • 禁止重复其他文档中已涵盖的信息——改为引用对应内容

Integration Points

集成点

SkillRelationship
prd-generation
Upstream: PRD defines what needs documenting
self-learning
Parallel: both analyze codebase; self-learning populates memory files used here
api-design
Upstream: API design specs inform API reference docs
spec-writing
Parallel: specs define behavior; docs explain usage
reverse-engineering-specs
Upstream: reverse-engineered specs provide behavioral understanding
code-review
Downstream: reviewer checks if docs were updated alongside code changes
Skill关系
prd-generation
上游：PRD定义了需要记录的内容
self-learning
并行：两者都分析代码库；self-learning会填充此处使用的内存文件
api-design
上游：API设计规范为API参考文档提供依据
spec-writing
并行：规范定义行为；文档解释使用方法
reverse-engineering-specs
上游：逆向生成的规范可帮助理解行为
code-review
下游：审核者会检查代码变更时是否同步更新了文档

Verification Gate

验证关口

Before claiming documentation is complete:
  1. VERIFY all public APIs are documented with correct signatures
  2. VERIFY code examples actually work (not invented)
  3. VERIFY cross-references link to existing content
  4. VERIFY documentation matches current code state
  5. VERIFY the user has approved each section
  6. RUN any documented commands to confirm they work
在声明文档完成前：
  1. 验证所有公共API都已记录，且签名正确
  2. 验证代码示例确实可用（非虚构）
  3. 验证交叉引用链接指向现有内容
  4. 验证文档与当前代码状态匹配
  5. 验证用户已批准每个部分
  6. 运行所有记录的命令确认其可正常工作

Concrete Example: API Reference Entry

具体示例：API参考条目

Given this source code:
typescript
export async function createUser(data: CreateUserInput): Promise<User> {
  // validates, hashes password, inserts into DB
}
Generate this documentation:
markdown
undefined
给定以下源代码：
typescript
export async function createUser(data: CreateUserInput): Promise<User> {
  // validates, hashes password, inserts into DB
}
生成对应文档：
markdown
undefined

createUser(data)

createUser(data)

Create a new user account with the provided details.
Parameters:
NameTypeRequiredDescription
data
CreateUserInput
YesUser registration data
CreateUserInput
shape:
FieldTypeRequiredConstraints
email
string
YesValid email format
password
string
YesMinimum 8 characters
name
string
Yes1-100 characters
Returns: 
Promise<User>
— the created user object (password excluded)
Throws:
  • ValidationError
    — if input fails validation
  • ConflictError
    — if email already exists
undefined
Create a new user account with the provided details.
Parameters:
NameTypeRequiredDescription
data
CreateUserInput
YesUser registration data
CreateUserInput
shape:
FieldTypeRequiredConstraints
email
string
YesValid email format
password
string
YesMinimum 8 characters
name
string
Yes1-100 characters
Returns: 
Promise<User>
— the created user object (password excluded)
Throws:
  • ValidationError
    — if input fails validation
  • ConflictError
    — if email already exists
undefined

Skill Type

Skill类型

Flexible — Adapt documentation depth and format to project needs while preserving the analyze-first principle and accuracy verification.
灵活——在遵守先分析原则和准确性验证的前提下，可根据项目需求调整文档深度和格式。