Best Practices
提示詞工程
撰寫有效提示詞的最佳實踐
有效的提示詞是成功運用 AI 輔助開發的基礎。清晰、具體並具備適當上下文的請求，能讓 Verdent 提供準確且切題的結果。
你將學到
- 撰寫有效提示詞的最佳實踐
- 如何提供上下文並避免常見錯誤
- @-mentions 與子代理委派等進階技巧
- 結構良好的提示詞範例
- 反覆優化的策略
什麼造就有效的提示詞
有效的提示詞清晰、具體，並提供必要的上下文，讓 Verdent 理解你的意圖並交付準確結果。
關鍵原則：
- 要具體 —— 明確說明你的需求，而非含糊的請求
- 附上細節 —— 當你有偏好時，提供技術規格
- 指定範圍 —— 釐清涉及哪些檔案／元件
- 提供上下文 —— 協助 Verdent 理解你的架構
- 說明成果 —— 描述成功的樣貌
- 使用自然語言 —— 不需要特殊語法
轉換範例：
不佳：
Fix the code良好：
Add input validation to the email field in ContactForm.js to reject invalid email formats不佳：
Add authentication良好：
Add JWT authentication using the same middleware pattern as auth.js, store tokens in httpOnly cookies常見的提示詞錯誤
範例提示詞：
Make the app betterFix the bugs| 問題 | 解決方法 |
|---|---|
| Verdent 不知道你想要哪些改進或要處理哪個錯誤 | 明確指出需要改進的部分或要修復的錯誤 |
範例提示詞：
Add authentication| 問題 | 解決方法 |
|---|---|
| Verdent 可能在你使用 OAuth 時實作 JWT，反之亦然 | 指定實作方式、既有模式與技術需求 |
範例提示詞：
Build the entire user management system with authentication, authorization, profiles, settings, and admin dashboard| 問題 | 解決方法 |
|---|---|
| 複雜的跨系統請求很難一次正確完成 | 拆分成較小的任務 —— 先做身分驗證，再做授權，最後做個人檔案 |
範例提示詞：
Update the validation logic| 問題 | 解決方法 |
|---|---|
| 不清楚要修改哪些檔案或驗證 | 指定範圍：「更新 UserController.js 中的驗證，要求使用強密碼」 |
範例提示詞：
Expecting Verdent to know your specific business rules or constraints| 問題 | 解決方法 |
|---|---|
| Verdent 在沒有你具體需求的情況下實作通用方案 | 明確說明所有限制、業務規則與需求 |
範例提示詞：
Referencing files without including them in context| 問題 | 解決方法 |
|---|---|
| Verdent 可能無法存取你正在討論的檔案 | 使用 @filename.js 明確納入相關檔案 |
範例提示詞：
Repeatedly asking for the same thing when Verdent encounters errors| 問題 | 解決方法 |
|---|---|
| 相同的做法產生相同的錯誤 | 閱讀錯誤訊息，根據失敗原因調整提示詞 |
範例提示詞：
Requesting large refactorings or multi-file changes without using Plan Mode first| 問題 | 解決方法 |
|---|---|
| 直到檔案已被修改後，你才看到完整範圍 | 對複雜任務切換到 Plan Mode，在執行前先審查做法 |
對複雜的變更啟用 Plan Mode，在執行前審查做法，可及早發現誤解。
範例提示詞：
Using Auto-Run or Skip Permission Mode without Git initialized| 問題 | 解決方法 |
|---|---|
| 若 Verdent 做出非預期的變更，沒有安全網 | 在使用寬鬆模式前，務必先初始化並提交 Git |
範例提示詞：
Providing incomplete requirements and expecting Verdent to guess correctly| 問題 | 解決方法 |
|---|---|
| Verdent 根據可能不符合你需求的假設進行實作 | 請 Verdent 訪談你：「在建立計畫前，先問我關於需求的釐清問題」 |
結構良好的提示詞範例
以清晰的需求與限制建立新功能：
Create a POST /api/tasks endpoint that:
- Accepts task title (required), description (optional), and category_id (required)
- Validates that the category exists in the database
- Returns 400 if validation fails with descriptive error messages
- Saves the task to the database and returns the created task with 201 status
- Add this to the existing tasks router in routes/tasks.js
- Create the controller method in controllers/taskController.js
- Use the existing error handling pattern from other controllers為何有效：
- 對輸入與驗證有清晰的需求
- 指定實作的具體檔案位置
- 參照既有模式以維持一致性
- 預期的 HTTP 狀態碼與錯誤處理
以上下文與建議方案描述問題：
Fix the race condition in payment processing at checkout. When multiple users submit payments simultaneously, some transactions fail with "duplicate order ID" errors. The issue appears to be in PaymentController.js around line 45 where we generate order IDs. Implement proper locking or use UUID generation to ensure unique IDs even under concurrent load.為何有效：
- 帶有徵狀的清晰問題描述
- 問題的具體位置（檔案與行號）
- 發生時機的上下文（並發使用者）
- 建議的解決方案做法
在保留行為的同時變更實作：
Refactor the authentication middleware in middleware/auth.js to use JWT tokens instead of session cookies. Keep the same authorization logic, but:
- Replace session validation with JWT verification
- Store tokens in httpOnly cookies
- Maintain the existing user object structure that routes expect
- Update only the authentication mechanism, don't change authorization rules
- Ensure all existing routes continue to work without modification為何有效：
- 清晰的目標（以 JWT 取代 session）
- 要重構的具體檔案
- 明確的限制（哪些不應變更）
- 向後相容的需求
撰寫具備全面覆蓋率的測試：
Write comprehensive unit tests for the UserService class in services/UserService.js. Cover:
- User creation with valid and invalid data
- Email validation edge cases (empty, malformed, duplicate)
- Password hashing verification
- User lookup by ID and email
- Error handling for database failures
Use Jest and follow the testing patterns in existing service tests為何有效：
- 要測試的具體類別／檔案
- 完整列出要涵蓋的情境
- 指定測試框架
- 參照既有的測試模式
以詳細規格建構 UI 元件：
Create a reusable SearchBar component for the product catalog with:
- Text input with real-time debounced search (300ms delay)
- Category dropdown filter (fetch options from /api/categories)
- Price range slider (min $0, max $1000)
- Clear filters button
- Use Material-UI components to match existing design
- Emit search parameters via onChange callback to parent
- Include PropTypes for all props為何有效：
- 含具體細節的完整功能清單
- 技術規格（300ms 防抖、價格區間）
- 指定 UI 函式庫（Material-UI）
- 整合方式（回呼至父元件）
進階提示技巧
參照特定檔案、元件或子代理：
@auth.js @UserController.js Refactor authentication to use the same validation pattern益處：
- 透過明確納入特定檔案，確保 Verdent 取得精確的上下文
- 在檔名相似的大型程式碼庫中避免歧義
- 確保所有相關程式碼同時可見，以準確進行重構與模式比對
- 當需要參照某個檔案的實作模式套用到另一個檔案時不可或缺
對大型變更在執行前切換到 Plan Mode：
Switch to Plan Mode
Refactor the entire API layer to use TypeScript with strict type checking益處：
- 在任何檔案被修改前，審查 Verdent 的完整做法
- 防止大型重構或架構變更中的高代價錯誤
- 在執行開始前，反覆優化計畫、加入限制或徹底重新導向
- 請 Verdent 用釐清問題訪談你，事先蒐集所有需求
將專門任務委派給內建或自訂的子代理：
@Code-reviewer Review the security vulnerabilities in authentication flow
@Explorer Find all files that import the deprecated API client
@Verifier Validate the authentication logic in the middleware益處：
- 運用針對特定任務（探索、驗證、程式碼審查）最佳化的專門代理
- 比通用處理更聚焦的專業與更快的結果
- 平行執行多項分析，大幅縮短總執行時間
- 為你專案的獨特需求建立具備領域知識的自訂子代理
內建預設子代理：
@Verifier—— 快速程式碼檢查與驗證@Explorer—— 快速探索程式碼庫與尋找檔案@Code-reviewer—— 程式碼品質評估
用 @Explorer 處理程式碼庫問題、用 @Code-reviewer 進行安全分析，有針對性的委派比由主代理路由更快。
對複雜的挑戰啟用延伸推理：
Think: Design the optimal database schema for a multi-tenant SaaS application益處：
- 啟用延伸推理，從多個角度更深入分析複雜問題
- 更徹底地評估替代做法與邊緣情況
- 在正確性至關重要時產出穩健的解決方案
- 回應較慢且點數用量較高，但能避免倉促、次佳方案帶來的高代價返工
Think Hard Mode 擅長架構決策、複雜除錯，以及需要深入分析的演算法問題。
在先前回應的基礎上逐步優化：
Initial: "Create a dashboard component"
Follow-up: "Add real-time data updates using WebSockets"
Follow-up: "Now add filtering and sorting capabilities"益處：
- 支援增量開發，在增加複雜度前於每一步進行測試
- 在往上建構前驗證每一層正確運作，以降低風險
- 若反覆操作產生非預期結果，可立即修正方向
- 由於每次反覆都小而有界，更容易找出是哪個具體變更引入了錯誤
反覆優化能降低風險，從小範圍開始、驗證結果，再逐步擴展。
在指定要變更的同時，指定哪些不要變更：
Add caching to the API endpoints, but:
- Don't modify the authentication middleware
- Keep the existing error handling unchanged
- Maintain backward compatibility with mobile clients益處：
- 明確界定邊界，防止修改關鍵系統（身分驗證、支付）
- 保護因合規或風險需求而必須維持不變的穩定系統
- 避免實作變更、發現功能損壞、重做方案的高代價循環
- 維持向後相容，保護久經考驗的程式碼免於不必要的重構
指向既有程式碼作為實作範例：
Implement the new ProductService following the same pattern as UserService.js, including error handling, validation, and database transaction management益處：
- 確保新實作與既有慣例保持一致
- 讓程式碼庫更易維護且更可預期
- 大幅減少所需的說明 —— 指向範例而非詳述做法
- 運用經驗證、久經考驗的模式，而非重新發明解法
- 減少錯誤並確保與既有系統無縫整合
建立 todos.md 檔案以追蹤複雜的多步驟任務：
Create a todos.md file with these tasks:
1. Refactor authentication to use JWT tokens
2. Update all controllers to use new auth middleware
3. Add tests for authentication flow
4. Update API documentation益處：
- 建立清晰的書面藍圖，可供審查、優化並與隊友分享
- 隨著專案需求演進輕鬆調整
- 跨工作階段持續存在，讓你可暫停工作、稍後恢復，並立即了解進度
- 作為專案產物，記錄已規劃、已完成與待辦事項，利於未來維護與新人上手
在不同的待辦事項之間開啟新工作階段以取得乾淨的上下文：
After completing todo #1: "Start a new session"
Then: "Let's work on todo #2 from todos.md"益處：
- 防止上下文污染，避免先前任務細節不當影響當前工作
- 確保只專注於當前待辦事項，不帶先前任務的包袱
- 不載入不必要的對話歷史，減少 token 用量
- 讓回應更快且更節省點數
- 為測試與提交變更建立自然的檢查點，維持乾淨的 git 歷史並更容易隔離問題
使用 MCP（Model Context Protocol）伺服器注入專門的上下文：
- 專案專屬文件
- API 規格（OpenAPI、GraphQL schema）
- 框架專屬知識
益處：
- 增進 Verdent 對自訂框架、內部工具，以及不在其訓練資料中的專門領域的理解
- 直接注入組織專屬的 API 規格與文件，免去反覆解釋自訂系統
- 使內部 API 與專有系統得以正確使用，這些光靠提示詞無法傳達
在提示詞中納入上下文
明確將相關檔案納入上下文：
@models/User.js @controllers/UserController.js Add password reset functionality何時使用：
- 處理緊密耦合的檔案時（模型與控制器、服務與測試）
- 參照某個檔案的實作模式以套用到另一個檔案
- 協調跨多個相關檔案的變更
- 在檔名相似的大型程式碼庫中，自動偵測可能漏掉上下文時
- 當請 Verdent「依照……相同的模式」時，務必使用，以確保它取得確切的程式碼
納入關於你技術堆疊的高層次上下文：
This is a MERN stack application (MongoDB, Express, React, Node.js) with JWT authentication. Add role-based access control following our existing middleware pattern.何時使用：
- 實作需與既有技術堆疊整合的功能時
- 首次在某程式碼庫中工作，或功能橫跨多層（前端到資料庫）時
- 當你的技術堆疊有強烈傾向（GraphQL vs REST、Redux vs Context API）會影響實作選擇時
- 當你需要 Verdent 選擇貼合你系統的做法，而非通用方案時
指向展示你慣例的程式碼：
Follow the same error handling pattern used in ProductController.js - return consistent error objects with status codes and descriptive messages何時使用：
- 當你希望新程式碼與既有慣例保持一致（錯誤處理、驗證、記錄、測試）時
- 在程式碼庫的新區域實作類似功能時
- 上手程式碼庫中不熟悉的部分，想學習並複製既有模式時
- 當你想避免詳述模式，並需要 Verdent 捕捉難以言述的細微之處時
說明限制或需求：
We're using TypeScript with strict mode enabled, React 18 with hooks only (no class components), and Material-UI v5 for styling何時使用：
- 當你的專案有特定技術需求（TypeScript 嚴格模式、僅用 React hooks、不依賴外部套件）時
- 處理舊有限制（IE11 支援、Node.js 14 相容性）時
- 當合規需求左右選擇時（WCAG 無障礙、GDPR 資料處理）
- 使用版本間有破壞性變更的特定函式庫版本時
- 當你需要防止 Verdent 提出違反專案技術邊界的方案時
解釋領域專屬規則：
Users can only view tasks assigned to them or their team. Managers can view all tasks in their department. Admins can view everything.何時使用：
- 實作具備 Verdent 無法僅從程式碼推斷的領域專屬規則的功能時
- 授權邏輯（誰能存取什麼）、業務工作流程（審批流程、狀態機）
- 驗證規則（密碼政策、資料限制）、領域限制（庫存上限、定價規則）
- 建構需要說明實體關係與基數的資料模型時
- 實作計算（折扣規則、稅額計算、佣金結構）時
- 當你需要 Verdent 正確落實組織的業務規則，而不僅是功能性程式碼時
除錯時分享錯誤訊息或記錄：
Getting "TypeError: Cannot read property 'id' of undefined" at UserController.js:42 when trying to update user profiles. The req.user object exists but doesn't have an id property after the recent auth middleware changes.何時使用：
- 修復錯誤時，務必納入完整的錯誤訊息、堆疊追蹤與記錄
- 執行階段錯誤（例外、當機）、建置失敗（編譯錯誤、linting 違規）
- 測試失敗（斷言錯誤、逾時問題）、非預期行為（錯誤輸出、缺漏資料）
- 當你有帶行號的確切錯誤訊息與顯示呼叫鏈的完整堆疊追蹤時
- 當你能提供發生時機的上下文時（總是發生、間歇性、特定條件）
- 當你想大幅提升 Verdent 找出根本原因而非猜測的能力時
Verdent 會根據你的請求自動載入相關檔案：
- 提示詞中以名稱提及的檔案
- 同一目錄下的相關檔案
- 常被存取的專案檔案
何時可依賴此功能：
- 對於關係明顯的標準檔案參照
- 以名稱提及元件，而 Verdent 需載入該特定檔案時
- 處理同一目錄下常一起運作的檔案時
- 存取常用的專案檔案（package.json、設定檔）時
- 在組織良好的程式碼庫中，對於直接明瞭的情境運作良好
- 對於複雜的多檔案重構、程式碼庫的相距甚遠部分，或檔名含糊時，改用明確的 @-mentions
透過規則檔（Settings → Rules）設定持久的上下文：
使用者規則（VERDENT.md）： 套用於所有專案的全域偏好
專案規則（AGENTS.md）： 專案專屬標準 —— 架構模式、編碼標準
計畫規則（plan_rules.md）： 自訂 Plan Mode 中的計畫格式與內容
何時使用：
- 當你在多個工作階段中反覆提供相同的上下文時
- 使用者規則用於個人偏好（編碼風格、偏好的函式庫、你偏好的模式）
- 專案規則用於團隊標準（架構決策、命名慣例、測試需求）
- 對新團隊成員上手很有價值（將團隊默會知識成文化）
- 在大型團隊間維持一致性並減少提示詞的冗長
- 當你的專案成熟到擁有值得記錄的既定模式時，投資於規則檔
納入螢幕截圖、設計稿或圖表：
@screenshot.png Implement this UI design with React components何時使用：
- 當視覺資訊比文字更能有效傳達需求時
- UI/UX 實作（設計稿、線框圖、使用者流程）
- 除錯視覺問題（版面損壞、渲染問題的螢幕截圖）
- 理解複雜架構（系統圖、資料庫 schema、流程圖）
- 對於響應式設計、無障礙分析與錯誤重現不可或缺
- 將 Figma 或 Sketch 等工具的設計轉成程式碼
- 一張捕捉良好的螢幕截圖往往能傳達需要數段文字才能描述的細節
參照外部文件或範例：
Ultrathink: Read this API documentation at https://api-docs.example.com/v1/endpoints and implement the authentication flow何時使用：
- 實作與有官方線上文件的外部 API 或函式庫整合時
- 當函式庫有複雜的設定選項或驗證流程時尤其有價值
- 使用「Ultrathink:」前綴指示 Verdent 在產生程式碼前先擷取並分析網頁內容
- 對於文件比訓練資料更新的快速演進 API 不可或缺
- 當遵循框架專屬模式時（Next.js App Router、Vue Composition API）
- 確保實作符合當前 API 版本並遵循官方建議
反覆優化策略
初始提示詞：
Add authentication to the APIVerdent 的回應可能較為通用。進一步優化：
Use JWT tokens stored in httpOnly cookies, implement refresh token rotation, and follow the authentication pattern from our existing UserController何時使用： 從一般請求開始，再根據初始回應加入細節
若 Verdent 的實作不符預期：
The validation logic is good, but use Joi schema validation instead of manual checks. Match the validation pattern in ProductController.js何時使用： 在審查輸出並找出具體改進之後
增量建構：
Initial: "Create a UserProfile component"
Follow-up: "Add an avatar upload feature with image preview"
Follow-up: "Add validation - max 5MB, only jpg/png formats"
Follow-up: "Show upload progress with a progress bar"何時使用： 在同一工作階段中逐步建構功能
若實作出乎意料：
Why did you use Redux instead of Context API? Can you explain the trade-offs for this use case?然後根據理解進一步優化：
Actually, use Context API for consistency with the rest of our application何時使用： 在請求變更前先理解其推理
對複雜變更：
Switch to Plan Mode
Show me how you would refactor the authentication system to support OAuth providers審查計畫、提出問題，並在執行前反覆優化做法。
何時使用： 需要審查的重大架構變更
若 Verdent 的風格與你不符：
The component structure is close, but use this pattern instead:
[paste example of your preferred structure]
Apply this same pattern to the remaining components何時使用： 建立或強化程式碼風格偏好
若輸出違反未說明的限制：
Good approach, but don't modify the database schema - work within the existing User table structure何時使用： 在看到初始實作後加入發現的限制
從核心功能開始，反覆加入功能：
Step 1: "Create basic CRUD endpoints for tasks"
Step 2: "Add pagination to the GET endpoint"
Step 3: "Add filtering by status and priority"
Step 4: "Add full-text search across title and description"何時使用： 增量建構複雜功能，並在每一步進行測試
常見問題
我的提示詞應該多具體？
要具體到足以消除歧義，但不必過度解釋顯而易見的細節。應包含：確切的檔案路徑、實作方式、預期成果與限制。不佳：「修復這段程式碼」—— 太含糊。良好：「在 ContactForm.js 的 email 欄位加入輸入驗證，以拒絕無效的 email 格式」—— 範圍與目標清晰。拿不準時，寧可更具體。
@-mentions 與自動檔案載入有何差異？
Verdent 會自動載入提示詞中以名稱提及的檔案，以及同一目錄下的相關檔案。@-mentions（@filename.js）明確保證某檔案在上下文中，這在處理緊密耦合的檔案、參照某個檔案的模式以套用到另一個檔案，或在大型程式碼庫中自動偵測可能漏掉上下文時至關重要。當請 Verdent「依照……相同的模式」時，務必使用 @-mentions 以確保確切的程式碼參照。
我何時該用 Plan Mode 而非一般模式？
使用 Plan Mode 的時機：大型重構或架構變更、想在執行前審查範圍的多檔案修改、需求不確定的複雜任務，或當你想讓 Verdent 在實作前用釐清問題訪談你時。略過 Plan Mode 的時機：簡單、定義明確的任務、快速錯誤修復或例行操作。Plan Mode 增加額外開銷，但能防止複雜工作中的高代價錯誤。
如果 Verdent 沒有正確理解或遵循我的提示詞怎麼辦？
使用反覆優化：審查輸出、找出問題，再在後續提示詞中提供修正。範例：「驗證邏輯很好，但請改用 Joi schema 驗證而非手動檢查。比照 ProductController.js 中的驗證模式。」你也可以請求說明：「你為何用 Redux 而非 Context API？」然後根據理解優化。不要重複相同的提示詞 —— 根據失敗原因進行調整。
在一個工作階段中，我需要在每個提示詞裡重複專案上下文嗎？
不需要 —— Verdent 在工作階段內維持對話上下文，因此你不需要重複已討論過的架構細節或慣例。然而，對於關鍵限制，或當工作階段變長時（100+ 則訊息），請重申重要的上下文。更好的做法：使用專案規則（AGENTS.md）記錄持久的上下文，例如技術堆疊、編碼標準與模式 —— 如此你就永遠不必重複它們。
結構良好、意圖清晰、具備相關上下文與具體限制的提示詞，能持續產出更好的結果。