code-documentation

代码文档技能

概述

此技能可为软件项目、代码库、库和 API 生成专业、全面的文档。它遵循 React、Django、Stripe 和 Kubernetes 等项目的行业最佳实践，生成准确、结构清晰且对新贡献者和资深开发者都有用的文档。

输出内容涵盖单文件 README 到多文档开发者指南，并始终根据项目复杂度和用户需求进行调整。

核心能力

• 生成全面的 README.md 文件，包含徽章、安装说明、用法和 API 参考
• 根据源代码分析创建 API 参考文档
• 通过图表编写架构和设计文档
• 编写开发者入门指南和贡献指南
• 根据提交历史或发行说明生成变更日志
• 按照特定语言的惯例编写内联代码文档
• 支持 JSDoc、docstrings、GoDoc、Javadoc 和 Rustdoc 格式
• 根据项目使用的语言和生态系统调整文档风格

何时使用此技能

遇到以下情况时，始终加载此技能：

• 用户要求为任何代码“编写文档”“创建文档”或“撰写文档”
• 用户请求 README、API 参考或开发者指南
• 用户分享代码库或仓库，并希望生成文档
• 用户要求改进或更新现有文档
• 用户需要架构文档，包括图表
• 用户请求变更日志或迁移指南

文档工作流

阶段 1：代码库分析

编写任何文档之前，都要彻底了解代码库。

步骤 1.1：项目信息梳理

确定项目的基本信息：

字段	确定方法
语言	检查文件扩展名、package.json、pyproject.toml、go.mod、Cargo.toml 等
框架	查看依赖项，确认是否使用已知框架（React、Django、Express、Spring 等）
构建系统	检查 Makefile、CMakeLists.txt、webpack.config.js、build.gradle 等
包管理器	npm/yarn/pnpm、pip/uv/poetry、cargo、go modules 等
项目结构	梳理目录树，了解项目架构
入口点	查找主文件、CLI 入口点和导出模块
现有文档	检查是否已有 README、docs/、wiki 或内联文档

步骤 1.2：代码结构分析

使用沙盒工具探索代码库：

# Get directory structure
ls /mnt/user-data/uploads/project-dir/

# Read key files
read_file /mnt/user-data/uploads/project-dir/package.json
read_file /mnt/user-data/uploads/project-dir/pyproject.toml

# Search for public API surfaces
grep -r "export " /mnt/user-data/uploads/project-dir/src/
grep -r "def " /mnt/user-data/uploads/project-dir/src/ --include="*.py"
grep -r "func " /mnt/user-data/uploads/project-dir/ --include="*.go"

步骤 1.3：确定文档范围

根据分析结果，确定要编写的文档：

项目规模	建议的文档
单文件 / 脚本	内联注释 + 用法说明标题
小型库	包含 API 参考的 README
中型项目	README + API 文档 + 示例
大型项目	README + 架构文档 + API 文档 + 贡献指南 + 变更日志

阶段 2：文档生成

步骤 2.1：生成 README

每个项目都需要 README。请遵循以下结构：

# Project Name

[One-line project description — what it does and why it matters]

