codebase-summary

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Summary

代码库总结

Generate comprehensive codebase documentation optimized for AI assistants and developers.

生成针对AI助手和开发者优化的全面代码库文档。

Parameters

参数

Gather all parameters upfront in a single prompt:

Parameter	Default	Description
`codebase_path`	Current directory	Path to analyze
`output_dir`	`.sop/summary`	Documentation output directory
`consolidate`	`false`	Create consolidated file at codebase root
`consolidate_target`	`AGENTS.md`	Target: AGENTS.md, README.md, or CONTRIBUTING.md
`check_consistency`	`true`	Check for cross-document inconsistencies
`check_completeness`	`true`	Identify documentation gaps
`update_mode`	`false`	Update existing docs based on git changes

在单个提示中预先收集所有参数：

参数	默认值	描述
`codebase_path`	当前目录	待分析的路径
`output_dir`	`.sop/summary`	文档输出目录
`consolidate`	`false`	在代码库根目录创建合并文件
`consolidate_target`	`AGENTS.md`	目标文件：AGENTS.md、README.md或CONTRIBUTING.md
`check_consistency`	`true`	检查跨文档的一致性
`check_completeness`	`true`	识别文档空白
`update_mode`	`false`	基于git变更更新现有文档

Workflow

工作流

Step 1: Setup

步骤1：准备

Validate
```
codebase_path
```
exists
Create
```
output_dir
```
if needed
If
```
update_mode
```
and
```
index.md
```
exists:
- Run
```
git log --oneline -20
```
  to identify recent changes
- Focus analysis on modified components

验证
```
codebase_path
```
是否存在
若需要则创建
```
output_dir
```
若开启
```
update_mode
```
且
```
index.md
```
已存在：
- 运行
```
git log --oneline -20
```
  识别近期变更
- 重点分析已修改的组件

Step 2: Analyze Structure

步骤2：分析结构

Run the structure analyzer:

bash

python {baseDir}/scripts/analyze_structure.py "{codebase_path}" --depth 4 --output "{output_dir}/codebase_info.md"

Run the dependency extractor:

bash

python {baseDir}/scripts/extract_dependencies.py "{codebase_path}" --output "{output_dir}/dependencies.md"

Then manually analyze:

Identify packages, modules, major components
Map architectural patterns (MVC, microservices, etc.)
Find key interfaces, APIs, entry points

运行结构分析器：

bash

python {baseDir}/scripts/analyze_structure.py "{codebase_path}" --depth 4 --output "{output_dir}/codebase_info.md"

运行依赖提取器：

bash

python {baseDir}/scripts/extract_dependencies.py "{codebase_path}" --output "{output_dir}/dependencies.md"

然后进行人工分析：

识别包、模块和主要组件
梳理架构模式（MVC、微服务等）
定位关键接口、API和入口点

Step 3: Generate Documentation

步骤3：生成文档

Create these files in

{output_dir}/

index.md - Primary AI context file:

AI instructions for using the documentation
Quick reference table mapping questions to files
Table of contents with summaries for each file
Brief codebase overview

architecture.md:

System architecture with Mermaid
```
graph
```
diagram
Layer descriptions
Design patterns used
Key design decisions with rationale

components.md:

Component overview with Mermaid
```
classDiagram
```
Per-component: purpose, location, key files, dependencies, interface

interfaces.md:

API endpoints with request/response formats
Internal interfaces and implementations
Error codes and handling

data_models.md:

ER diagram with Mermaid
```
erDiagram
```
Per-model: table, fields, indexes, relationships

workflows.md:

Key processes with Mermaid
```
sequenceDiagram
```
Step-by-step breakdowns
Error handling

See

{baseDir}/references/documentation-templates.md

for templates.

在

{output_dir}/

中创建以下文件：

index.md - 核心AI上下文文件：

关于使用该文档的AI指令
问题与文件映射的快速参考表
含各文件摘要的目录
代码库简要概述

architecture.md：

包含Mermaid
```
graph
```
图的系统架构
层级说明
使用的设计模式
关键设计决策及理由

components.md：

包含Mermaid
```
classDiagram
```
的组件概述
各组件详情：用途、位置、关键文件、依赖项、接口

interfaces.md：

含请求/响应格式的API端点
内部接口与实现
错误码及处理方式

data_models.md：

包含Mermaid
```
erDiagram
```
的ER图
各模型详情：表、字段、索引、关系

