规则系统与行为引导
通过规则系统控制 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 行以内
- 在展示代码后提供简短解释
- 除非你明确要求,否则避免冗长注释
如何创建与编辑
推荐大多数用户使用
- 点击 Verdent 顶部栏的 Settings 按钮
- 从下拉菜单中选择 Rules
- 选择 User Rules
- 文件在 VS Code 编辑器中打开
- 使用 Markdown 格式编辑
- 保存文件(
Cmd+S/Ctrl+S)
此方法会自动定位文件并在你的默认编辑器中打开它。
推荐高级用户使用
- 导航到
~/.verdent/VERDENT.md - 用任意文本编辑器打开
- 编辑 Markdown 内容
- 保存更改
如果你偏好直接处理配置文件,此方法更快。
项目规则(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 test、npm 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 步:识别冲突
- 观察到与规则相矛盾的意外行为
- 检查哪些规则可能适用于该情况
- 查找规则文件之间的矛盾
第 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):
- 让团队参与规则的制定
- 为不直观的规则记录其理由
- 让团队规则聚焦于共享标准,而非个人偏好