Skip to main content
Rule files are Markdown documents that define how Verdent behaves and responds during coding sessions. They guide the AI agent’s behavior, output formatting, decision-making, and adherence to project standards. Purpose: Rules allow you to customize Verdent’s behavior without changing code or settings. They establish coding conventions, preferred patterns, communication style, and task execution preferences that persist across sessions. How Rules Work: Verdent continuously references rule files during conversations, applying guidelines to code generation, analysis, documentation, and decision-making. Rules influence every agent response to ensure consistency with user preferences. Three Categories:
  • Global preferences (user_rules.md) - Personal coding style, language preferences
  • Project-specific standards (AGENTS.md) - Team conventions, architectural patterns
  • Plan customization (Plan.md) - Plan Mode output format and content
Rule Precedence: When rules conflict, Verdent applies precedence: AGENTS.md (highest) → user_rules.md (medium) → defaults (lowest)

​
User Rules (user_rules.md)

user_rules.md defines global preferences that apply across all projects and sessions. It establishes personal coding style, preferred tools, communication preferences, and default behaviors.

​
Location and Scope

File Location: ~/.verdent/user_rules.md Scope: Global to all projects Access:
  • Settings → Rules → User Rules
  • Direct file edit at ~/.verdent/user_rules.md
Changes Take Effect: Rules apply immediately in new conversations and influence current conversation responses.

​
Use Cases

  • Coding Preferences
  • Output Language
  • Code Comments
  • Documentation
  • Communication
Coding Preferences
  • Indentation style (2-space, 4-space, tabs)
  • Naming conventions (camelCase, snake_case, PascalCase)
  • Preferred language features (ES6+, TypeScript strict mode, type hints)
Define your personal coding style and conventions applied across all projects.

​
Format and Syntax

user_rules.md uses plain Markdown format with bullet points or numbered lists. Structure: 
# 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
Writing Style:
  • Use clear, directive language (“Always use…”, “Prefer…”, “Never…”)
  • Organize into logical sections with headers
  • Bullet points for individual rules
  • Be specific about desired behavior

​
Examples by Developer Type

  • TypeScript
  • Python Data Science
  • Full-Stack JS
  • Multilingual
  • Minimalist
# 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
Application: When you ask Verdent to create a new React component, it will automatically:
  • Use TypeScript with strict mode
  • Create a named export (not default)
  • Add TSDoc comments with @param/@returns tags
  • Organize imports by category

​
How to Create and Edit

  • Settings Menu
  • Direct File Edit
Recommended for most users
  1. Click Settings button in Verdent top bar
  2. Select Rules from dropdown
  3. Choose User Rules
  4. File opens in VS Code editor
  5. Edit using Markdown format
  6. Save file (Cmd+S / Ctrl+S)
This method automatically locates the file and opens it in your default editor.

​
Project Rules (AGENTS.md)

AGENTS.md defines project-specific rules that control agent behavior for the current project. It establishes team coding standards, architectural patterns, testing requirements, and development workflows specific to the project.

​
Location and Scope

File Location: Project root directory Scope: Current project only Version Control: Can be committed to git for team-wide sharing Access:
  • Settings → Rules → Project Rules
  • Direct edit at <project-root>/AGENTS.md

​
Use Cases

  • Team Conventions
  • Architecture
  • Testing
  • Workflows
  • Technology
Team ConventionsShared coding standards all team members follow:
  • Consistent indentation across team
  • Naming conventions for components/functions
  • File organization patterns
Enforce consistent coding style across the entire development team.
Team Collaboration: AGENTS.md is stored in the project root and can be committed to version control, ensuring all team members work with consistent agent behavior.
Share AGENTS.md with your team via version control to ensure consistent AI behavior across all team members.

​
Format and Syntax

AGENTS.md uses Markdown format with structured sections and bullet points, similar to user_rules.md but focused on project-specific requirements. Structure: 
# 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
Writing Style:
  • Imperative, directive language
  • Organized by workflow area (dev, testing, deployment)
  • Specific commands and procedures
  • Team-wide standards, not personal preferences

​
Examples by Project Type

  • Monorepo
  • React/TypeScript
  • Backend API
  • Mobile App
  • Python Django
# 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
Application: When working on this monorepo, Verdent will:
  • Use turbo commands for navigation and testing
  • Format PR titles with project name prefix
  • Run lint and test commands before suggesting commits

​
Differences from user_rules.md

Scope:
  • user_rules.md: Personal preferences across all projects
  • AGENTS.md: Team standards for specific project only
Priority:
  • AGENTS.md: Higher precedence - overrides user_rules for project consistency
  • user_rules.md: Lower precedence - applies when no project rule conflicts
Content Focus:
  • user_rules.md: Individual coding style, communication preferences, personal tools
  • AGENTS.md: Team conventions, project architecture, shared workflows, technology stack
Version Control:
  • user_rules.md: Not shared - stays on individual’s machine
  • AGENTS.md: Committed to git - shared with entire team
Storage:
  • user_rules.md: ~/.verdent/user_rules.md (global)
  • AGENTS.md: Project root directory (project-specific)
Example Conflict Resolution: 
user_rules.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)
When to Use Which:
  • user_rules.md: Personal preferences you want across all projects
  • AGENTS.md: Standards the entire team must follow for this project

​
Plan Rules (Plan.md)

Plan.md customizes the content and format of plans generated in Plan Mode. It controls plan detail level, sections included, formatting preferences, and information displayed.

​
Location and Scope

File Location: ~/.verdent/plan_settings.json Scope: Global to all projects Application: Only applied during Plan Mode when generating plans Access:
  • Settings → Rules → Plan Rules
  • Direct file edit at ~/.verdent/plan_settings.json

