---
title: 理解现有代码
description: 使用 Verdent 探索、分析和理解现有代码库
---
Verdent for VS Code 通过自然语言提问和自动化探索，帮助你理解陌生的代码库。内置的 Explorer 子智能体能够快速查找文件、搜索代码模式并回答架构相关问题，而不会消耗你的主上下文窗口。
### 你将学到
- 使用 Explorer 子智能体探索陌生的代码库
- 询问代码结构和实现相关的问题
- 获取函数、类和模块的详细解释
- 从现有代码生成文档
- 理解项目架构和数据流
- 高效地帮助新团队成员上手
### 前置条件
在使用 Verdent 理解代码之前：
- 已安装 Verdent 扩展的 Visual Studio Code
- 在 VS Code 中打开了一个代码库或项目工作区
- 拥有积分可用的有效 Verdent 套餐
---
## 探索陌生的代码库
当你询问代码库结构相关的问题或请求文件搜索时，Verdent 会自动委派给 **Explorer 子智能体**（`@Explorer`），这是一个针对快速代码库探索优化的 token 高效型专家。
Explorer 子智能体能够快速：
- 查找匹配模式或名称的文件
- 搜索特定关键字或函数的代码
- 回答关于代码库的架构问题
- 定位功能的实现位置
**探索性问题示例：**
```
What is the structure of this project?
```
```
Where is user authentication handled?
```
```
Find all API endpoint definitions
```
```
Show me where database queries are defined
```
Explorer 在后台高效工作，提供快速答案的同时不会消耗你的主上下文窗口。Verdent 会以相关的文件路径和代码片段呈现结果。
**面向复杂任务的并行探索：**
对于复杂的探索任务，多个 Explorer 智能体可以并行运行以节省时间，每个智能体同时调查代码库的不同方面。随后 Verdent 会将这些发现综合成一份连贯的总结。
**示例：**
```
Use the Explorer agent to find all places where we manually validate email addresses
```
这确保 Verdent 能够系统地发现每一处位置，不会遗漏代码库中的任何实例。
---
## 询问你的代码相关问题
Verdent 使用自然语言回答几乎任何关于你代码库的问题。AI 会理解上下文，并提供详细的解释、分析和洞见。
询问特定功能的工作方式：
```
Explain how authentication works in this project
```
```
What does the calculateTotal function do?
```
```
How are API requests handled?
```
Verdent 会分析相关代码，追踪执行流程，并结合具体文件和行号解释其实现。
理解应用程序的全局视图：
```
What is the overall architecture of this application?
```
```
How do the components communicate with each other?
```
```
What design patterns are used in this codebase?
```
Verdent 会检查你的项目结构，识别模式，并解释架构决策。
深入了解技术决策：
```
Why do you think Redux was chosen instead of Context API for state management?
```
```
What would happen if I changed the API timeout from 30s to 60s?
```
```
Is this validateUserInput function redundant?
```
Verdent 会分析代码上下文，并基于你项目的模式和行业最佳实践提供有理有据的解释。
查找特定功能或依赖项：
```
Where is user data validated?
```
```
Show me all database queries in the project
```
```
What dependencies does this project have?
```
Explorer 子智能体使用 grep（内容搜索）和 glob（文件模式匹配）等工具进行高效搜索，返回相关结果而不消耗主上下文。
理解算法和模式：
```
How does the quicksort algorithm work in the sortItems function?
```
```
What are the best practices for error handling in React components?
```
```
Explain the Observer pattern implementation in the EventEmitter class
```
Verdent 会提供清晰的解释，并引用你代码库中的具体实现。
---
## 解释函数和类
Verdent 通过分析特定函数或类的实现、参数、返回值以及在整个代码库中的使用情况，提供详细的解释。
**示例：**
```
Explain the UserAuth class
```
```
What does the processPayment function do?
```
```
Break down the ApiService class methods
```
**Verdent 会解释的内容：**
- **用途**：该函数或类完成了什么
- **参数**：输入类型、预期值和约束条件
- **返回类型**：输出类型和可能的返回值
- **内部逻辑**：实现是如何逐步运作的
- **依赖项**：使用的外部模块、函数或服务
- **使用示例**：该函数/类在你代码的其他位置如何使用
Verdent 会追踪代码的执行流程，识别边界情况，并解释实现选择背后的理由。
---
## 生成文档
Verdent 可以生成多种格式的文档，包括内联代码注释（JSDoc、Python docstrings 等）、README 文件、API 文档和架构指南。
#### 使用 Plan Mode 生成文档
在 Plan Mode 中，Verdent 可以：
- 分析你现有的文档，匹配其风格和详细程度
- 就格式偏好提出澄清性问题（注释风格、详细程度、是否包含示例）
- 分析代码库以了解当前的文档模式
- 呈现一份文档计划，说明将记录哪些内容以及采用何种风格
**示例：**
```
Generate JSDoc comments for all functions in the utils folder
```
Verdent 会检查你项目中现有的 JSDoc 注释，就偏好提问（参数描述、是否包含示例用法），然后生成符合你既有约定的文档。
**支持的文档格式：**
- **内联注释**：JSDoc、Python docstrings、Javadoc、XML 文档注释
- **README 文件**：项目概览、安装说明、使用指南
- **API 文档**：端点描述、请求/响应格式、认证细节
- **架构指南**：系统设计说明、组件关系、数据流图
在生成大量文档时使用 Plan Mode。Verdent 会审查你现有的文档风格并提出澄清性问题，以确保生成的文档符合你项目的约定。
为多个文件生成文档时使用 Plan Mode，在提交前审查文档结构。
---
## 总结文件和模块
Verdent 通过阅读代码、理解其结构，并用通俗的语言解释其用途，来分析和总结文件或模块。
**示例：**
```
Summarize what the authMiddleware.js file does
```
```
Explain the purpose of the UserService module
```
```
What's the main responsibility of the PaymentController?
```
**Verdent 会提供的内容：**
- **主要用途**：该文件/模块在系统中完成了什么
- **关键函数**：主要的函数或方法及其作用
- **依赖项**：使用的外部模块和服务
- **导出项**：公共 API 以及系统其他部分可以访问的内容
- **模式**：使用的设计模式或架构方法
- **集成点**：它如何与项目的其他部分连接
Verdent 会阅读文件、识别关键函数、追踪依赖项，并解释该代码如何融入更大的项目架构中。
---
## 理解架构
Verdent 通过详细的文字描述、组件关系和数据流说明来解释架构。虽然它不会直接生成图形化图表，但可以创建 ASCII 字符图或可供渲染的 Mermaid 图表代码。
**示例：**
```
Explain the architecture of this application and show component relationships
```
Verdent 可能会生成一个 ASCII 表示：
```
Frontend (React)
↓
API Layer (Express)
↓
Service Layer (Business Logic)
↓
Database Layer (PostgreSQL)
```
或生成可供渲染的 Mermaid 代码：
```mermaid
graph TD
A[React Frontend] --> B[API Gateway]
B --> C[Auth Service]
B --> D[User Service]
C --> E[Database]
D --> E
```
**架构解释包括：**
- **组件交互**：系统不同部分如何通信
- **数据流**：信息如何在应用程序中流动
- **架构模式**：MVC、微服务、分层架构等
- **技术栈**：前端、后端、数据库、外部服务
- **集成点**：API、消息队列、webhook、第三方服务
- **可扩展性模式**：负载均衡、缓存、数据库分片
Verdent 会分析你的项目结构，追踪导入和依赖关系，识别模式，并解释你系统设计背后的架构决策。
---
## 帮助新团队成员上手
Verdent 通过回答代码库相关问题、解释架构决策、识别关键文件和模式，以及生成专门帮助新人理解项目结构和约定的文档，来帮助新团队成员上手。
**在 Plan Mode 中**，Verdent 可以提出澄清性问题，了解代码库的哪些方面与新团队成员的职责最相关，然后创建个性化的上手指南。
**上手问题示例：**
```
What's the best starting point for understanding this codebase?
```
```
How does data flow from the API to the frontend?
```
```
Where should I look to understand the authentication system?
```
```
What are the naming conventions and code style guidelines used here?
```
**Verdent 可以生成：**
- **上手指南**：代码库架构的逐步讲解
- **组件图**：展示组件之间关系的可视化或文本指南
- **常见模式**：频繁使用的模式和约定的文档
- **安装说明**：如何配置开发环境并运行项目
- **首批任务**：建议简单的首次贡献以熟悉项目
新团队成员可以通过对话方式探索代码库，立即获得答案，无需打断资深开发者，也无需花费数小时通读代码。
Verdent 的 Explorer 子智能体让新人能够高效地发现代码库。他们可以提出宽泛的问题，如"展示所有 React 组件"，或具体的查询，如"错误日志在哪里实现？"，并立即获得准确的答案。
---
## 最佳实践
先从高层次的问题开始，如"架构是什么？"，然后再深入具体的实现。这样可以逐步构建上下文。
对于跨代码库的彻底搜索，显式提及 Explorer 智能体以确保不遗漏任何实例："使用 Explorer 查找所有的认证检查。"
理解决策背后的理由往往比理解实现更有价值。在问"这段代码做什么？"的同时，也问"为什么选择这种模式？"
在生成文档时，使用 Plan Mode 来审查 Verdent 的方案，确保它符合你的风格，并在执行前完善计划。
当你想要详细解释时，引用具体的文件："@components/UserProfile.tsx 解释这个组件"可确保 Verdent 聚焦于正确的代码。
在进行修改之前，先让 Verdent 解释当前的实现。这有助于 Verdent 提出更符合现有模式的建议。
Verdent 会保持对话上下文，因此你可以提出澄清性问题、请求更深入的解释，或探索相关主题，而无需重复上下文。
---
## 另请参阅
了解如何使用 Verdent 编写新功能和组件
在 AI 辅助下安全地改进和重构现有代码