# 规则系统与行为引导 (/zh-CN/docs/verdent-for-vscode/agents-rules/rule-systems)

> 通过规则系统控制 Verdent 的行为



规则文件是 Markdown 文档，用于定义 Verdent 在编码会话期间如何运作和响应。它们引导 AI 智能体的行为、输出格式、决策制定，以及对项目标准的遵循。

\*\*用途：\*\*规则让你无需更改代码或设置即可自定义 Verdent 的行为。它们确立编码规范、偏好模式、沟通风格以及任务执行偏好，并在多个会话间持续生效。

\*\*规则的工作方式：\*\*Verdent 在对话过程中持续参考规则文件，将这些指南应用于代码生成、分析、文档编写和决策制定。规则影响每一次智能体响应，以确保与用户偏好保持一致。

**三个类别：**

* **全局偏好**（VERDENT.md）—— 个人编码风格、语言偏好
* **项目专属标准**（AGENTS.md）—— 团队规范、架构模式
* **计划自定义**（Plan.md）—— Plan Mode 的输出格式与内容

\*\*规则优先级：\*\*当规则冲突时，Verdent 按以下优先级处理：**AGENTS.md**（最高）→ **VERDENT.md**（中等）→ **默认值**（最低）

***

## 用户规则（VERDENT.md） [#用户规则verdentmd]

VERDENT.md 定义适用于所有项目和会话的全局偏好。它确立个人编码风格、偏好工具、沟通偏好以及默认行为。

### 位置与作用范围 [#位置与作用范围]

**文件位置：** `~/.verdent/VERDENT.md`

**作用范围：** 对所有项目全局生效

**访问方式：**

* Settings → Rules → User Rules
* 直接编辑文件 `~/.verdent/VERDENT.md`

\*\*生效时机：\*\*规则在新对话中立即生效，并影响当前对话的响应。

***

### 使用场景 [#使用场景]

<Tabs>
  <Tab title="编码偏好">
    **编码偏好**

    * 缩进风格（2 个空格、4 个空格、制表符）
    * 命名规范（camelCase、snake\_case、PascalCase）
    * 偏好的语言特性（ES6+、TypeScript 严格模式、类型提示）

    定义你在所有项目中通用的个人编码风格与规范。
  </Tab>

  <Tab title="输出语言">
    **输出语言**

    * 默认响应语言（例如"始终使用西班牙语响应"）
    * 技术术语处理（"当没有对应法语词时使用英语术语"）

    控制 Verdent 在响应和解释中使用的语言。
  </Tab>

  <Tab title="代码注释">
    **代码注释**

    * 偏好的详细程度（"详细注释"与"仅最少注释"）
    * 注释语言（"用法语撰写注释"）

    指定代码注释的数量及使用的语言。
  </Tab>

  <Tab title="文档">
    **文档风格**

    * 代码应如何记录（JSDoc、TSDoc、docstring）
    * 在文档中包含使用示例

    为 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 严格模式
    * 创建命名导出（而非默认导出）
    * 添加带 @param/@returns 标签的 TSDoc 注释
    * 按类别组织导入
  </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 进行数据操作
    * 在所有函数上包含类型提示
    * 在转换后显示 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 顶部栏的 **Settings** 按钮
    2. 从下拉菜单中选择 **Rules**
    3. 选择 **User Rules**
    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） [#项目规则agentsmd]

AGENTS.md 定义项目专属规则，用于控制智能体在当前项目中的行为。它确立团队编码标准、架构模式、测试要求，以及该项目特有的开发工作流。

### 位置与作用范围 [#位置与作用范围-1]

**文件位置：** 项目根目录

**作用范围：** 仅当前项目

**版本控制：** 可提交到 git 以供团队共享

**访问方式：**

* Settings → Rules → Project Rules
* 直接编辑 `<project-root>/AGENTS.md`

***

### 使用场景 [#使用场景-1]

<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>

***

### 格式与语法 [#格式与语法-1]

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 的区别 [#与-verdentmd-的区别]

**作用范围：**

* **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） [#计划规则planmd]

Plan.md 自定义 Plan Mode 中生成的计划的内容与格式。它控制计划的详细程度、包含的分区、格式偏好以及显示的信息。

### 位置与作用范围 [#位置与作用范围-2]

**文件位置：** \~/.verdent/plan\_settings.json

**作用范围：** 对所有项目全局生效

**应用时机：** 仅在 Plan Mode 生成计划时应用

**访问方式：**

* Settings → Rules → Plan Rules
* 直接编辑文件 \~/.verdent/plan\_settings.json

***

### 使用场景 [#使用场景-2]

<Tabs>
  <Tab title="计划结构">
    **计划结构**

    定义要包含的分区：

    * 摘要、前置条件、步骤、验证
    * 风险评估、回滚流程
    * 时间估计、关键路径

    控制每个计划中出现哪些分区与信息。
  </Tab>

  <Tab title="详细程度">
    **详细程度**

    控制粒度：

    * 高层概览（每个阶段 1-2 小时）
    * 详细的实现步骤（每个任务 15-30 分钟）
    * 函数级细节（签名、文件路径）

    调整实现计划的粒度与具体程度。
  </Tab>

  <Tab title="格式">
    **格式偏好**

    选择呈现风格：

    * 编号列表与项目符号
    * 代码片段与文字描述
    * 图示（以文字描述）

    自定义计划信息的格式化与显示方式。
  </Tab>

  <Tab title="信息">
    **信息纳入**

    指定额外的元素：

    * 内联时间估计
    * 风险等级（低/中/高）
    * 团队协作的角色分配
    * 强调测试要求

    添加上下文与元数据，使计划更具可操作性。
  </Tab>
</Tabs>

***

### 格式与语法 [#格式与语法-2]

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 脚本回退迁移"
  </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-步识别冲突]

1. 观察到与规则相矛盾的意外行为
2. 检查哪些规则可能适用于该情况
3. 查找规则文件之间的矛盾

#### 第 2 步：检查规则优先级 [#第-2-步检查规则优先级]

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

项目规则覆盖个人偏好。

#### 第 3 步：隔离测试 [#第-3-步隔离测试]

\*\*禁用 VERDENT.md：\*\*临时重命名或清空文件，测试冲突是否解决

\*\*不使用 AGENTS.md 测试：\*\*在没有 AGENTS.md 的项目中工作，以隔离 user\_rules 的行为

\*\*新对话：\*\*开启全新会话，以排除对话上下文的影响

***

### 常见冲突场景 [#常见冲突场景]

#### 场景 1：格式冲突 [#场景-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：同一文件中存在矛盾规则 [#场景-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：规则过于含糊 [#场景-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
```

**逻辑化组织：**

* 在分区标题下对相关规则分组
* 分离关注点（风格、测试、文档、安全）
* 在各规则文件中使用一致的结构

**保持规则可维护：**

* 编写简洁的规则（每个项目符号一个概念）
* 随项目演进审查并更新规则
* 及时移除过时规则

**优先排列重要规则：**

* 将关键规则置于每个分区的最前面
* 对不可妥协的标准使用强调（"**绝不**提交凭证"）
* 聚焦于能预防 bug 或安全问题的规则

**测试规则有效性：**

* 验证 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">
    编写高效提示词，最大化发挥 Verdent 的能力
  </Card>
</CardGroup>