Controlling Verdent’s behavior through rule systems
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
VERDENT.md defines global preferences that apply across all projects and sessions. It establishes personal coding style, preferred tools, communication preferences, and default behaviors.
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…”)
# 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
# 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
Application:
When you ask Verdent to write data analysis code, it will:
Use pandas for data operations
Include type hints on all functions
Show DataFrame.head() and shape after transformations
Add inline comments documenting data assumptions
# 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
Application:
Verdent will:
Write modern JavaScript with ES6+ syntax
Use async/await instead of promise chains
Generate Jest tests targeting 80% coverage
Proactively identify performance and security concerns
# 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
Application:
All Verdent responses will be in French, with technical terms in English where appropriate. Code comments and documentation will follow your language preferences.
# 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
Application:
Verdent will:
Generate concise, self-documenting code
Keep functions under 20 lines
Provide brief explanations after showing code
Avoid verbose comments unless you explicitly request them
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.
State management approach (Redux, Context, Zustand)
API design patterns (REST, GraphQL)
Define the architectural decisions and patterns for the project.
Testing RequirementsExpected test coverage and frameworks:
Minimum coverage thresholds (80%, 90%)
Testing frameworks (Jest, pytest, Vitest)
Test file naming conventions
Establish testing standards and quality gates for the project.
Development WorkflowsBuild commands, deployment procedures, PR guidelines:
How to run tests (pnpm test, npm run test)
Build commands for specific packages
PR title format requirements
Document team workflows and development procedures.
Technology ConstraintsApproved libraries and framework versions:
Allowed dependencies
Framework version requirements
Platform support (iOS 14+, Android API 26+)
Control technology stack choices and maintain consistency.
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.
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)
# 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
# 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
Application:
All React components Verdent creates will:
Use functional components with hooks
Include TypeScript interfaces
Be placed in the correct directory
Include Jest tests targeting 80% coverage
# 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
Application:
When creating API endpoints, Verdent will:
Add input validation automatically
Use parameterized queries for database operations
Generate tests for both success and error cases
Avoid logging sensitive data
# 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)
Application:
Mobile app code will:
Support minimum platform versions
Use Redux Toolkit for state
Optimize images to WebP format
Use FlatList for performance on long lists
# 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
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.
Plan.md uses Markdown format with sections describing desired plan structure and content.Structure:
---name: Plan Rulesversion: 1.0.0last_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 Technicalversion: 1.0.0last_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
---name: High-Level Strategicversion: 1.0.0last_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"
Application:
Plans will be high-level, focusing on:
Strategic approach in 3-5 major phases
“Why” explanations over implementation details
Decision points and trade-offs
Success criteria without specific implementation
---name: Time-Consciousversion: 1.0.0last_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
Application:
Plans will include:
Each step with time estimate: “Create authentication middleware (45 minutes)”
Total duration: “Estimated total: 6 hours”
Parallel tasks marked: “Can be done in parallel with step 3”
Critical path bolded to show blocking operations
---name: Risk-Focusedversion: 1.0.0last_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
Application:
Each phase will include:
Risk assessment: “Risk: high (database migration on production)”
Mitigation: “Run migration on staging first, verify with test queries”
Rollback: “Revert migration with down script if issues occur”
---name: Team Collaborationversion: 1.0.0last_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
Application:
Plans will specify:
“Backend API (Backend Team): Create authentication endpoints”
“Integration point: Frontend team waits for API spec from backend”
“Review required: Security team review before merge”
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 plan2. AGENTS.md: "Follow project conventions" → Applied to approach3. 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)
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.
Plan Rules only affect Plan Mode output format. They don’t change how Verdent analyzes or implements solutions.
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.
Disable VERDENT.md:
Temporarily rename or clear file, test if conflict resolvesTest without AGENTS.md:
Work in project without AGENTS.md to isolate user_rules behaviorNew conversation:
Start fresh session to eliminate conversation context influence
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
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
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
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