doc-generator

模式：认知／提示词驱动——没有独立的实用脚本；请在 Agent 上下文中使用。

文档生成技能——根据代码、API 和规范生成全面的文档，包括 API 文档、开发者指南、架构文档和用户手册。 - 生成 API 文档 - 编写开发者指南 - 编写架构文档 - 编写用户手册 - 生成 OpenAPI/Swagger 规范 - 更新现有文档

步骤 1：确定文档类型

确定文档类型：

• API 文档：端点参考
• 开发者指南：设置和使用方法
• 架构文档：系统概述
• 用户手册：功能指南

步骤 2：提取信息

收集文档内容：

• 阅读代码和注释
• 分析 API 端点
• 提取示例
• 了解架构

步骤 3：生成文档

创建文档：

• 遵循文档模板
• 包含示例
• 添加故障排除内容
• 创建清晰的结构

步骤 4：验证文档

验证质量：

• 检查完整性
• 确认示例可运行
• 确保内容清晰
• 验证链接 </execution_process>

**与 Technical Writer Agent 集成**： - 使用此技能生成文档 - 确保文档质量 - 验证完整性

与 Developer Agent 集成：

• 生成 API 文档
• 创建内联文档
• 随代码变更更新文档

<best_practices>

1. 从代码中提取：以代码为事实依据
2. 包含示例：提供可运行的示例
3. 保持更新：确保文档与代码同步
4. 结构清晰：按逻辑组织
5. 以用户为中心：面向用户而非系统编写 </best_practices>

**API 文档**

# Users API

## Endpoints

### GET /api/users

List all users with pagination.

**Query Parameters:**

- `page` (number): Page number (default: 1)
- `limit` (number): Items per page (default: 10)

**Response:**

```json
{
  "data": [
    {
      "id": "uuid",
      "email": "[email protected]",
      "name": "User Name"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100
  }
}
```

示例：

curl -X GET "http://localhost:3000/api/users?page=1&limit=10"

</formatting_example>

<formatting_example>
**Developer Guide**

```markdown
# Developer Guide

## Getting Started

### Prerequisites
- Node.js 18+
- pnpm 8+

### Installation
```bash
pnpm install

开发

pnpm dev

架构

[架构概述]

开发工作流

[开发流程]

</formatting_example>
</examples>

<examples>
<usage_example>
**Example Commands**:

生成 API 文档

为 app/api/users 生成 API 文档

生成开发者指南

为此项目生成开发者指南

生成架构文档

生成架构文档

生成 OpenAPI 规范

根据 API 路由生成 OpenAPI 规范

</usage_example>
</examples>

## Iron Laws

1. **ALWAYS** extract documentation from code as the source of truth — never write documentation that describes how you wish the code worked rather than how it actually works.
2. **NEVER** publish documentation with non-runnable examples — every code example must be copy-paste ready and verified to work before the documentation is written.
3. **ALWAYS** structure documentation with the progressive disclosure pattern (Setup → Quick Start → Reference → Troubleshooting) — readers need orientation before details.
4. **NEVER** document internal implementation details that consumers don't need to know — documentation of private internals creates false contracts and maintenance burden.
5. **ALWAYS** regenerate documentation when the code it describes changes — stale documentation is worse than no documentation because it actively misleads users.

## Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| No working code examples | Users can't understand how to use the API without runnable examples | Include minimal copy-paste examples verified to work for every public API |
| Aspirational documentation (describes intended behavior) | Creates false contracts; users file bugs when docs don't match code | Read the actual implementation first; document only observed behavior |
| Documenting private/internal APIs | Creates implicit dependencies; refactoring breaks "documented" behavior | Only document public APIs; mark internal functions with `@internal` if needed |
| Monolithic reference dumps without Quick Start | Users abandon before finding what they need | Always include a Quick Start section with the simplest possible working example |
| Documentation in a separate PR from code change | Docs drift immediately; often abandoned | Require documentation updates in the same PR as API changes |

## Memory Protocol (MANDATORY)

**Before starting:**
Read `.claude/context/memory/learnings.md`

**After completing:**
- New pattern -> `.claude/context/memory/learnings.md`
- Issue found -> `.claude/context/memory/issues.md`
- Decision made -> `.claude/context/memory/decisions.md`

> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.