理解既有程式碼
使用 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 definitionsShow me where database queries are definedExplorer 會在背景高效運作，提供快速答案而不會消耗你的主要上下文視窗。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 projectWhat 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 projectWhat 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 classVerdent 會提供清楚的說明，並參照你程式碼庫中的特定實作。
說明函式與類別
Verdent 會透過分析特定函式或類別的實作、參數、回傳值及其在整個程式碼庫中的使用方式，提供詳細的說明。
範例：
Explain the UserAuth classWhat does the processPayment function do?Break down the ApiService class methodsVerdent 會說明的內容：
- 用途：該函式或類別所達成的目標
- 參數：輸入類型、預期值與限制
- 回傳類型：輸出類型與可能的回傳值
- 內部邏輯：實作如何逐步運作
- 相依項目：所使用的外部模組、函式或服務
- 使用範例：該函式／類別在你程式碼中其他位置的使用方式
Verdent 會追蹤程式碼的執行流程、辨識邊界情況，並說明實作選擇背後的理由。
產生文件
Verdent 能以多種格式產生文件，包括行內程式碼註解（JSDoc、Python docstring 等）、README 檔案、API 文件與架構指南。
使用 Plan Mode 產生文件
在 Plan Mode 中，Verdent 可以：
- 分析你既有的文件以符合其風格與密度
- 詢問關於格式偏好的釐清問題（註解風格、細節程度、是否包含範例）
- 分析程式碼庫以理解目前的文件模式
- 呈現一份文件計畫，說明將記錄哪些內容以及採用何種風格
範例：
Generate JSDoc comments for all functions in the utils folderVerdent 會檢視你專案中既有的 JSDoc 註解、詢問關於偏好的問題（參數說明、是否包含使用範例），接著產生符合你既定慣例的文件。
支援的文件格式：
- 行內註解：JSDoc、Python docstring、Javadoc、XML 文件註解
- README 檔案：專案概覽、設定說明、使用指南
- API 文件：端點說明、請求／回應格式、驗證細節
- 架構指南：系統設計說明、元件關係、資料流圖
在產生大量文件時，請使用 Plan Mode。Verdent 會檢視你既有的文件風格並詢問釐清問題，以確保產生的文件符合你專案的慣例。
在為多個檔案產生文件時，請使用 Plan Mode，並在提交前檢視文件結構。
摘要檔案與模組
Verdent 會透過閱讀程式碼、理解其結構並以淺白語言說明其用途，來分析並摘要檔案或模組。
範例：
Summarize what the authMiddleware.js file doesExplain the purpose of the UserService moduleWhat's the main responsibility of the PaymentController?Verdent 會提供的內容：
- 主要用途：該檔案／模組在系統中所達成的目標
- 關鍵函式：主要的函式或方法及其角色
- 相依項目：所使用的外部模組與服務
- 匯出項目：公開 API 以及系統其他部分可存取的內容
- 模式：所使用的設計模式或架構方法
- 整合點：它如何與專案其他部分連接
Verdent 會閱讀檔案、辨識關鍵函式、追蹤相依項目，並說明該程式碼如何融入更大的專案架構中。
理解架構
Verdent 會透過詳細的文字描述、元件關係與資料流說明來解釋架構。雖然它不會直接產生圖形化圖表，但能建立 ASCII 圖或 Mermaid 圖表程式碼供你算繪。
範例：
Explain the architecture of this application and show component relationshipsVerdent 可能會產生 ASCII 表示：
Frontend (React)
↓
API Layer (Express)
↓
Service Layer (Business Logic)
↓
Database Layer (PostgreSQL)或產生可供算繪的 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 代理以確保不遺漏任何實例：「使用 Explorer 找出所有驗證檢查。」
多問「為什麼」，而不只是「是什麼」
理解決策背後的理由，往往比理解實作更有價值。在問「這段程式碼做什麼？」的同時，也問「為什麼選擇這個模式？」
善用 Plan Mode 產生文件
在產生文件時，使用 Plan Mode 來檢視 Verdent 的做法，確保它符合你的風格，並在執行前完善計畫。
使用 @-mention 取得聚焦的說明
當你需要詳細說明時，請參照特定檔案：「@components/UserProfile.tsx explain this component」可確保 Verdent 聚焦於正確的程式碼。
在要求變更前先建立上下文
在進行修改之前，先請 Verdent 說明目前的實作。這能幫助 Verdent 提出更符合既有模式的建議。
放心地提出後續問題
Verdent 會維持對話上下文，因此你可以提出釐清問題、要求更深入的說明，或探索相關主題，而無需重複說明上下文。