name: codebase-documenter description: 该技能用于编写代码库的文档，包括README文件、架构文档、代码注释和API文档。当用户请求帮助记录代码、创建入门指南、解释项目结构或使代码库对新开发人员更易访问时，请使用此技能。该技能提供模板、最佳实践和结构化方法，用于创建清晰、对初学者友好的文档。

代码库文档编写器

概述

此技能能够为代码库创建全面、对初学者友好的文档。它提供结构化模板和最佳实践，用于编写README、架构指南、代码注释和API文档，帮助新用户快速理解项目并做出贡献。

对初学者友好文档的核心原则

为新手编写代码文档时，请遵循以下基本原则：

从“为什么”开始 - 在深入实现细节之前，先解释目的
使用渐进式披露 - 从简单到复杂分层呈现信息
提供上下文 - 不仅要解释代码做什么，还要解释它为什么存在
包含示例 - 为每个概念展示具体的使用示例
假设没有先验知识 - 尽可能定义术语并避免行话
视觉辅助 - 使用图表、流程图和文件树结构
快速见效 - 帮助用户在5分钟内运行起某些东西

文档类型及使用时机

1. README 文档

何时创建： 用于项目根目录、主要功能模块或独立组件。

遵循的结构：

# 项目名称

## 项目功能
[1-2句通俗易懂的解释]

## 快速开始
[让用户在<5分钟内运行项目]

## 项目结构
[带解释的可视化文件树]

## 核心概念
[用户需要理解的核心概念]

## 常见任务
[高频操作的逐步指南]

## 故障排除
[常见问题及解决方案]

最佳实践：

以项目的价值主张开头
包含实际有效的设置说明（测试它们！）
提供项目结构的可视化概览
链接到高级主题的深入文档
保持根README专注于入门

2. 架构文档

何时创建： 用于具有多个模块、复杂数据流或不明显设计决策的项目。

遵循的结构：

# 架构概述

## 系统设计
[高层级图表及解释]

## 目录结构
[每个目录用途的详细分解]

## 数据流
[数据如何在系统中流动]

## 关键设计决策
[为什么做出某些架构选择]

## 模块依赖
[不同部分如何交互]

## 扩展点
[在何处以及如何添加新功能]

最佳实践：

使用图表展示系统组件和关系
解释架构决策背后的“原因”
记录正常路径和错误处理
标识模块间的边界
包含带注释的可视化文件树结构

3. 代码注释

何时创建： 用于复杂逻辑、非显而易见的算法或需要上下文的代码。

注释模式：

函数/方法文档：

/**
 * 计算部分计费周期的按比例订阅费用。
 *
 * 存在原因：用户可以在月中订阅，因此我们只需向他们收取当前计费周期剩余天数的费用。
 *
 * @param {number} fullPrice - 正常的月度订阅价格
 * @param {Date} startDate - 用户订阅开始日期
 * @param {Date} periodEnd - 当前计费周期结束日期
 * @returns {number} 按比例计算的应收费金额
 *
 * @example
 * // 用户于1月15日订阅，周期于1月31日结束
 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
 * // 返回：16.13 (31天中的17天)
 */

复杂逻辑文档：

# 存在此检查的原因：API为已删除用户返回null，
# 但为从未设置姓名的用户返回空字符串。我们需要
# 为审计日志区分这些情况。
if user_name is None:
    # 用户已被删除 - 将此记录为安全事件
    log_deletion_event(user_id)
elif user_name == "":
    # 用户从未完成入职 - 可以安全跳过
    continue

最佳实践：

解释“为什么”而不是“是什么” - 代码本身显示了它做什么
记录边缘情况和业务逻辑
为复杂函数添加示例
解释非自解释的参数
注明任何陷阱或反直觉的行为

4. API 文档

何时创建： 用于任何HTTP端点、SDK方法或公共接口。

遵循的结构：

## 端点名称

### 功能
[端点用途的通俗易懂解释]

### 端点
`POST /api/v1/resource`

### 认证
[需要什么认证以及如何提供]

### 请求格式
[JSON模式或示例请求]

### 响应格式
[JSON模式或示例响应]

### 使用示例
[使用curl/代码的具体示例]

### 常见错误
[错误代码及其含义]

### 相关端点
[链接到相关操作]

最佳实践：

提供可运行的curl示例
展示成功和错误响应
清晰地解释认证
记录速率限制和约束
包含常见问题的故障排除

文档工作流程

步骤 1：分析代码库

编写文档前：

识别入口点 - 主文件、索引文件、应用初始化
映射依赖关系 - 模块之间如何关联
找出核心概念 - 用户需要理解的关键抽象
定位配置 - 环境设置、配置文件
审查现有文档 - 在现有基础上构建，不要重复

