| name | codebase-documenter |
| description | 代码库文档生成器 - 适用于为代码库编写文档，包括README文件、架构文档、代码注释和API文档。当用户请求帮助记录代码、创建入门指南、解释项目结构或使代码库对新开发者更友好时使用此技能。该技能提供模板、最佳实践和结构化方法来创建清晰、适合初学者的文档。 |
代码库文档生成器
概述
本技能用于为代码库创建全面的、对初学者友好的文档。它提供了结构化的模板和最佳实践，用于编写 README、架构指南、代码注释和 API 文档，帮助新用户快速理解项目并为项目做出贡献。
面向初学者的文档核心原则
在为新用户记录代码时，请遵循以下基本原则：
- 从“为什么”开始 - 在深入实现细节之前解释目的
- 使用渐进式披露 - 从简单到复杂分层呈现信息
- 提供上下文 - 不仅解释代码做什么，还要解释为什么存在
- 包含示例 - 为每个概念展示具体的使用示例
- 假设没有先验知识 - 定义术语，尽可能避免行话
- 视觉辅助 - 使用图表、流程图和文件树结构
- 快速成功 - 帮助用户在 5 分钟内运行起来
文档类型及使用时机
1. README 文档
何时创建： 用于项目根目录、主要功能模块或独立组件。
遵循的结构：
# 项目名称
## 这是什么
[1-2 句话的通俗解释]
## 快速开始
[让用户在 < 5 分钟内运行项目]
## 项目结构
[带有解释的可视化文件树]
## 核心概念
[用户需要理解的核心概念]
## 常见任务
[常见操作的逐步指南]
## 故障排除
[常见问题和解决方案]
最佳实践：
- 以项目的价值主张开头
- 包含实际可行的设置说明（测试它们！）
- 提供项目结构的可视化概述
- 链接到更深入的文档以获取高级主题
- 根 README 专注于入门
2. 架构文档
何时创建： 用于具有多个模块、复杂数据流或非显而易见的设计决策的项目。
遵循的结构：
# 架构概述
## 系统设计
[高级图表和解释]
## 目录结构
[每个目录用途的详细说明]
## 数据流
[数据如何在系统中流动]
## 关键设计决策
[为什么做出某些架构选择]
## 模块依赖
[不同部分如何交互]
## 扩展点
[在哪里以及如何添加新功能]
最佳实践：
- 使用图表展示系统组件和关系
- 解释架构决策背后的“为什么”
- 记录正常路径和错误处理
- 标识模块之间的边界
- 包含带注释的可视化文件树结构
3. 代码注释
何时创建： 用于复杂逻辑、不明显的算法或需要上下文的代码。
注释模式：
函数/方法文档：
复杂逻辑文档：
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 - 用于项目 READMEassets/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 - 如何创建有效的图表和文件树
在以下情况下加载这些参考：
- 为复杂企业级代码库创建文档时
- 处理多个利益相关者需求时
- 需要高级文档模式时
- 在大型项目中标准化文档时
常见模式
创建文件树结构
文件树帮助新用户理解项目组织：
project-root/
├── 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 偏好。
**推理：**
- 上下文 API 会导致这么多组件不必要的重新渲染
- Redux DevTools 帮助调试复杂的状态变化
- 团队具有现有的 Redux 专业知识
**权衡：**
- 更多的样板代码
- 新学习曲线更陡
- 值得：性能、调试、团队熟悉度
输出指南
在生成文档时：
- 为目标受众编写 - 根据文档是面向初学者、中级还是高级用户来调整复杂度
- 使用一致的格式 - 遵循 markdown 惯例，一致的标题层次结构
- 提供可用的示例 - 测试所有代码片段和命令
- 在文档之间链接 - 创建文档导航结构
- 保持可维护性 - 文档应易于在代码变更时更新
- 添加日期和版本 - 注意文档的最后更新时间
快速参考
生成 README 的命令：
“为这个项目创建一个 README 文件，帮助新开发者入门”
记录架构的命令：
“记录此代码库的架构，解释不同模块如何交互”
添加代码注释的命令：
“为此文件添加解释性注释，帮助新开发者理解逻辑”
记录 API 的命令：
“为此文件中的所有端点创建 API 文档”
