---
title: "規則系統與行為引導"
description: "透過規則系統控制 Verdent 的行為"
---

規則檔案是 Markdown 文件，用來定義 Verdent 在程式設計工作階段中的行為與回應方式。它們會引導 AI 代理的行為、輸出格式、決策制定，以及對專案標準的遵循。

**目的：** 規則讓你無需變更程式碼或設定即可自訂 Verdent 的行為。它們建立程式設計慣例、偏好的模式、溝通風格，以及可跨工作階段持續沿用的任務執行偏好。

**規則如何運作：** Verdent 在對話過程中會持續參照規則檔案，將相關指引套用到程式碼生成、分析、文件撰寫與決策制定上。規則會影響每一次代理回應，確保與使用者偏好保持一致。

**三大類別：**

- **全域偏好**（VERDENT.md）- 個人程式設計風格、語言偏好
- **專案專屬標準**（AGENTS.md）- 團隊慣例、架構模式
- **計畫自訂**（Plan.md）- Plan Mode 的輸出格式與內容

**規則優先順序：** 當規則發生衝突時，Verdent 會套用優先順序：**AGENTS.md**（最高）→ **VERDENT.md**（中等）→ **預設值**（最低）

---

## 使用者規則（VERDENT.md）

VERDENT.md 定義適用於所有專案與工作階段的全域偏好。它建立個人程式設計風格、偏好的工具、溝通偏好，以及預設行為。

### 位置與範圍

**檔案位置：** `~/.verdent/VERDENT.md`

**範圍：** 全域適用於所有專案

**存取方式：**

- 設定 → 規則 → 使用者規則
- 直接在 `~/.verdent/VERDENT.md` 編輯檔案

**變更生效時機：** 規則會立即套用於新對話，並影響當前對話的回應。

---

### 使用情境

<Tabs>
  <Tab title="程式設計偏好">
    **程式設計偏好**

    - 縮排風格（2 空格、4 空格、tab）
    - 命名慣例（camelCase、snake_case、PascalCase）
    - 偏好的語言特性（ES6+、TypeScript strict 模式、type hints）

    定義你的個人程式設計風格與慣例，套用於所有專案。
  </Tab>
  <Tab title="輸出語言">
    **輸出語言**

    - 預設回應語言（例如「一律以西班牙文回應」）
    - 技術術語處理（「當無對應法文時使用英文術語」）

    控制 Verdent 在回應與說明中使用的語言。
  </Tab>
  <Tab title="程式碼註解">
    **程式碼註解**

    - 偏好的詳細程度（「詳細註解」相對於「僅最少量註解」）
    - 註解語言（「以法文撰寫註解」）

    指定程式碼應以多少篇幅、何種語言加上註解。
  </Tab>
  <Tab title="文件">
    **文件風格**

    - 程式碼應如何記錄（JSDoc、TSDoc、docstrings）
    - 在文件中包含使用範例

    為 API 文件與程式碼文件格式設定標準。
  </Tab>
  <Tab title="溝通">
    **溝通**

    - 回應的語氣與詳盡程度（「簡短說明」相對於「詳細說明」）
    - 說明風格（「先顯示程式碼，再進行說明」）

    自訂 Verdent 如何與你溝通並呈現資訊。
  </Tab>
</Tabs>

---

### 格式與語法

VERDENT.md 使用純 Markdown 格式，搭配項目符號或編號清單。

**結構：**

```markdown
# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly
```

**撰寫風格：**

- 使用清楚、指示性的語言（「一律使用……」、「偏好……」、「絕不……」）
- 以邏輯區塊與標題組織內容
- 以項目符號呈現個別規則
- 對期望的行為要明確具體

---

### 依開發者類型的範例

