⚡

代码库文档编写器 codebase-documenter

代码库文档编写器是一个专门用于创建高质量技术文档的技能工具，提供代码库文档化、README编写、架构说明、API文档生成和代码注释规范等功能。它包含结构化模板、最佳实践指南和文档工作流程，帮助开发团队创建清晰、易维护、对初学者友好的技术文档，提升代码可读性和团队协作效率。

架构设计 0 次安装 0 次浏览 更新于 2/28/2026

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

代码库文档编写器

概述

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

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

为新用户记录代码时，请遵循以下基本原则：

  1. 从“为什么”开始 - 在深入实现细节之前解释目的
  2. 使用渐进式披露 - 从简单到复杂分层呈现信息
  3. 提供上下文 - 不仅解释代码做什么，还要解释它为什么存在
  4. 包含示例 - 为每个概念展示具体使用示例
  5. 假设没有先验知识 - 尽可能定义术语并避免行话
  6. 视觉辅助 - 使用图表、流程图和文件树结构
  7. 快速成功 - 帮助用户在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：分析代码库

编写文档前：

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

步骤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文档

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

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

步骤4：审查清晰度

最终确定文档前：

  1. 以初学者身份阅读 - 没有项目上下文是否合理？
  2. 检查完整性 - 解释中是否存在空白？
  3. 验证示例 - 代码示例是否实际有效？
  4. 测试说明 - 有人能遵循设置步骤吗？
  5. 改进结构 - 信息是否易于查找？

文档模板

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

可用模板

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

使用模板

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

最佳实践参考

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

  • 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专业知识

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

输出指南

生成文档时：

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

快速参考

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

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

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

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