Rule Systems & Behavior Guidance

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 (VERDENT.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) → VERDENT.md (medium) → defaults (lowest)

User Rules (VERDENT.md)

VERDENT.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/VERDENT.md

Scope: Global to all projects

Access:

• Settings → Rules → User Rules
• Direct file edit at ~/.verdent/VERDENT.md

Changes Take Effect: Rules apply immediately in new conversations and influence current conversation responses.

Use Cases

Format and Syntax

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

# 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

# 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

# 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

# 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

# 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

How to Create and Edit

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

Format and Syntax

AGENTS.md uses Markdown format with structured sections and bullet points, similar to VERDENT.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

# 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

# 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

# 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

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

# 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

Differences from VERDENT.md

Scope:

• VERDENT.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
• VERDENT.md: Lower precedence - applies when no project rule conflicts

Content Focus:

• VERDENT.md: Individual coding style, communication preferences, personal tools
• AGENTS.md: Team conventions, project architecture, shared workflows, technology stack

Version Control:

• VERDENT.md: Not shared - stays on individual's machine
• AGENTS.md: Committed to git - shared with entire team

Storage:

• VERDENT.md: ~/.verdent/VERDENT.md (global)
• AGENTS.md: Project root directory (project-specific)

Example Conflict Resolution:

VERDENT.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:

• VERDENT.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

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

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

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

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

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

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

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 VERDENT.md or AGENTS.md

Other Rule Types Application:

• VERDENT.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. 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

Mode-Specific Behavior:

• Agent Mode: VERDENT.md + AGENTS.md applied (no plan_rules.md)
• Plan Mode: VERDENT.md + AGENTS.md + Plan.md all applied
• Chat Mode: VERDENT.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 (VERDENT.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:

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 Rules: Plan.md applies independently during Plan Mode and doesn't conflict with user/project rules. It controls plan format, while VERDENT.md and AGENTS.md control code style within the plan.

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) → VERDENT.md (medium) → defaults (lowest)

Project rules override personal preferences.

Step 3: Test in Isolation

Disable VERDENT.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

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

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 VERDENT.md preference for 2-space indentation."

2. Incremental Refinement: Add specificity to ambiguous rules

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