<Tabs>
  <Tab title="TypeScript">
    ```markdown
    # User Rules

    ## TypeScript Preferences
    - Use strict mode in tsconfig.json
    - Prefer interfaces over type aliases for object shapes
    - Include return types on all functions
    - Use const assertions where appropriate

    ## Code Organization
    - One component per file
    - Named exports instead of default exports
    - Organize imports: external, internal, types

    ## Documentation
    - TSDoc comments for public APIs
    - Include @param and @returns tags
    ```

    **套用方式：** 當你要求 Verdent 建立新的 React 元件時，它會自動：

    - 使用 TypeScript 並啟用 strict 模式
    - 建立具名匯出（而非預設匯出）
    - 加入帶有 @param/@returns 標籤的 TSDoc 註解
    - 依類別整理 imports
  </Tab>
  <Tab title="Python 資料科學">
    ```markdown
    # User Rules

    ## Python Style
    - Follow PEP 8 conventions
    - Use type hints for function signatures
    - Prefer list comprehensions over map/filter

    ## Data Analysis
    - Use pandas for data manipulation
    - Include DataFrame.head() after transformations
    - Document assumptions about data

    ## Output Format
    - Show shape and info() after operations
    - Include visualization examples
    ```

    **套用方式：** 當你要求 Verdent 撰寫資料分析程式碼時，它會：

    - 使用 pandas 進行資料操作
    - 在所有函式上加入 type hints
    - 在轉換後顯示 DataFrame.head() 與 shape
    - 加入內嵌註解說明資料假設
  </Tab>
  <Tab title="全端 JS">
    ```markdown
    # User Rules

    ## JavaScript Preferences
    - Use ES6+ features (arrow functions, destructuring)
    - Async/await over promises
    - Template literals for string interpolation

    ## Testing
    - Jest for unit tests
    - Include test cases for edge conditions
    - Aim for 80%+ code coverage

    ## Code Review
    - Flag potential performance issues
    - Suggest security improvements
    ```

    **套用方式：** Verdent 會：

    - 以 ES6+ 語法撰寫現代 JavaScript
    - 使用 async/await 而非 promise 鏈
    - 生成以 80% 覆蓋率為目標的 Jest 測試
    - 主動找出效能與安全性疑慮
  </Tab>
  <Tab title="多語言">
    ```markdown
    # User Rules

    ## Communication
    - Always respond in French
    - Use technical English terms when no French equivalent exists
    - Provide French variable/function names when appropriate

    ## Code Comments
    - Write comments in French
    - Documentation in both French and English
    ```

    **套用方式：** 所有 Verdent 回應將以法文呈現，並在適當處保留英文技術術語。程式碼註解與文件會遵循你的語言偏好。
  </Tab>
  <Tab title="極簡主義">
    ```markdown
    # User Rules

    ## Code Style
    - Minimal comments - code should be self-documenting
    - Short, focused functions (< 20 lines)
    - Avoid unnecessary abstractions

    ## Output Preferences
    - Brief explanations
    - Show code first, explain after
    - No verbose documentation unless requested
    ```

    **套用方式：** Verdent 會：

    - 生成簡潔、自我說明的程式碼
    - 將函式保持在 20 行以內
    - 在顯示程式碼後提供簡短說明
    - 除非你明確要求，否則避免冗長註解
  </Tab>
</Tabs>

---

### 如何建立與編輯

<Tabs>
  <Tab title="設定選單">
    **建議大多數使用者採用**

    1. 點擊 Verdent 頂部列的 **設定** 按鈕
    2. 從下拉選單選擇 **規則**
    3. 選擇 **使用者規則**
    4. 檔案會在 VS Code 編輯器中開啟
    5. 使用 Markdown 格式編輯
    6. 儲存檔案（`Cmd+S` / `Ctrl+S`）

    此方法會自動定位檔案並在你的預設編輯器中開啟。
  </Tab>
  <Tab title="直接編輯檔案">
    **建議進階使用者採用**

    1. 前往 `~/.verdent/VERDENT.md`
    2. 以任何文字編輯器開啟
    3. 編輯 Markdown 內容
    4. 儲存變更

    若你偏好直接操作設定檔，此方法較快。
  </Tab>
