codebase-documenter

代码库文档编写器

为任何代码库创建全面、适合初学者的文档。

适用场景

适用于：

• 编写或更新 README 文件
• 创建架构文档
• 添加有意义的代码注释
• 编写 API 和端点文档
• 创建入门指南
• 说明项目结构

不适用于：

• 代码审查 → 使用 generic-code-reviewer
• UX 设计决策 → 使用 generic-ux-designer
• 添加代码功能 → 使用 generic-feature-developer

核心原则

1. 从“为什么”开始——先说明目的，再介绍实现
2. 循序渐进地展开——由浅入深
3. 提供背景信息——说明代码为何存在，而不只是它的作用
4. 提供示例——为每个概念提供具体用法
5. 假设读者没有任何先验知识——定义术语，避免使用行话
6. 使用可视化辅助——图表、文件树、流程图
7. 快速见效——让读者在 5 分钟内运行起来

文档编写工作流

1. 分析——入口点、依赖项、核心概念、配置
2. 选择类型——README → 架构 → API → 注释
3. 生成——使用模板，并根据项目进行定制
4. 验证——以初学者的视角阅读，并对照代码检查示例

文档类型

README（项目入口）

# Project Name

## What This Does

[1-2 sentence explanation]

## Quick Start

[< 5 minute setup]

## Project Structure

[Visual file tree]

## Key Concepts

[Core abstractions]

## Common Tasks

[Step-by-step guides]

架构文档

# Architecture Overview

## System Design

[High-level diagram]

## Data Flow

[How data moves through system]

## Key Design Decisions

[Why certain choices were made]

## Extension Points

[Where to add new features]

代码注释

// ✅ GOOD - Explains WHY and context
// IndexedDB quota check: Prevents silent failures when storage is full.
// Without this, writes fail with cryptic QuotaExceededError.
if (quota.percentUsed > 80) showStorageWarning();

// ❌ BAD - Just repeats what code does
// Check if quota is over 80

API 文档

## Endpoint: POST /api/resource

### What It Does

[Plain-English purpose]

### Request/Response

[JSON examples]

### Common Errors

[Error codes and meanings]

可视化模式

文件树

project/
├── src/                    # Source code
│   ├── components/        # Reusable UI
│   ├── services/          # Business logic
│   └── types/             # TypeScript types
├── tests/                 # Test files
└── package.json           # Dependencies

数据流

User Request Flow:
1. User submits → 2. Validation → 3. API → 4. Database → 5. Response

[1] components/Form.tsx
    ↓ validates
[2] services/validation.ts
    ↓ calls API
[3] services/api.ts
    ↓ queries
[4] Database
    ↓ returns
[5] Form.tsx (updates UI)

设计决策（ADR）

## Why We Use [Technology]

**Decision:** [What we chose]
**Context:** [Why we needed to choose]
**Reasoning:** [Why this option]
**Trade-offs:** [What we gave up]

文档质量检查清单

发布前

• 快速入门可在不到 5 分钟内完成
• 代码示例可直接复制粘贴
• 文件路径准确无误
• 链接有效
• 已定义行话
• 为复杂流程配有图表

应避免的常见错误

• 假设读者了解该代码库
• 代码示例已过时
• 缺少先决条件
• 复杂系统没有可视化辅助
• 只解释“是什么”，不解释“为什么”

验证工作流

编写文档后：

1. 以全新视角测试——假装自己从未见过该代码库，并据此阅读
2. 检查示例——对照当前代码、API 及其使用的路径逐一检查示例
3. 检查链接——确保所有内部和外部链接均可访问
4. 初学者评审——新开发者能否看懂？
5. 更新检查——文档是否反映了当前代码？

另请参阅

• 代码审查标准——文档质量
• 项目 CLAUDE.md——文档规则