Verdent Docs
智能体与规则

规则系统与行为引导

通过规则系统控制 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

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

访问方式:

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

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


使用场景

编码偏好

  • 缩进风格(2 个空格、4 个空格、制表符)
  • 命名规范(camelCase、snake_case、PascalCase)
  • 偏好的语言特性(ES6+、TypeScript 严格模式、类型提示)

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

输出语言

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

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

代码注释

  • 偏好的详细程度("详细注释"与"仅最少注释")
  • 注释语言("用法语撰写注释")

指定代码注释的数量及使用的语言。

文档风格

  • 代码应如何记录(JSDoc、TSDoc、docstring)
  • 在文档中包含使用示例

为 API 文档和代码文档格式设定标准。

沟通

  • 响应的语气与详尽程度("简短解释"与"详细解释")
  • 解释风格("先展示代码,再解释")

自定义 Verdent 与你沟通及呈现信息的方式。


格式与语法

VERDENT.md 使用纯 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

写作风格:

  • 使用清晰、指令性的语言("始终使用……"、"优先……"、"绝不……")
  • 用标题将内容组织为逻辑分区
  • 用项目符号列出单条规则
  • 对期望的行为做出具体说明

按开发者类型分类的示例

# 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 注释
  • 按类别组织导入
# 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
  • 添加内联注释记录数据假设
# 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 测试
  • 主动识别性能与安全问题
# 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 响应将使用法语,并在合适处保留英语技术术语。代码注释和文档将遵循你的语言偏好。

# 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 行以内
  • 在展示代码后提供简短解释
  • 除非你明确要求,否则避免冗长注释

如何创建与编辑

推荐大多数用户使用

  1. 点击 Verdent 顶部栏的 Settings 按钮
  2. 从下拉菜单中选择 Rules
  3. 选择 User Rules
  4. 文件在 VS Code 编辑器中打开
  5. 使用 Markdown 格式编辑
  6. 保存文件(Cmd+S / Ctrl+S

此方法会自动定位文件并在你的默认编辑器中打开它。

推荐高级用户使用

  1. 导航到 ~/.verdent/VERDENT.md
  2. 用任意文本编辑器打开
  3. 编辑 Markdown 内容
  4. 保存更改

如果你偏好直接处理配置文件,此方法更快。


项目规则(AGENTS.md)

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

位置与作用范围

文件位置: 项目根目录

作用范围: 仅当前项目

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

访问方式:

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

使用场景

团队规范

所有团队成员遵循的共享编码标准:

  • 全团队一致的缩进
  • 组件/函数的命名规范
  • 文件组织模式

在整个开发团队中强制执行一致的编码风格。

架构模式

项目专属的设计模式:

  • MVC、微服务、monorepo 结构
  • 状态管理方式(Redux、Context、Zustand)
  • API 设计模式(REST、GraphQL)

定义项目的架构决策与模式。

测试要求

期望的测试覆盖率与框架:

  • 最低覆盖率阈值(80%、90%)
  • 测试框架(Jest、pytest、Vitest)
  • 测试文件命名规范

为项目确立测试标准与质量门槛。

开发工作流

构建命令、部署流程、PR 指南:

  • 如何运行测试(pnpm testnpm run test
  • 特定包的构建命令
  • PR 标题格式要求

记录团队工作流与开发流程。

技术约束

经批准的库与框架版本:

  • 允许的依赖
  • 框架版本要求
  • 平台支持(iOS 14+、Android API 26+)

控制技术栈选择并保持一致性。

**团队协作:**AGENTS.md 存储在项目根目录,可提交到版本控制,确保所有团队成员使用一致的智能体行为。

通过版本控制将 AGENTS.md 与团队共享,确保所有团队成员的 AI 行为保持一致。


格式与语法

AGENTS.md 使用带结构化分区和项目符号的 Markdown 格式,与 VERDENT.md 类似,但聚焦于项目专属要求。

结构:

# 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

写作风格:

  • 祈使、指令性的语言
  • 按工作流领域组织(开发、测试、部署)
  • 具体的命令与流程
  • 全团队标准,而非个人偏好

按项目类型分类的示例

# 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 命令
# 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 测试
# 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 会:

  • 自动添加输入校验
  • 对数据库操作使用参数化查询
  • 为成功和错误两种情况生成测试
  • 避免记录敏感数据
# 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 以提升性能
# 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%+

与 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 生成计划时应用

访问方式:

  • Settings → Rules → Plan Rules
  • 直接编辑文件 ~/.verdent/plan_settings.json

使用场景

计划结构

定义要包含的分区:

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

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

详细程度

控制粒度:

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

调整实现计划的粒度与具体程度。

格式偏好

选择呈现风格:

  • 编号列表与项目符号
  • 代码片段与文字描述
  • 图示(以文字描述)

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

信息纳入

指定额外的元素:

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

添加上下文与元数据,使计划更具可操作性。


格式与语法

Plan.md 使用 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

按规划风格分类的示例

---
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>
  • 测试与回滚流程
---
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 个主要阶段呈现战略方法
  • 重"为什么"的解释而非实现细节
  • 决策点与权衡
  • 不含具体实现的成功标准
---
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 并行进行"
  • 关键路径加粗以显示阻塞操作
---
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 脚本回退迁移"
---
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 规范"
  • "需要审查:合并前由安全团队审查"

计划规则何时应用?

计划规则的应用:

  • 时机: 仅在 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 控制计划内代码的风格。

计划规则仅影响 Plan Mode 的输出格式。它们不会改变 Verdent 分析或实现解决方案的方式。

记住优先级:AGENTS.md(最高)→ VERDENT.md(中等)→ 默认值(最低)。项目规则在冲突中总是胜出。

详细的冲突解决算法、在冲突期间查看正在应用哪条规则的机制,以及临时暂停规则的覆盖机制,目前正在开发中。


规则冲突排查

当你观察到与规则相矛盾的意外行为时,请遵循以下调试策略:

第 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

修复示例:

- 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. 渐进式细化:**为含糊的规则增加具体性

调试规则冲突时,逐条临时禁用规则,以隔离出导致意外行为的那条规则。

修改前:

- Use appropriate error handling

修改后:

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

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

编写规则的最佳实践

具体且指令明确:

  • 使用清晰、祈使的语言("始终使用……"、"绝不……"、"优先……")
  • 避免含糊的措辞("尽量……" → "始终……")
  • 准确说明你想要什么,而非你不想要什么

推荐:

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

避免:

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

逻辑化组织:

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

保持规则可维护:

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

优先排列重要规则:

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

测试规则有效性:

  • 验证 Verdent 在实践中是否遵循规则
  • 开启新对话以测试规则应用
  • 根据智能体的实际行为细化规则

平衡细节与灵活性:

  • 过于具体 → 行为僵化、无法适应
  • 过于含糊 → 行为不一致
  • 力求清晰指引,同时为因地制宜的决策留出空间

团队考量(AGENTS.md):

  • 让团队参与规则的制定
  • 为不直观的规则记录其理由
  • 让团队规则聚焦于共享标准,而非个人偏好

参见