</Tabs>

---

## 專案規則（AGENTS.md）

AGENTS.md 定義專案專屬的規則，用來控制代理在當前專案中的行為。它建立團隊程式設計標準、架構模式、測試需求，以及該專案專屬的開發工作流程。

### 位置與範圍

**檔案位置：** 專案根目錄

**範圍：** 僅限當前專案

**版本控制：** 可提交至 git 以供整個團隊共用

**存取方式：**

- 設定 → 規則 → 專案規則
- 直接在 `<project-root>/AGENTS.md` 編輯

---

### 使用情境

<Tabs>
  <Tab title="團隊慣例">
    **團隊慣例**

    所有團隊成員共同遵循的程式設計標準：

    - 整個團隊一致的縮排
    - 元件／函式的命名慣例
    - 檔案組織模式

    在整個開發團隊中強制執行一致的程式設計風格。
  </Tab>
  <Tab title="架構">
    **架構模式**

    專案專屬的設計模式：

    - MVC、微服務、monorepo 結構
    - 狀態管理方式（Redux、Context、Zustand）
    - API 設計模式（REST、GraphQL）

    為專案定義架構決策與模式。
  </Tab>
  <Tab title="測試">
    **測試需求**

    期望的測試覆蓋率與框架：

    - 最低覆蓋率門檻（80%、90%）
    - 測試框架（Jest、pytest、Vitest）
    - 測試檔案命名慣例

    為專案建立測試標準與品質關卡。
  </Tab>
  <Tab title="工作流程">
    **開發工作流程**

    建置指令、部署程序、PR 指南：

    - 如何執行測試（`pnpm test`、`npm run test`）
    - 特定套件的建置指令
    - PR 標題格式需求

    記錄團隊工作流程與開發程序。
  </Tab>
  <Tab title="技術">
    **技術限制**

    核准的程式庫與框架版本：

    - 允許的相依套件
    - 框架版本需求
    - 平台支援（iOS 14+、Android API 26+）

    控制技術堆疊選擇並維持一致性。
  </Tab>
</Tabs>

**團隊協作：** AGENTS.md 存放於專案根目錄，可提交至版本控制，確保所有團隊成員都在一致的代理行為下工作。

<Tip>
  透過版本控制與團隊共用 AGENTS.md，確保所有團隊成員都有一致的 AI 行為。
</Tip>

---

### 格式與語法

AGENTS.md 使用 Markdown 格式，搭配結構化區塊與項目符號，類似 VERDENT.md，但聚焦於專案專屬的需求。

**結構：**

```markdown
# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines
```

**撰寫風格：**

- 命令式、指示性的語言
- 依工作流程領域組織（開發、測試、部署）
- 具體的指令與程序
- 全團隊的標準，而非個人偏好

---

### 依專案類型的範例