步骤 2：选择文档类型

基于用户请求和代码库分析：

新项目或缺少README → 从README文档开始
复杂架构或多个模块 → 创建架构文档
令人困惑的代码部分 → 添加内联代码注释
HTTP/API端点 → 编写API文档
需要多种类型 → 按顺序处理：README → 架构 → API → 注释

步骤 3：生成文档

使用 assets/templates/ 中的模板作为起点：

assets/templates/README.template.md - 用于项目README
assets/templates/ARCHITECTURE.template.md - 用于架构文档
assets/templates/API.template.md - 用于API文档

根据特定代码库自定义模板：

填写项目特定信息 - 用实际内容替换占位符
添加具体示例 - 使用项目中的真实代码
包含视觉辅助 - 创建文件树、图表、流程图
测试说明 - 验证设置步骤确实有效
链接相关文档 - 将文档片段连接在一起

步骤 4：审查清晰度

最终确定文档前：

以初学者身份阅读 - 没有项目上下文时是否清晰？
检查完整性 - 解释中是否存在空白？
验证示例 - 代码示例是否真的有效？
测试说明 - 是否有人能遵循设置步骤？
改进结构 - 信息是否易于查找？

文档模板

此技能在 assets/templates/ 中包含多个提供起始结构的模板：

可用模板

README.template.md - 包含快速开始、项目结构和常见任务部分的综合README结构
ARCHITECTURE.template.md - 包含系统设计、数据流和设计决策的架构文档模板
API.template.md - 包含请求/响应格式和示例的API端点文档
CODE_COMMENTS.template.md - 有效内联文档的示例和模式

使用模板

从 assets/templates/ 读取相应模板
为特定项目自定义 - 用实际信息替换占位符
添加项目特定部分 - 根据需要扩展模板
包含真实示例 - 使用代码库中的实际代码
删除不相关的部分 - 删除不适用的部分

最佳实践参考

有关详细的文档最佳实践、风格指南和高级模式，请参考：

references/documentation_guidelines.md - 综合风格指南和最佳实践
references/visual_aids_guide.md - 如何创建有效的图表和文件树

在以下情况下加载这些参考：

为复杂的企业代码库创建文档
处理多个利益相关者的需求
需要高级文档模式
标准化大型项目的文档

常见模式

创建文件树结构

文件树帮助新用户理解项目组织：

项目根目录/
├── src/                    # 源代码
│   ├── components/        # 可复用的UI组件
│   ├── pages/             # 页面级组件（路由）
│   ├── services/          # 业务逻辑和API调用
│   ├── utils/             # 辅助函数
│   └── types/             # TypeScript类型定义
├── public/                # 静态资源（图片、字体）
├── tests/                 # 测试文件（镜像src结构）
└── package.json           # 依赖项和脚本

解释复杂数据流

使用带图表的编号步骤：

用户请求流：
1. 用户提交表单 → 2. 验证 → 3. API调用 → 4. 数据库 → 5. 响应

[1] components/UserForm.tsx
    ↓ 验证输入
[2] services/validation.ts
    ↓ 发送到API
[3] services/api.ts
    ↓ 查询数据库
[4] 数据库 (PostgreSQL)
    ↓ 返回数据
[5] components/UserForm.tsx (更新UI)

记录设计决策

捕捉架构选择背后的“原因”：

## 为什么我们使用Redux

**决策：** 使用Redux而非Context API进行状态管理

**背景：** 我们的应用有50多个组件需要访问用户认证状态、购物车和UI偏好设置。

**推理：**
- 对于这么多组件，Context API会导致不必要的重新渲染
- Redux DevTools有助于调试复杂的状态变化
- 团队已有Redux专业知识

**权衡：**
- 更多的样板代码
- 新开发人员学习曲线更陡峭
- 值得：性能、调试、团队熟悉度

输出指南

生成文档时：

为目标受众编写 - 根据文档是为初学者、中级还是高级用户调整复杂度
使用一致的格式 - 遵循Markdown约定，一致的标题层次结构
提供可运行的示例 - 测试所有代码片段和命令
在文档之间链接 - 创建文档导航结构
保持可维护性 - 文档应易于随着代码更改而更新
添加日期和版本 - 注明文档最后更新时间

快速参考

生成README的命令： “为此项目创建一个README文件，帮助新开发人员入门”

记录架构的命令： “记录此代码库的架构，解释不同模块如何交互”

添加代码注释的命令： “向此文件添加解释性注释，帮助新开发人员理解逻辑”

记录API的命令： “为此文件中的所有端点创建API文档”