​
Use Cases

  • Plan Structure
  • Detail Level
  • Format
  • Information
Plan StructureDefine sections to include:
  • Summary, prerequisites, steps, verification
  • Risk assessment, rollback procedures
  • Time estimates, critical path
Control what sections and information appear in every plan.

​
Format and Syntax

Plan.md uses Markdown format with sections describing desired plan structure and content. Structure: 

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

​
Examples by Planning Style

  • Detailed Technical
  • High-Level Strategic
  • Time-Conscious
  • Risk-Focused
  • Team Collaboration
---
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)
Application: Plans will include:
  • Executive summary at the top
  • 20-30 minute task breakdowns
  • Specific file paths like src/components/Auth/Login.tsx
  • Function signatures like async function authenticateUser(credentials: UserCredentials): Promise<AuthResult>
  • Testing and rollback procedures

​
When Are Plan Rules Applied?

Plan Rules Application:
  • Timing: Only applied during Plan Mode when generating plans
  • Scope: Controls plan format and content, not code generation
  • Independence: Doesn’t conflict with user_rules.md or AGENTS.md
Other Rule Types Application:
  • user_rules.md: Continuously applied across all modes (Agent, Plan, Chat)
  • AGENTS.md: Continuously applied across all modes for project-specific behavior
Interaction Example: 
Plan Mode activated:
1. user_rules.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
Mode-Specific Behavior:
  • Agent Mode: user_rules.md + AGENTS.md applied (no plan_rules.md)
  • Plan Mode: user_rules.md + AGENTS.md + Plan.md all applied
  • Chat Mode: user_rules.md + AGENTS.md applied (no Plan.md)

​
Rule Precedence and Conflict Resolution

When rules conflict, Verdent applies precedence to ensure consistent behavior.

​
Precedence Order

1. Project Rules (AGENTS.md) - Highest Priority Project-specific rules override global preferences. Team standards take precedence over individual preferences for consistency. 2. User Rules (user_rules.md) - Medium Priority Global preferences apply when no project-specific rule conflicts. 3. Default Behavior - Lowest Priority Verdent’s built-in defaults apply when no rules are specified. Example Conflict Resolution: 
user_rules.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)
Plan Rules: Plan.md applies independently during Plan Mode and doesn’t conflict with user/project rules. It controls plan format, while user_rules.md and AGENTS.md control code style within the plan.
Plan Rules only affect Plan Mode output format—they don’t change how Verdent analyzes or implements solutions.
Remember precedence: AGENTS.md (highest) → user_rules.md (medium) → defaults (lowest). Project rules always win conflicts.
Detailed conflict resolution algorithms, mechanisms to view which rule is being applied during conflicts, and override mechanisms for temporary rule suspension are currently in development.

​
Troubleshooting Rule Conflicts

When you observe unexpected behavior that contradicts a rule, follow this debug strategy:

​
Step 1: Identify the Conflict

  1. Observe unexpected behavior that contradicts a rule
  2. Check which rules might apply to the situation
  3. Look for contradictions between rule files

​
Step 2: Check Rule Precedence

AGENTS.md (highest) → user_rules.md (medium) → defaults (lowest)
Project rules override personal preferences.

​
Step 3: Test in Isolation

Disable user_rules.md: Temporarily rename or clear file, test if conflict resolves Test without AGENTS.md: Work in project without AGENTS.md to isolate user_rules behavior New conversation: Start fresh session to eliminate conversation context influence

​
Common Conflict Scenarios

​
Scenario 1: Formatting Conflict

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

​
Scenario 2: Contradictory Rules in Same File

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies
Example fix: 
- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

​
Scenario 3: Rule Too Vague

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

​
Debug Strategy

1. Explicit Test: Ask Verdent “Which rule are you following for [specific behavior]?” Example: 
You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your user_rules.md preference for 2-space indentation."
2. Incremental Refinement: Add specificity to ambiguous rules
When debugging rule conflicts, temporarily disable rules one-by-one to isolate which rule causes unexpected behavior.
Before: 
- Use appropriate error handling
After: 
- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)
3. Priority Markers: Use “CRITICAL:” or “REQUIRED:” for non-negotiable rules 
## 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

​
Best Practices for Writing Rules

Be Specific and Directive:
  • Use clear, imperative language (“Always use…”, “Never…”, “Prefer…”)
  • Avoid ambiguous phrasing (“Try to…” → “Always…”)
  • State exactly what you want, not what you don’t want
Good: 
- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions
Avoid: 
- Try to use modern JavaScript features
- Add comments when necessary
Organize Logically:
  • Group related rules under section headers
  • Separate concerns (style, testing, documentation, security)
  • Use consistent structure across rule files
Keep Rules Maintainable:
  • Write concise rules (one concept per bullet)
  • Review and update rules as project evolves
  • Remove obsolete rules promptly
Prioritize Important Rules:
  • Place critical rules first in each section
  • Use emphasis for non-negotiable standards (“NEVER commit credentials”)
  • Focus on rules that prevent bugs or security issues
Test Rules Effectiveness:
  • Verify Verdent follows rules in practice
  • Start new conversation to test rule application
  • Refine rules based on actual agent behavior
Balance Detail and Flexibility:
  • Too specific → Rigid behavior that doesn’t adapt
  • Too vague → Inconsistent behavior
  • Aim for clear guidance with room for context-appropriate decisions
Team Considerations (AGENTS.md):
  • Involve team in rule creation
  • Document rationale for non-obvious rules
  • Keep team rules focused on shared standards, not personal preferences

​
See Also

Subagent Management

Create and manage specialized subagents for project-specific tasks

Best Practices: Prompts

Writing effective prompts to get the most from VerdentP