<Tabs>
  <Tab title="Monorepo">
    ```markdown
    # AGENTS.md

    ## Dev environment tips
    - Use `pnpm dlx turbo run where <project_name>` to jump to a package
    - Run `pnpm install --filter <project_name>` to add package to workspace
    - Check the name field in package.json to confirm the right name

    ## Testing instructions
    - Run `pnpm turbo run test --filter <project_name>` for all checks
    - From package root: `pnpm test`
    - Focus on one test: `pnpm vitest run -t "<test name>"`
    - Fix all errors before merge

    ## PR instructions
    - Title format: [<project_name>] <Title>
    - Always run `pnpm lint` and `pnpm test` before committing
    ```

    **套用方式：** 在此 monorepo 中作業時，Verdent 會：

    - 使用 turbo 指令進行導覽與測試
    - 以專案名稱前綴格式化 PR 標題
    - 在建議提交前執行 lint 與 test 指令
  </Tab>
  <Tab title="React/TypeScript">
    ```markdown
    # AGENTS.md

    ## Code Standards
    - Use functional components with hooks
    - TypeScript strict mode required
    - Named exports only (no default exports)
    - PropTypes or TypeScript interfaces for all components

    ## File Organization
    - One component per file
    - Components in `src/components/`
    - Hooks in `src/hooks/`
    - Utils in `src/utils/`

    ## Testing
    - Jest + React Testing Library
    - Test all user interactions
    - 80%+ coverage required
    ```

    **套用方式：** Verdent 建立的所有 React 元件將：

    - 使用搭配 hooks 的函式型元件
    - 包含 TypeScript 介面
    - 放置於正確的目錄中
    - 包含以 80% 覆蓋率為目標的 Jest 測試
  </Tab>
  <Tab title="後端 API">
    ```markdown
    # AGENTS.md

    ## API Standards
    - All endpoints include input validation
    - Use async/await for asynchronous operations
    - Consistent error format: { error: string, code: number }
    - Rate limiting on public endpoints

    ## Security
    - Never log sensitive data (passwords, tokens, PII)
    - Parameterized queries only (prevent SQL injection)
    - Validate and sanitize all inputs

    ## Testing
    - Unit tests for all business logic
    - Integration tests for API endpoints
    - Test success and error cases
    ```

    **套用方式：** 建立 API 端點時，Verdent 會：

    - 自動加入輸入驗證
    - 對資料庫操作使用參數化查詢
    - 為成功與錯誤情況生成測試
    - 避免記錄敏感資料
  </Tab>
  <Tab title="行動應用程式">
    ```markdown
    # AGENTS.md

    ## Platform Support
    - iOS 14+ and Android API 26+
    - React Native 0.72+
    - Test on both platforms before PR

    ## State Management
    - Use Redux Toolkit
    - Async operations with Redux Thunk
    - Normalize state shape

    ## Performance
    - Images: WebP format, max 500KB
    - Bundle size: monitor with bundle analyzer
    - FlatList for long lists (>20 items)
    ```

    **套用方式：** 行動應用程式的程式碼將：

    - 支援最低平台版本
    - 使用 Redux Toolkit 進行狀態管理
    - 將圖片最佳化為 WebP 格式
    - 在長清單上使用 FlatList 以提升效能
  </Tab>
  <Tab title="Python Django">
    ```markdown
    # AGENTS.md

    ## Django Conventions
    - Follow Django best practices and PEP 8
    - Class-based views preferred
    - Django ORM for database operations
    - Migrations: never edit generated files

    ## Testing
    - pytest-django for all tests
    - Factory Boy for test fixtures
    - Coverage must be 90%+

    ## Deployment
    - Docker compose for local development
    - Environment variables in .env (never committed)
    - Run migrations before deployment
    ```

    **套用方式：** Django 程式碼將：

    - 使用類別型視圖
    - 使用 Django ORM 而非原生 SQL
    - 以 Factory Boy fixtures 生成 pytest 測試
    - 以 90%+ 測試覆蓋率為目標
  </Tab>
</Tabs>

---

### 與 VERDENT.md 的差異

**範圍：**

- **VERDENT.md：** 適用於所有專案的個人偏好
- **AGENTS.md：** 僅限特定專案的團隊標準

**優先順序：**

- **AGENTS.md：** 較高優先順序——為了專案一致性而覆寫 user_rules
- **VERDENT.md：** 較低優先順序——在無專案規則衝突時套用

**內容焦點：**

- **VERDENT.md：** 個人程式設計風格、溝通偏好、個人工具
- **AGENTS.md：** 團隊慣例、專案架構、共用工作流程、技術堆疊

**版本控制：**

- **VERDENT.md：** 不共用——保留在個人的機器上
- **AGENTS.md：** 提交至 git——與整個團隊共用

**儲存位置：**

- **VERDENT.md：** `~/.verdent/VERDENT.md`（全域）
- **AGENTS.md：** 專案根目錄（專案專屬）

**衝突解決範例：**

```
VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)
```

**何時使用哪一個：**

