Back to Details

codebase-documenter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Documenter

Codebase Documenter

Generates comprehensive documentation for codebases - architecture, components, data flow, development guidelines.
为代码库生成全面的文档，涵盖架构、组件、数据流和开发指南。

When to Use

使用场景

  • "explain this codebase"
  • "document the architecture"
  • "how does this code work"
  • "create developer documentation"
  • "generate codebase overview"
  • "create onboarding docs"
  • "解释这个代码库"
  • "记录架构信息"
  • "这段代码如何工作"
  • "创建开发者文档"
  • "生成代码库概览"
  • "创建入职文档"

What It Documents

文档涵盖内容

1. Project Overview

1. 项目概述

  • Purpose & vision
  • Target users
  • Key features
  • Technology stack
  • Project status
  • 目标与愿景
  • 目标用户
  • 核心功能
  • 技术栈
  • 项目状态

2. Architecture

2. 架构

  • High-level structure
  • Design patterns
  • Data flow
  • Control flow
  • Diagrams (Mermaid)
  • Architectural decisions
  • 高层结构
  • 设计模式
  • 数据流
  • 控制流
  • 图表（Mermaid）
  • 架构决策

3. Directory Structure

3. 目录结构

  • Organization purpose
  • Naming conventions
  • Entry points
  • Core modules
  • Configuration locations
  • 组织目的
  • 命名规范
  • 入口文件
  • 核心模块
  • 配置文件位置

4. Key Components

4. 关键组件

  • Major modules
  • Classes & functions
  • Responsibilities
  • Interactions
  • Extension points
  • Code examples
  • 主要模块
  • 类与函数
  • 职责说明
  • 交互逻辑
  • 扩展点
  • 代码示例

5. External Integrations

5. 外部集成

  • APIs consumed
  • Databases & schemas
  • Authentication
  • Caching
  • Message queues
  • File storage
  • 调用的API
  • 数据库与Schema
  • 认证机制
  • 缓存策略
  • 消息队列
  • 文件存储

6. Data Models

6. 数据模型

  • Database schema
  • Data structures
  • Validation
  • Migrations
  • Data transformations
  • 数据库Schema
  • 数据结构
  • 校验规则
  • 迁移方案
  • 数据转换

7. Development Setup

7. 开发环境搭建

  • Prerequisites
  • Installation steps
  • Configuration
  • Running the app
  • Testing
  • Debugging
  • Troubleshooting
  • 前置依赖
  • 安装步骤
  • 配置说明
  • 运行应用
  • 测试方法
  • 调试技巧
  • 故障排查

8. Development Guidelines

8. 开发指南

  • Coding conventions
  • Testing approach
  • Error handling
  • Logging
  • Security practices
  • Performance patterns
  • 编码规范
  • 测试方法
  • 错误处理
  • 日志规范
  • 安全实践
  • 性能优化模式

9. Deployment

9. 部署流程

  • Build process
  • Deployment steps
  • Environments
  • Monitoring
  • Rollback procedures
  • 构建过程
  • 部署步骤
  • 环境配置
  • 监控方案
  • 回滚流程

10. Contributing

10. 贡献指南

  • Development workflow
  • Code review guidelines
  • Testing requirements
  • Documentation updates
  • 开发工作流
  • 代码评审规范
  • 测试要求
  • 文档更新规则

Approach

实现流程

  1. Explore using Explore agent (thorough)
  2. Map structure with Glob
  3. Read critical files (README, entry points, core modules)
  4. Identify patterns with Grep (imports, exports)
  5. Trace execution paths
  6. Extract knowledge from docs, comments, tests
  7. Synthesize into cohesive documentation
  1. 探索：使用Explore Agent进行全面探索
  2. 映射结构：借助Glob工具映射目录结构
  3. 读取关键文件：（README、入口文件、核心模块）
  4. 识别模式：使用Grep工具查找模式、导入和导出
  5. 追踪执行路径
  6. 提取知识：从文档、注释、测试用例中提取信息
  7. 整合：整合成连贯的文档

Output

输出结果

Creates markdown documentation:
docs/
├── README.md              # Overview and quick start
├── ARCHITECTURE.md        # System architecture
├── DEVELOPMENT.md         # Development guide
├── API.md                 # API documentation
├── DEPLOYMENT.md          # Deployment guide
└── CONTRIBUTING.md        # Contribution guidelines
Or single comprehensive doc if preferred.
生成Markdown格式的文档：
docs/
├── README.md              # 概览与快速开始
├── ARCHITECTURE.md        # 系统架构
├── DEVELOPMENT.md         # 开发指南
├── API.md                 # API文档
├── DEPLOYMENT.md          # 部署指南
└── CONTRIBUTING.md        # 贡献指南
也可根据需求生成单一的综合文档。

Depth Levels

深度级别

  • Quick: High-level overview (15-30 min)
  • Standard: Comprehensive coverage (30-60 min)
  • Deep: Exhaustive with examples (60+ min)
  • 快速：高层概览（15-30分钟）
  • 标准：全面覆盖（30-60分钟）
  • 深度：详尽说明含示例（60分钟以上）

Visual Elements

可视化元素

  • Mermaid diagrams (architecture, flow charts, sequence)
  • Code examples from codebase
  • Specific file:line references
  • Tables for structured info
  • Lists for guidelines
  • Mermaid图表（架构图、流程图、时序图）
  • 代码库中的代码示例
  • 具体文件:行号引用
  • 结构化信息表格
  • 指南列表

Tools Used

使用工具

  • Task (Explore agent): Codebase exploration
  • Glob: Map directory structure
  • Grep: Find patterns, imports, exports
  • Read: Analyze key files
  • Write: Create documentation
  • Bash: Extract metadata (git log, versions)
  • Task (Explore Agent)：代码库探索
  • Glob：映射目录结构
  • Grep：查找模式、导入和导出
  • Read：分析关键文件
  • Write：创建文档
  • Bash：提取元数据（git日志、版本信息）

Success Criteria

成功标准

  • Complete coverage of all areas
  • Clear explanations with examples
  • Visual diagrams for complex concepts
  • Specific file:line references
  • Actionable setup/development instructions
  • New developer can onboard using only docs
  • Organized, navigable structure
  • Accurate and current information
  • 全面覆盖所有文档领域
  • 清晰的说明及示例
  • 复杂概念配有可视化图表
  • 包含具体文件:行号引用
  • 可操作的搭建/开发指导
  • 新开发者仅通过文档即可完成入职
  • 组织有序、便于导航的结构
  • 准确且最新的信息

Integration

集成能力

  • code-auditor: Includes quality/security context
  • project-bootstrapper: Documents bootstrap decisions
  • visual-html-creator: Create visual diagrams
  • code-auditor：包含质量/安全相关内容
  • project-bootstrapper：记录初始化决策
  • visual-html-creator：创建可视化图表