Systèmes de règles et orientation du comportement

Les fichiers de règles sont des documents Markdown qui définissent comment Verdent se comporte et répond pendant les sessions de codage. Ils orientent le comportement de l'agent IA, le formatage des sorties, la prise de décision et le respect des standards du projet.

Objectif : Les règles vous permettent de personnaliser le comportement de Verdent sans modifier le code ou les paramètres. Elles établissent des conventions de codage, des modèles préférés, un style de communication et des préférences d'exécution des tâches qui persistent entre les sessions.

Fonctionnement des règles : Verdent se réfère en continu aux fichiers de règles pendant les conversations, en appliquant les directives à la génération de code, à l'analyse, à la documentation et à la prise de décision. Les règles influencent chaque réponse de l'agent pour garantir la cohérence avec les préférences de l'utilisateur.

Trois catégories :

• Préférences globales (VERDENT.md) - Style de codage personnel, préférences de langue
• Standards spécifiques au projet (AGENTS.md) - Conventions d'équipe, modèles architecturaux
• Personnalisation des plans (Plan.md) - Format et contenu de sortie du Plan Mode

Priorité des règles : En cas de conflit, Verdent applique la priorité suivante : AGENTS.md (la plus élevée) → VERDENT.md (moyenne) → valeurs par défaut (la plus basse)

Règles utilisateur (VERDENT.md)

VERDENT.md définit des préférences globales qui s'appliquent à tous les projets et sessions. Il établit le style de codage personnel, les outils préférés, les préférences de communication et les comportements par défaut.

Emplacement et portée

Emplacement du fichier : ~/.verdent/VERDENT.md

Portée : Globale à tous les projets

Accès :

• Paramètres → Règles → Règles utilisateur
• Édition directe du fichier à ~/.verdent/VERDENT.md

Prise d'effet des modifications : Les règles s'appliquent immédiatement dans les nouvelles conversations et influencent les réponses de la conversation en cours.

Cas d'usage

Format et syntaxe

VERDENT.md utilise un format Markdown simple avec des puces ou des listes numérotées.

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

Style de rédaction :

• Utilisez un langage clair et directif ("Toujours utiliser...", "Préférer...", "Ne jamais...")
• Organisez en sections logiques avec des titres
• Puces pour chaque règle individuelle
• Soyez précis sur le comportement souhaité

Exemples par type de développeur

# 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

Comment créer et modifier

Règles de projet (AGENTS.md)

AGENTS.md définit des règles spécifiques au projet qui contrôlent le comportement de l'agent pour le projet en cours. Il établit les standards de codage de l'équipe, les modèles architecturaux, les exigences de test et les flux de travail de développement propres au projet.

Emplacement et portée

Emplacement du fichier : Répertoire racine du projet

Portée : Le projet en cours uniquement

Contrôle de version : Peut être commité dans git pour un partage à l'échelle de l'équipe

Accès :

• Paramètres → Règles → Règles de projet
• Édition directe à <project-root>/AGENTS.md

Cas d'usage

Collaboration en équipe : AGENTS.md est stocké à la racine du projet et peut être commité dans le contrôle de version, garantissant que tous les membres de l'équipe travaillent avec un comportement d'agent cohérent.

Format et syntaxe

AGENTS.md utilise un format Markdown avec des sections structurées et des puces, semblable à VERDENT.md mais axé sur les exigences propres au projet.

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

Style de rédaction :

• Langage impératif et directif
• Organisé par domaine de flux de travail (développement, tests, déploiement)
• Commandes et procédures spécifiques
• Standards à l'échelle de l'équipe, pas des préférences personnelles

Exemples par type de projet

# 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

Différences avec VERDENT.md

Portée :

• VERDENT.md : Préférences personnelles pour tous les projets
• AGENTS.md : Standards d'équipe pour un projet spécifique uniquement

Priorité :

• AGENTS.md : Priorité plus élevée - remplace les règles utilisateur pour la cohérence du projet
• VERDENT.md : Priorité plus basse - s'applique en l'absence de conflit avec une règle de projet

Axe du contenu :

• VERDENT.md : Style de codage individuel, préférences de communication, outils personnels
• AGENTS.md : Conventions d'équipe, architecture du projet, flux de travail partagés, pile technologique

Contrôle de version :

• VERDENT.md : Non partagé - reste sur la machine de l'individu
• AGENTS.md : Commité dans git - partagé avec toute l'équipe

Stockage :

• VERDENT.md : ~/.verdent/VERDENT.md (global)
• AGENTS.md : Répertoire racine du projet (spécifique au projet)

Exemple de résolution de conflit :

VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)

Quand utiliser lequel :

• VERDENT.md : Préférences personnelles que vous souhaitez appliquer à tous les projets
• AGENTS.md : Standards que toute l'équipe doit suivre pour ce projet

Règles de plan (Plan.md)

Plan.md personnalise le contenu et le format des plans générés en Plan Mode. Il contrôle le niveau de détail des plans, les sections incluses, les préférences de formatage et les informations affichées.

Emplacement et portée

Emplacement du fichier : ~/.verdent/plan_settings.json

Portée : Globale à tous les projets

Application : Uniquement appliqué pendant le Plan Mode lors de la génération de plans

Accès :

• Paramètres → Règles → Règles de plan
• Édition directe du fichier à ~/.verdent/plan_settings.json