- **VERDENT.md：** 你希望套用於所有專案的個人偏好
- **AGENTS.md：** 整個團隊在此專案中必須遵循的標準

---

## 計畫規則（Plan.md）

Plan.md 用來自訂在 Plan Mode 中生成的計畫的內容與格式。它控制計畫的詳細程度、納入的區塊、格式偏好，以及顯示的資訊。

### 位置與範圍

**檔案位置：** ~/.verdent/plan_settings.json

**範圍：** 全域適用於所有專案

**套用時機：** 僅在 Plan Mode 生成計畫時套用

**存取方式：**

- 設定 → 規則 → 計畫規則
- 直接在 ~/.verdent/plan_settings.json 編輯檔案

---

### 使用情境

<Tabs>
  <Tab title="計畫結構">
    **計畫結構**

    定義要納入的區塊：

    - 摘要、先決條件、步驟、驗證
    - 風險評估、回滾程序
    - 時間估算、關鍵路徑

    控制每個計畫中出現哪些區塊與資訊。
  </Tab>
  <Tab title="詳細程度">
    **詳細程度**

    控制細緻度：

    - 高層級概覽（每個階段 1-2 小時）
    - 詳細實作步驟（每個任務 15-30 分鐘）
    - 函式層級細節（簽章、檔案路徑）

    調整實作計畫的細緻與具體程度。
  </Tab>
  <Tab title="格式">
    **格式偏好**

    選擇呈現風格：

    - 編號清單相對於項目符號
    - 程式碼片段相對於文字描述
    - 圖表（以文字描述）

    自訂計畫資訊的格式與顯示方式。
  </Tab>
  <Tab title="資訊">
    **資訊納入**

    指定額外元素：

    - 內嵌時間估算
    - 風險等級（低／中／高）
    - 團隊協作的角色分派
    - 強調測試需求

    為計畫加入上下文與中繼資料，使其更具可執行性。
  </Tab>
</Tabs>

---

### 格式與語法

Plan.md 使用 Markdown 格式，以區塊描述期望的計畫結構與內容。

**結構：**

```markdown

---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes
```

---

### 依計畫風格的範例