workflows.md：

包含Mermaid
```
sequenceDiagram
```
的关键流程
分步拆解
错误处理

模板可参考

{baseDir}/references/documentation-templates.md

。

Step 4: Review

步骤4：审核

check_consistency

Verify terminology consistency across documents
Check cross-references are valid

check_completeness

Identify undocumented components
Note gaps from language/framework limitations

Save findings to

{output_dir}/review_notes.md

若开启

check_consistency

：

验证跨文档的术语一致性
检查交叉引用是否有效

若开启

check_completeness

：

识别未文档化的组件
记录因语言/框架限制导致的空白

将审核结果保存至

{output_dir}/review_notes.md

。

Step 5: Consolidate (if enabled)

步骤5：合并（若启用）

consolidate

true

Create file at codebase root (not in output_dir)
Use
```
consolidate_target
```
as filename
Tailor content to target:

Target	Focus
AGENTS.md	AI context, directory structure, coding patterns, testing
README.md	Project overview, installation, usage, getting started
CONTRIBUTING.md	Dev setup, coding standards, contribution workflow

Default AGENTS.md prompt: Focus on information NOT in README.md or CONTRIBUTING.md—file purposes, directory structure, coding patterns, testing instructions, package guidance.

若

consolidate

设为

true

：

在代码库根目录创建文件（不在output_dir中）
使用
```
consolidate_target
```
作为文件名
根据目标调整内容：

目标文件	重点内容
AGENTS.md	AI上下文、目录结构、编码模式、测试
README.md	项目概述、安装、使用、快速入门
CONTRIBUTING.md	开发环境搭建、编码规范、贡献流程

默认AGENTS.md提示：重点涵盖README.md或CONTRIBUTING.md中未包含的信息——文件用途、目录结构、编码模式、测试说明、包指南。

Step 6: Summary

步骤6：总结

Report:

What was documented
Next steps for using documentation
How to add index.md to AI assistant context
If
```
update_mode
```
: summarize detected changes

生成报告：

已完成文档的内容
使用文档的后续步骤
如何将index.md添加至AI助手上下文
若开启
```
update_mode
```
：总结检测到的变更

Output Structure

输出结构

{consolidate_target}           # At codebase root if consolidate=true
{output_dir}/
├── index.md                   # Primary AI context (read this first)
├── codebase_info.md          # Structure analysis output
├── architecture.md           # System architecture
├── components.md             # Component details
├── interfaces.md             # APIs and interfaces
├── data_models.md            # Data models
├── workflows.md              # Key workflows
├── dependencies.md           # Dependencies output
└── review_notes.md           # Review findings

{consolidate_target}           # 若consolidate=true则位于代码库根目录
{output_dir}/
├── index.md                   # 核心AI上下文文件（优先阅读）
├── codebase_info.md          # 结构分析输出
├── architecture.md           # 系统架构
├── components.md             # 组件详情
├── interfaces.md             # API与接口
├── data_models.md            # 数据模型
├── workflows.md              # 关键工作流
├── dependencies.md           # 依赖项输出
└── review_notes.md           # 审核结果

Progress Indicators

进度指示器

Provide updates:

Setting up...
✅ Created {output_dir}

Analyzing structure...
✅ Found X packages across Y languages
✅ Identified Z components

Generating documentation...
✅ Created index.md
✅ Generated architecture.md, components.md...

Reviewing...
✅ Consistency check complete
✅ Found N gaps documented in review_notes.md

Done!
✅ Documentation at {output_dir}
✅ Primary context file: {output_dir}/index.md

提供以下更新：

准备中...
✅ 已创建 {output_dir}

分析结构中...
✅ 发现X个包，涉及Y种语言
✅ 识别出Z个组件

生成文档中...
✅ 已创建index.md
✅ 已生成architecture.md、components.md...

审核中...
✅ 一致性检查完成
✅ 发现N处空白，已记录在review_notes.md中

完成！
✅ 文档位于 {output_dir}
✅ 核心上下文文件：{output_dir}/index.md

Resources

资源

Scripts:

{baseDir}/scripts/analyze_structure.py

{baseDir}/scripts/extract_dependencies.py

Templates:

{baseDir}/references/documentation-templates.md

脚本：

{baseDir}/scripts/analyze_structure.py

、

{baseDir}/scripts/extract_dependencies.py

模板：

{baseDir}/references/documentation-templates.md