name: understand-codebase description: Systematically explore and deeply understand an entire codebase — its structure, architecture, data flow, models, training pipelines, and utilities. Use ONLY when the user manually invokes this skill via /skill-understand-codebase. After exploration, the agent is ready to modify code, build features, explain functionality, or answer questions about the codebase. disable-model-invocation: true
Understand Codebase
当用户手动调用此 skill 时，对当前项目代码库进行全面、系统的探索和理解。探索完成后，准备好回答后续问题或执行代码修改任务。
核心原则
- 并行优先：尽可能同时启动多个探索任务，最大化效率
- 智能适应：根据项目规模自动调整探索深度（小项目全读，大项目分层抽样）
- 自主驱动：不要询问用户"要不要开始探索"，直接开始
- 全面覆盖：不遗漏关键模块，特别关注 ML/DL 项目中的模型、数据、训练、推理等部分
探索流程
Phase 1: 项目概览（并行执行）
同时启动以下所有探索任务：
任务 A — 文档与配置
- 读取
README.md（及任何docs/目录下的关键文档） - 读取包管理文件：
requirements.txt,setup.py,pyproject.toml,package.json,Cargo.toml等 - 读取配置文件：
.env.example,config/,*.yaml,*.toml,*.json（配置类）
任务 B — 目录结构
- 使用 Glob 获取完整文件树，识别顶层目录结构
- 重点关注：
src/,lib/,models/,data/,scripts/,train/,eval/,inference/,utils/,tests/ - 统计代码规模（文件数、主要语言分布）
任务 C — 入口点识别
- 搜索
main,__main__,if __name__,entry,app,cli等关键入口模式 - 搜索
Makefile,Dockerfile,docker-compose, CI/CD 配置（.github/workflows/） - 搜索脚本文件：
scripts/,bin/,*.sh
Phase 2: 深度理解（根据 Phase 1 结果规划）
根据项目类型，智能选择重点探索方向：
ML/DL 项目（检测到模型定义、训练脚本、数据处理时）
- 模型架构：读取模型定义文件，理解网络结构、层定义、前向传播逻辑
- 数据管线：读取 Dataset/DataLoader 定义，理解数据格式、预处理、增强策略
- 训练流程：读取训练脚本，理解优化器、损失函数、学习率调度、训练循环
- 推理/评估：读取推理脚本，理解模型加载、预测流程、评估指标
- 配置管理：理解超参数配置方式（argparse / yaml / hydra 等）
Web/API 项目（检测到路由、中间件、数据库时）
- 路由与 API：读取路由定义，理解端点、请求/响应格式
- 数据层：读取模型/schema 定义，理解数据结构和关系
- 业务逻辑：读取 service/controller 层，理解核心业务流程
- 中间件与工具：理解认证、日志、错误处理等横切关注点
通用项目
- 核心模块：读取
src/或主包下的核心文件 - 公共 API：理解对外暴露的接口和类
- 工具函数：读取
utils/,helpers/,common/等 - 测试：浏览测试文件以理解预期行为
Phase 3: 关联分析
- 理解模块间的依赖关系和调用链
- 识别核心数据流：输入 → 处理 → 输出 的完整路径
- 注意设计模式、抽象层次、扩展点
探索工具使用策略
| 需求 | 推荐工具 | 说明 |
|---|---|---|
| 获取文件列表与目录结构 | Glob | 快速获取文件树 |
| 按文件名模式搜索 | Glob | 如 **/model*.py, **/train*.py |
| 搜索特定代码模式 | Grep | 如类定义、函数签名、import 语句 |
| 理解功能和行为 | SemanticSearch | 如"训练循环在哪里"、"数据如何预处理" |
| 读取文件内容 | Read | 读取关键文件的完整内容 |
| 大规模并行探索 | Task (explore) | 启动多个子代理并行探索不同模块 |
关键搜索模式参考
# 模型相关
**/model*.py, **/network*.py, **/arch*.py, **/backbone*.py
class.*Model, class.*Net, def forward
# 数据相关
**/data*.py, **/dataset*.py, **/loader*.py, **/preprocess*.py
class.*Dataset, DataLoader, transform
# 训练相关
**/train*.py, **/fit*.py, **/run*.py
optimizer, loss, criterion, backward, scheduler, epoch
# 推理相关
**/predict*.py, **/infer*.py, **/eval*.py, **/test*.py
model.eval, torch.no_grad, predict, inference
# 配置相关
**/config*, **/*.yaml, **/*.yml, **/*.toml
argparse, hydra, OmegaConf
规模适应策略
| 项目规模 | 文件数参考 | 策略 |
|---|---|---|
| 小型 | < 50 文件 | 尝试读取所有核心代码文件 |
| 中型 | 50-200 文件 | 读取所有核心模块，抽样读取工具类 |
| 大型 | > 200 文件 | 分层探索：先目录结构 → 入口点 → 核心模块 → 按需深入 |
注意事项
- 不要跳过测试文件，它们是理解预期行为的重要来源
- 关注
__init__.py文件，它们揭示模块的公共 API - 如果发现
CHANGELOG.md或HISTORY.md，浏览最近的变更了解项目演进 - 对于 monorepo，先识别子项目边界，再逐个探索
- 遇到生成的代码（如 protobuf、swagger）时标注但不深入分析