<Tabs>
  <Tab title="詳細技術型">
    ```markdown
    ---
    name: Detailed Technical
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Executive summary (2-3 sentences)
    - Prerequisites and dependencies
    - Numbered implementation steps
    - Testing and verification strategy
    - Rollback procedures

    ## Level of Detail
    - Break into 20-30 minute tasks
    - Specific file paths for all modifications
    - Function signatures for new code
    - Database schema changes with migration steps

    ## Format
    - Numbered lists for sequence
    - Code blocks for complex logic
    - Diagrams for architecture changes (describe verbally)
    ```

    **套用方式：** 計畫將包含：

    - 頂部的執行摘要
    - 20-30 分鐘的任務拆解
    - 具體檔案路徑，如 `src/components/Auth/Login.tsx`
    - 函式簽章，如 `async function authenticateUser(credentials: UserCredentials): Promise<AuthResult>`
    - 測試與回滾程序
  </Tab>
  <Tab title="高層策略型">
    ```markdown
    ---
    name: High-Level Strategic
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Brief overview (1 paragraph)
    - Major phases only (3-5 high-level steps)
    - Key decisions and trade-offs
    - Success criteria

    ## Level of Detail
    - High-level phases (1-2 hours each)
    - Avoid implementation specifics
    - Focus on approach and strategy

    ## Format
    - Bullet points for flexibility
    - Minimal code examples
    - Emphasize "why" over "how"
    ```

    **套用方式：** 計畫將以高層級呈現，聚焦於：

    - 以 3-5 個主要階段呈現策略方法
    - 偏重「為什麼」的說明而非實作細節
    - 決策點與權衡取捨
    - 成功標準，但不含具體實作
  </Tab>
  <Tab title="時間導向型">
    ```markdown
    ---
    name: Time-Conscious
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Time estimates for each step
    - Total project duration estimate
    - Parallel tasks identified
    - Critical path highlighted

    ## Level of Detail
    - Tasks sized to 30-minute increments
    - Dependencies clearly marked
    - Blocking operations identified

    ## Format
    - Include time estimates inline
    - Mark parallel tasks
    - Highlight critical path with bold
    ```

    **套用方式：** 計畫將包含：

    - 每個步驟附帶時間估算：「建立驗證中介軟體（45 分鐘）」
    - 總時長：「估計總計：6 小時」
    - 標記平行任務：「可與步驟 3 平行進行」
    - 將關鍵路徑以粗體呈現以顯示阻塞操作
  </Tab>
  <Tab title="風險導向型">
    ```markdown
    ---
    name: Risk-Focused
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Risk assessment for each phase
    - Mitigation strategies included
    - Rollback procedures defined
    - Testing requirements emphasized

    ## Level of Detail
    - Identify potential failure points
    - Document error handling approach
    - Include recovery procedures

    ## Format
    - Risk levels: low, medium, high
    - Separate "Risks" section for each phase
    - Mitigation steps in sub-bullets
    ```

    **套用方式：** 每個階段將包含：

    - 風險評估：「風險：高（正式環境的資料庫遷移）」
    - 緩解措施：「先在測試環境執行遷移，並以測試查詢驗證」
    - 回滾：「若發生問題，以 down script 還原遷移」
  </Tab>
  <Tab title="團隊協作型">
    ```markdown
    ---
    name: Team Collaboration
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Role assignments for each task
    - Coordination points identified
    - Review checkpoints included
    - Communication requirements

    ## Level of Detail
    - Specify who handles each component
    - List integration points between team members
    - Include pair programming opportunities

    ## Format
    - Use mentions for role assignments
    - Mark collaboration points
    - Include "Review required" markers
    ```

    **套用方式：** 計畫將指明：

    - 「後端 API（後端團隊）：建立驗證端點」
    - 「整合點：前端團隊等待後端提供的 API 規格」
    - 「需審查：合併前由安全團隊審查」
  </Tab>
</Tabs>

---

### 計畫規則何時套用？

**計畫規則的套用：**

- **時機：** 僅在 Plan Mode 生成計畫時套用
- **範圍：** 控制計畫格式與內容，而非程式碼生成
- **獨立性：** 不與 VERDENT.md 或 AGENTS.md 衝突

**其他規則類型的套用：**

- **VERDENT.md：** 在所有模式（Agent、Plan、Chat）中持續套用
- **AGENTS.md：** 在所有模式中持續套用，提供專案專屬行為

**互動範例：**

```
Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates
```

**模式專屬行為：**

- **Agent Mode：** 套用 VERDENT.md + AGENTS.md（無 plan_rules.md）
- **Plan Mode：** 同時套用 VERDENT.md + AGENTS.md + Plan.md
- **Chat Mode：** 套用 VERDENT.md + AGENTS.md（無 Plan.md）

---

## 規則優先順序與衝突解決

當規則發生衝突時，Verdent 會套用優先順序以確保行為一致。

### 優先順序

**1. 專案規則（AGENTS.md）- 最高優先順序** 專案專屬規則會覆寫全域偏好。為了一致性，團隊標準優先於個人偏好。

**2. 使用者規則（VERDENT.md）- 中等優先順序** 在無專案專屬規則衝突時套用全域偏好。

**3. 預設行為 - 最低優先順序** 在未指定任何規則時套用 Verdent 的內建預設值。

**衝突解決範例：**

```
VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)
```

**計畫規則：** Plan.md 在 Plan Mode 期間獨立套用，不會與使用者／專案規則衝突。它控制計畫格式，而 VERDENT.md 與 AGENTS.md 則控制計畫內的程式碼風格。

<Note>
  計畫規則僅影響 Plan Mode 的輸出格式，不會改變 Verdent 分析或實作解決方案的方式。
</Note>

