codebase-documenter

用途

Codebase Documenter 用于为任意代码库创建全面、对新手友好的文档。它适合在需要记录代码、或让新开发者更容易理解项目时使用。

具体适用场景包括：

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

不适用场景：

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

核心原则

从“为什么”开始：在讲实现之前先解释目的。
渐进式披露：从简单到复杂。
提供上下文：说明代码为何存在，而不只是它做了什么。
包含示例：为每个概念提供具体用法。
假设无先验知识：定义术语，避免行话。
可视化辅助：使用图表、文件树、流程图。
快速见效：让读者在 5 分钟内跑起来。

文档工作流

分析：入口点、依赖、核心概念、配置。
选择类型：README → 架构 → API → 注释。
生成：使用模板，针对项目定制。
验证：以初学者视角阅读，通过阅读代码核对示例。

文档类型

README（项目入口）

模板结构包含：项目名称、功能说明（1-2 句）、快速开始（少于 5 分钟的设置）、项目结构（可视化文件树）、关键概念（核心抽象）、常见任务（分步指南）。

架构文档

模板结构包含：架构概览、系统设计（高层图）、数据流（数据如何在系统中移动）、关键设计决策（为何做出某些选择）、扩展点（在哪里添加新功能）。

代码注释

好的注释解释“为什么”和上下文，例如：

// ✅ 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 文档

模板结构包含：端点（如 POST /api/resource）、功能说明（平实语言的目的）、请求/响应（JSON 示例）、常见错误（错误码与含义）。

可视化模式

文件树

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 分钟内完成
[ ] 代码示例可复制粘贴
[ ] 文件路径准确
[ ] 链接有效
[ ] 行话已定义
[ ] 复杂流程配有图表

应避免的常见错误：

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

验证工作流

编写文档后：

新鲜视角测试：像从未见过该代码库一样阅读。
检查示例：对照当前代码、API 和路径阅读每个示例。
检查链接：所有内部/外部链接均可解析。
初学者评审：新开发者能否理解？
更新检查：是否反映当前代码？

参见

Code Review Standards - 文档质量
项目 CLAUDE.md - 文档规则