[![Badge](link)](#) [![Badge](link)](#)

## Features

- [Key feature 1 — brief description]
- [Key feature 2 — brief description]
- [Key feature 3 — brief description]

## Quick Start

### Prerequisites

- [Prerequisite 1 with version requirement]
- [Prerequisite 2 with version requirement]

### Installation

[Installation commands with copy-paste-ready code blocks]

### Basic Usage

[Minimal working example that demonstrates core functionality]

## Documentation

- [Link to full API reference if separate]
- [Link to architecture docs if separate]
- [Link to examples directory if applicable]

## API Reference

[Inline API reference for smaller projects OR link to generated docs]

## Configuration

[Environment variables, config files, or runtime options]

## Examples

[2-3 practical examples covering common use cases]

## Development

### Setup

[How to set up a development environment]

### Testing

[How to run tests]

### Building

[How to build the project]

## Contributing

[Contribution guidelines or link to CONTRIBUTING.md]

## License

[License information]

步骤 2.2：生成 API 参考

对于每个公共 API 接口，都要记录以下内容：

函数 / 方法文档：

### `functionName(param1, param2, options?)`

Brief description of what this function does.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | Description of param1 |
| `param2` | `number` | Yes | — | Description of param2 |
| `options` | `Object` | No | `{}` | Configuration options |
| `options.timeout` | `number` | No | `5000` | Timeout in milliseconds |

**Returns:** `Promise<Result>` — Description of return value

**Throws:**
- `ValidationError` — When param1 is empty
- `TimeoutError` — When the operation exceeds the timeout

**Example:**

\`\`\`javascript
const result = await functionName("hello", 42, { timeout: 10000 });
console.log(result.data);
\`\`\`

类文档：

### `ClassName`

Brief description of the class and its purpose.

**Constructor:**

\`\`\`javascript
new ClassName(config)
\`\`\`

| Parameter | Type | Description |
|-----------|------|-------------|
| `config.option1` | `string` | Description |
| `config.option2` | `boolean` | Description |

**Methods:**

- [`method1()`](#method1) — Brief description
- [`method2(param)`](#method2) — Brief description

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `property1` | `string` | Description |
| `property2` | `number` | Read-only. Description |

步骤 2.3：架构文档

对于中大型项目，应包含架构文档：

# Architecture Overview

## System Diagram

[Include a Mermaid diagram showing the high-level architecture]

\`\`\`mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
    C --> E[(Database)]
    D --> E
\`\`\`

## Component Overview

### Component Name
- **Purpose**: What this component does
- **Location**: `src/components/name/`
- **Dependencies**: What it depends on
- **Public API**: Key exports or interfaces

## Data Flow

[Describe how data flows through the system for key operations]

## Design Decisions

### Decision Title
- **Context**: What situation led to this decision
- **Decision**: What was decided
- **Rationale**: Why this approach was chosen
- **Trade-offs**: What was sacrificed

步骤 2.4：内联代码文档

生成符合语言规范的内联文档：

Python（文档字符串 — Google 风格）：

def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
    """Process data from the given file path.

    Reads the input file, applies transformations based on the provided
    options, and returns a structured result object.

    Args:
        input_path: Absolute path to the input data file.
            Supports CSV, JSON, and Parquet formats.
        options: Optional configuration dictionary.
            - "validate" (bool): Enable input validation. Defaults to True.
            - "format" (str): Output format ("json" or "csv"). Defaults to "json".

    Returns:
        A ProcessResult containing the transformed data and metadata.

    Raises:
        FileNotFoundError: If input_path does not exist.
        ValidationError: If validation is enabled and data is malformed.

    Example:
        >>> result = process_data("/data/input.csv", {"validate": True})
        >>> print(result.row_count)
        1500
    """

TypeScript（JSDoc / TSDoc）：

/**
 * Fetches user data from the API and transforms it for display.
 *
 * @param userId - The unique identifier of the user
 * @param options - Configuration options for the fetch operation
 * @param options.includeProfile - Whether to include the full profile. Defaults to `false`.
 * @param options.cache - Cache duration in seconds. Set to `0` to disable.
 * @returns The transformed user data ready for rendering
 * @throws {NotFoundError} When the user ID does not exist
 * @throws {NetworkError} When the API is unreachable
 *
 * @example
 * ```ts
 * const user = await fetchUser("usr_123", { includeProfile: true });
 * console.log(user.displayName);
 * ```
 */

Go（GoDoc）：

// ProcessData reads the input file at the given path, applies the specified
// transformations, and returns the processed result.
//
// The input path must be an absolute path to a CSV or JSON file.
// If options is nil, default options are used.
//
// ProcessData returns an error if the file does not exist or cannot be parsed.
func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {

阶段 3：质量保证

第 3.1 步：文档完整性检查

确认文档涵盖以下内容：

• 它是什么 — 项目描述清晰易懂，新手也能看明白
• 为什么存在 — 它解决的问题和价值主张
• 如何安装 — 可直接复制粘贴的安装命令
• 如何使用 — 至少提供一个可运行的最简示例
• API 范围 — 记录所有公开函数、类和类型
• 配置 — 所有环境变量、配置文件和选项
• 错误处理 — 常见错误及其解决方法
• 贡献指南 — 如何设置开发环境并提交更改

第 3.2 步：质量标准

标准	检查项
准确性	每个代码示例都必须能与所述 API 配合运行
完整性	所有公开 API 均有文档说明
一致性	全文使用相同的格式和结构
时效性	文档与当前代码一致，而非旧版本
易读性	不使用未解释的行话，缩略语首次出现时需给出定义
示例	每个复杂概念至少提供一个实用示例

第 3.3 步：交叉引用验证

确保：

• 提及的所有文件路径都存在于项目中
• 引用的所有函数和类都存在于代码中
• 所有代码示例都使用正确的函数签名
• 版本号与项目的实际版本一致
• 所有链接（内部和外部）均有效

文档风格指南

写作原则

1. 先讲“为什么” — 解释某项功能如何运作之前，先说明它存在的原因
2. 循序渐进地展开 — 从简单内容开始，逐步增加复杂度
3. 用示例说明，而非空谈 — 优先使用代码示例，而不是冗长的解释
4. 使用主动语态 — 写“函数返回 X”，而不是“X 由函数返回”
5. 使用现在时 — 写“服务在端口 8080 上启动”，而不是“服务将在端口 8080 上启动”
6. 使用第二人称 — 写“你可以配置……”，而不是“用户可以配置……”

格式规则

• 使用 ATX 风格标题（#、##、###）
• 使用带语言标识的围栏代码块（```python、```bash）
• 使用表格展示结构化信息（参数、选项、配置）
• 使用提示块呈现重要说明、警告和建议
• 保持行长易读（源文件中的正文建议在约 80–100 个字符处换行）
• 函数名、文件路径、变量名和 CLI 命令使用 代码格式

特定语言的惯例

语言	文档格式	风格指南
Python	Google 风格的文档字符串	PEP 257
TypeScript/JavaScript	TSDoc / JSDoc	TypeDoc 惯例
Go	GoDoc 注释	Effective Go
Rust	Rustdoc（///）	Rust API 指南
Java	Javadoc	Oracle Javadoc 指南
C/C++	Doxygen	Doxygen 手册

输出处理

生成后：

• 将文档文件保存到 /mnt/user-data/outputs/
• 对于多文件文档，保持项目目录结构
• 使用 present_files 工具向用户展示生成的文件
• 邀请用户针对特定章节提出修改，或调整详细程度
• 建议可能有价值的补充文档

说明

• 编写文档前务必分析实际代码，切勿猜测 API 签名或行为
• 如果已有文档，除非用户明确要求重写，否则应保留其结构
• 对于大型代码库，优先记录公开 API 和关键抽象
• 文档应使用与项目现有文档相同的语言；如果没有现有文档，则默认使用英语
• 生成变更日志时，使用 Keep a Changelog 格式
• 此技能可与 deep-research 技能配合使用，用于记录第三方集成或依赖项