<Tip>
  記住優先順序：AGENTS.md（最高）→ VERDENT.md（中等）→ 預設值（最低）。專案規則永遠在衝突中勝出。
</Tip>

<Info>
  詳細的衝突解決演算法、在衝突期間檢視套用中規則的機制，以及暫時停用規則的覆寫機制，目前都還在開發中。
</Info>

---

### 規則衝突疑難排解

當你觀察到與規則相牴觸的非預期行為時，請依照以下除錯策略：

#### 步驟 1：找出衝突

1. 觀察與規則相牴觸的非預期行為
2. 檢查哪些規則可能適用於該情境
3. 找出規則檔案之間的牴觸

#### 步驟 2：檢查規則優先順序

```
AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)
```

專案規則會覆寫個人偏好。

#### 步驟 3：隔離測試

**停用 VERDENT.md：** 暫時重新命名或清空檔案，測試衝突是否解決

**在無 AGENTS.md 的情況下測試：** 在沒有 AGENTS.md 的專案中作業，以隔離 user_rules 的行為

**新對話：** 開始全新工作階段，以排除對話上下文的影響

---

### 常見衝突情境

#### 情境 1：格式衝突

```
VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team
```

#### 情境 2：同一檔案中的牴觸規則

```
AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies
```

修正範例：

```markdown
- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance
```

#### 情境 3：規則過於模糊

```
"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"
```

---

### 除錯策略

**1. 明確測試：** 詢問 Verdent「針對〔特定行為〕，你遵循的是哪一條規則？」

範例：

```
You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."
```

**2. 漸進式調整：** 為模糊的規則增加具體性

<Tip>
  在除錯規則衝突時，逐一暫時停用規則，以隔離出造成非預期行為的規則。
</Tip>

調整前：

```markdown
- Use appropriate error handling
```

調整後：

```markdown
- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)
```

**3. 優先順序標記：** 對不可妥協的規則使用「CRITICAL:」或「REQUIRED:」

```markdown
## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations
```

---

### 撰寫規則的最佳實務

**具體且具指示性：**

- 使用清楚、命令式的語言（「一律使用……」、「絕不……」、「偏好……」）
- 避免模稜兩可的措辭（「盡量……」→「一律……」）
- 明確說明你想要什麼，而非你不想要什麼

**良好範例：**

```markdown
- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions
```

**應避免：**

```markdown
- Try to use modern JavaScript features
- Add comments when necessary
```

**邏輯化組織：**

- 將相關規則歸入區塊標題下
- 區分關注點（風格、測試、文件、安全性）
- 在各規則檔案間使用一致的結構

**保持規則可維護：**

- 撰寫精簡的規則（每個項目一個概念）
- 隨專案演進審查並更新規則
- 及時移除過時的規則

**為重要規則排定優先順序：**

- 將關鍵規則放在每個區塊的最前面
- 對不可妥協的標準使用強調（「**絕不**提交憑證」）
- 聚焦於能預防錯誤或安全性問題的規則

**測試規則成效：**

- 驗證 Verdent 在實務上是否遵循規則
- 開始新對話以測試規則套用
- 根據實際的代理行為調整規則

**在細節與彈性之間取得平衡：**

- 過於具體 → 僵化、無法適應的行為
- 過於模糊 → 不一致的行為
- 力求清楚指引，同時保留依上下文做出適切決策的空間

**團隊考量（AGENTS.md）：**

- 讓團隊參與規則建立
- 為不明顯的規則記錄其理由
- 讓團隊規則聚焦於共用標準，而非個人偏好

---

## 另請參閱

<CardGroup cols={2}>
  <Card title="子代理管理" icon="robot" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    建立並管理專案專屬任務的專門子代理
  </Card>
  <Card title="最佳實務：提示詞" icon="message-lines" href="/docs/verdent-for-vscode/best-practices/prompts">
    撰寫有效的提示詞以充分發揮 VerdentP 的效益
  </Card>
</CardGroup>