# 理解既有程式碼 (/zh-Hant/docs/verdent-for-vscode/task-based-guides/understanding-code)
> 使用 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 docstring 等）、README 檔案、API 文件與架構指南。
#### 使用 Plan Mode 產生文件 [#使用-plan-mode-產生文件]
在 Plan Mode 中，Verdent 可以：
* 分析你既有的文件以符合其風格與密度
* 詢問關於格式偏好的釐清問題（註解風格、細節程度、是否包含範例）
* 分析程式碼庫以理解目前的文件模式
* 呈現一份文件計畫，說明將記錄哪些內容以及採用何種風格
**範例：**
```
Generate JSDoc comments for all functions in the utils folder
```
Verdent 會檢視你專案中既有的 JSDoc 註解、詢問關於偏好的問題（參數說明、是否包含使用範例），接著產生符合你既定慣例的文件。
**支援的文件格式：**
* **行內註解**：JSDoc、Python docstring、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 explain this component」可確保 Verdent 聚焦於正確的程式碼。
在進行修改之前，先請 Verdent 說明目前的實作。這能幫助 Verdent 提出更符合既有模式的建議。
Verdent 會維持對話上下文，因此你可以提出釐清問題、要求更深入的說明，或探索相關主題，而無需重複說明上下文。
***
## 另請參閱 [#另請參閱]
了解如何使用 Verdent 撰寫新功能與元件
透過 AI 協助安全地改善並重構既有程式碼