Cas d'usage

Format et syntaxe

Plan.md utilise un format Markdown avec des sections décrivant la structure et le contenu de plan souhaités.

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

Exemples par style de planification

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

Quand les règles de plan sont-elles appliquées ?

Application des règles de plan :

• Moment : Uniquement appliquées pendant le Plan Mode lors de la génération de plans
• Portée : Contrôle le format et le contenu du plan, pas la génération de code
• Indépendance : N'entre pas en conflit avec VERDENT.md ou AGENTS.md

Application des autres types de règles :

• VERDENT.md : Appliqué en continu dans tous les modes (Agent, Plan, Chat)
• AGENTS.md : Appliqué en continu dans tous les modes pour un comportement spécifique au projet

Exemple d'interaction :

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

Comportement spécifique au mode :

• Agent Mode : VERDENT.md + AGENTS.md appliqués (pas de plan_rules.md)
• Plan Mode : VERDENT.md + AGENTS.md + Plan.md tous appliqués
• Chat Mode : VERDENT.md + AGENTS.md appliqués (pas de Plan.md)

Priorité des règles et résolution de conflits

En cas de conflit entre règles, Verdent applique une priorité pour garantir un comportement cohérent.

Ordre de priorité

1. Règles de projet (AGENTS.md) - Priorité la plus élevéeLes règles spécifiques au projet remplacent les préférences globales. Les standards d'équipe ont priorité sur les préférences individuelles pour assurer la cohérence.

2. Règles utilisateur (VERDENT.md) - Priorité moyenneLes préférences globales s'appliquent lorsqu'aucune règle spécifique au projet n'est en conflit.

3. Comportement par défaut - Priorité la plus basseLes valeurs par défaut intégrées de Verdent s'appliquent lorsqu'aucune règle n'est spécifiée.

Exemple de résolution de conflit :

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)

Règles de plan : Plan.md s'applique de manière indépendante pendant le Plan Mode et n'entre pas en conflit avec les règles utilisateur/projet. Il contrôle le format du plan, tandis que VERDENT.md et AGENTS.md contrôlent le style de code au sein du plan.

Résolution des problèmes de conflits de règles

Lorsque vous observez un comportement inattendu qui contredit une règle, suivez cette stratégie de débogage :

Étape 1 : Identifier le conflit

1. Observez le comportement inattendu qui contredit une règle
2. Vérifiez quelles règles pourraient s'appliquer à la situation
3. Recherchez les contradictions entre les fichiers de règles

Étape 2 : Vérifier la priorité des règles

AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)

Les règles de projet remplacent les préférences personnelles.

Étape 3 : Tester isolément

Désactiver VERDENT.md : Renommez ou videz temporairement le fichier, testez si le conflit se résout

Tester sans AGENTS.md : Travaillez dans le projet sans AGENTS.md pour isoler le comportement des règles utilisateur

Nouvelle conversation : Démarrez une session fraîche pour éliminer l'influence du contexte de conversation

Scénarios de conflit courants

Scénario 1 : Conflit de formatage

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

Scénario 2 : Règles contradictoires dans le même fichier

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies

Exemple de correction :

- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

Scénario 3 : Règle trop vague

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

Stratégie de débogage

1. Test explicite : Demandez à Verdent "Quelle règle suis-tu pour [comportement spécifique] ?"

Exemple :

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. Raffinement progressif : Ajoutez de la précision aux règles ambiguës

Avant :

- Use appropriate error handling

Après :

- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)

3. Marqueurs de priorité : Utilisez "CRITIQUE :" ou "REQUIS :" pour les règles non négociables

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

Bonnes pratiques pour la rédaction des règles

Être précis et directif :

• Utilisez un langage clair et impératif ("Toujours utiliser...", "Ne jamais...", "Préférer...")
• Évitez les formulations ambiguës ("Essayer de..." → "Toujours...")
• Indiquez exactement ce que vous voulez, pas ce que vous ne voulez pas

Bon exemple :

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

À éviter :

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

Organiser logiquement :

• Regroupez les règles connexes sous des titres de section
• Séparez les préoccupations (style, tests, documentation, sécurité)
• Utilisez une structure cohérente entre les fichiers de règles

Garder les règles maintenables :

• Rédigez des règles concises (un concept par puce)
• Révisez et mettez à jour les règles au fil de l'évolution du projet
• Supprimez rapidement les règles obsolètes

Prioriser les règles importantes :

• Placez les règles critiques en premier dans chaque section
• Utilisez l'accentuation pour les standards non négociables ("NE JAMAIS commiter d'identifiants")
• Concentrez-vous sur les règles qui préviennent les bugs ou les problèmes de sécurité

Tester l'efficacité des règles :

• Vérifiez que Verdent suit les règles en pratique
• Démarrez une nouvelle conversation pour tester l'application des règles
• Affinez les règles en fonction du comportement réel de l'agent

Équilibrer précision et flexibilité :

• Trop précis → Comportement rigide qui ne s'adapte pas
• Trop vague → Comportement incohérent
• Visez des consignes claires laissant de la place à des décisions adaptées au contexte

Considérations d'équipe (AGENTS.md) :

• Impliquez l'équipe dans la création des règles
• Documentez la justification des règles non évidentes
• Concentrez les règles d'équipe sur les standards partagés, pas les préférences personnelles

Voir aussi