Extensibilité et personnalisation

Ce que vous allez apprendre

Comment personnaliser et étendre Verdent for VS Code à l'aide de trois méthodes d'extensibilité puissantes : les sous-agents personnalisés, les systèmes de règles et l'intégration MCP.

Vue d'ensemble de l'extensibilité

Verdent for VS Code propose trois méthodes principales pour étendre ses capacités et personnaliser son comportement :

1. Sous-agents personnalisés - Créez des agents IA spécialisés pour des tâches propres à un domaine
2. Système de règles - Guidez le comportement via VERDENT.md, AGENTS.md et plan_rules.md
3. Intégration MCP - Connectez des outils et services externes via le Model Context Protocol

Chaque méthode répond à des besoins de personnalisation différents et peut être combinée pour une optimisation complète du flux de travail.

Méthode 1 : Sous-agents personnalisés

Vue d'ensemble

Les sous-agents personnalisés sont des agents IA spécialisés dotés de prompts système dédiés, de politiques d'invocation et d'une expertise propre à une tâche. Ils étendent les sous-agents intégrés de Verdent (@Verifier, @Explorer, @Code-reviewer) avec des capacités propres au projet.

Emplacement de stockage : ~/.verdent/subagents/

Création de sous-agents personnalisés

Structure de fichier :

---
name: subagent-name
description: One-line purpose description
---
# System Prompt

[Behavior definition, personality, task interpretation approach]

Invocation policy (strict|flexible): Policy description

When to use:
- Scenario 1
- Scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2

Méthodes de création :

Méthode 1 : Menu des paramètres

1. Paramètres → Sous-agents
2. « Créer un nouveau sous-agent »
3. Définissez le nom, la description, le prompt système
4. Configurez la politique d'invocation
5. Enregistrez dans ~/.verdent/subagents/

Méthode 2 : Création directe de fichier

1. Accédez à ~/.verdent/subagents/
2. Créez un fichier markdown (par exemple security-reviewer.md)
3. Ajoutez le frontmatter YAML
4. Rédigez le prompt système et les consignes d'utilisation

Cas d'usage des sous-agents personnalisés

Expertise propre à un domaine :

• Calculs financiers : conformité fiscale, réglementations financières
• Conformité HIPAA en santé : normes de traitement des données patients
• Cryptographie : bonnes pratiques de mise en œuvre de la sécurité

Flux de travail propres à l'équipe :

• Vérificateurs de style de code : normes de codage de l'équipe au-delà des règles du linter
• Cohérence de la documentation : garantir que la documentation suit les modèles de l'équipe
• Auditeurs de dépendances : surveiller les packages tiers par rapport aux listes approuvées

Spécialistes de la pile technologique :

• Optimiseurs de performance React : identifier les rendus inutiles
• Optimiseurs de requêtes SQL : analyser et améliorer les performances de la base de données
• Réviseurs de configuration Docker : valider les pratiques de conteneurisation

Assurance qualité :

• Analyseurs de couverture de tests : identifier les chemins de code non testés
• Réviseurs de gestion des erreurs : garantir une gestion exhaustive des exceptions
• Vérificateurs des normes de journalisation : valider les pratiques de journalisation

Exemple : générateur de documentation API

---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation

Utilisation :

@api-documenter document the /api/users endpoints

Exemple : réviseur de migration de base de données

---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt

You are a database migration safety specialist.

Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables

Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures

When NOT to use:
- Schema design from scratch
- Query optimization

Politiques d'invocation

Politique stricte :

• Le sous-agent ne s'exécute que lorsqu'il est explicitement demandé via une mention @-
• L'utilisateur garde un contrôle total sur l'invocation
• Idéal pour les sous-agents spécialisés, utilisés occasionnellement

Politique flexible :

• Permet une invocation automatique basée sur la détection du type de tâche
• L'agent principal route automatiquement les tâches correspondantes
• Idéal pour les sous-agents fréquemment utilisés et bien définis

Méthode 2 : Système de règles

Vue d'ensemble

Les fichiers de règles sont des documents Markdown qui guident le comportement de Verdent, le formatage des sorties et la prise de décision, sans modification de code. Trois types de règles offrent une personnalisation complète :

Priorité des règles

En cas de conflit :

1. AGENTS.md (la plus élevée) - Les règles du projet remplacent les préférences de l'utilisateur
2. VERDENT.md (moyenne) - Appliquée en l'absence de conflit avec le projet
3. Comportement par défaut (la plus basse) - Comportements par défaut intégrés de Verdent

Exemple de conflit :

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

VERDENT.md (préférences globales)

Objectif : Style de codage et préférences personnelles applicables à tous les projets

Exemple :

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases
- Include return types on all functions

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

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

Accès : Paramètres → Règles → Règles utilisateur

AGENTS.md (règles du projet)

Objectif : Normes de codage à l'échelle de l'équipe et conventions propres au projet

Exemple :

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to navigate
- Run `pnpm install --filter <project_name>` for dependencies
- Check package.json name field for correct package name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- 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

Accès : Répertoire racine du projet (sous contrôle de version)

plan_rules.md (personnalisation du plan)

Objectif : Contrôler le format de sortie et le niveau de détail de Plan Mode

Exemple :

# Plan Rules

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

Accès : Paramètres → Règles → Règles de plan

Bonnes pratiques de rédaction des règles

Soyez précis et directif :

✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"

Organisez de façon logique :

• Regroupez les règles liées sous des en-têtes de section
• Séparez les préoccupations (style, tests, documentation, sécurité)
• Utilisez une structure cohérente entre les fichiers

Priorisez les règles critiques :

• Placez les règles importantes en premier dans chaque section
• Utilisez l'emphase pour les normes non négociables : **NEVER** commit credentials
• Concentrez-vous sur la prévention des bugs et la sécurité

Testez l'efficacité :

• Démarrez une nouvelle conversation pour vérifier l'application de la règle
• Affinez les règles en fonction du comportement réel de l'agent
• Mettez à jour au fur et à mesure de l'évolution du projet

Méthode 3 : Intégration MCP

Vue d'ensemble

Le Model Context Protocol (MCP) étend Verdent en connectant des outils, sources de données et services externes. Les serveurs MCP font office de passerelles entre Verdent et les systèmes externes.

Configuration : ~/.verdent/mcp.json via Paramètres → Serveurs MCP

Capacités de MCP

Accès aux systèmes externes :

• Outils de requête de base de données (PostgreSQL, MySQL, MongoDB)
• APIs de services cloud (AWS, Azure, GCP)
• Gestion de projet (Jira, Linear, Asana)
• Pipelines CI/CD (Jenkins, GitHub Actions)
• Services de supervision (Datadog, New Relic)

Développement d'outils personnalisés : Créez des serveurs MCP pour des systèmes propriétaires :

• Intégrations API internes
• Passerelles vers des systèmes existants
• Sources de données spécialisées
• Outils d'automatisation de flux de travail

MCP vs sous-agents personnalisés vs règles

Exemple : combiner les trois méthodes

Scénario : Équipe de développement full-stack avec exigences de conformité strictes

Sous-agent personnalisé :

---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]

AGENTS.md (règles du projet) :

## Security Standards
- All API endpoints must validate inputs
- Never log PII or credentials
- Encrypt sensitive data at rest and in transit

## Compliance
- Run @compliance-auditor before all PRs
- Document data retention policies in code comments
- Include audit trails for data access

Intégration MCP :

• Serveur MCP de base de données de conformité : vérifie les opérations par rapport aux règles de conformité
• Serveur MCP de journal d'audit : enregistre tous les accès aux données sensibles

Flux de travail :

User: "Create endpoint for user profile updates"
Verdent: [Applies AGENTS.md rules]
         [Generates secure endpoint with validation]
         [Automatically invokes @compliance-auditor]
         [Uses MCP to log operation in audit system]
         Result: Compliant, secure, audited endpoint

Bonnes pratiques d'extensibilité

Commencez simplement, montez en puissance progressivement

Adoption progressive :

1. Phase 1 : Commencez par des règles de base (VERDENT.md ou AGENTS.md)
2. Phase 2 : Ajoutez des sous-agents personnalisés pour les tâches spécialisées répétitives
3. Phase 3 : Intégrez MCP pour les connexions à des systèmes externes

Combinez les méthodes de façon stratégique

Exemples de synergie :

Règles + sous-agents :

• AGENTS.md précise quand invoquer des sous-agents personnalisés
• Les règles garantissent que les recommandations des sous-agents sont suivies

Règles + MCP :

• AGENTS.md définit quels serveurs MCP sont approuvés pour l'utilisation
• Les règles précisent quand l'accès à des données externes est requis

Sous-agents + MCP :

• Un sous-agent personnalisé utilise les outils MCP pour accéder à des systèmes externes
• Le sous-agent interprète les résultats MCP avec une expertise spécialisée

Documentez les personnalisations

Documentation d'équipe : Pour les sous-agents personnalisés et les règles de projet (AGENTS.md) :

• Documentez la logique des règles ou sous-agents non évidents
• Fournissez des exemples d'utilisation correcte
• Incluez des guides de dépannage
• Placez sous contrôle de version avec le code

Documentation personnelle : Pour VERDENT.md et les sous-agents personnels :

• Commentez les règles complexes en expliquant le raisonnement
• Gardez les règles organisées et à jour
• Supprimez rapidement les règles obsolètes

Testez rigoureusement

Processus de validation :

1. Créez la personnalisation (sous-agent/règle/configuration MCP)
2. Démarrez une nouvelle conversation pour tester
3. Vérifiez que le comportement correspond aux attentes
4. Affinez en fonction des résultats
5. Documentez les modèles réussis

Scénarios de test courants :

• Le sous-agent s'invoque-t-il automatiquement lorsque prévu ?
• Les règles du projet remplacent-elles correctement les règles utilisateur ?
• Le serveur MCP se connecte-t-il et exécute-t-il les opérations ?
• Les méthodes combinées interagissent-elles sans conflit ?

Dépannage de l'extensibilité

Problèmes de sous-agents personnalisés

Le sous-agent ne s'invoque pas :

• Vérifiez la politique d'invocation (la politique stricte requiert une mention @- explicite)
• Vérifiez que les consignes « Quand l'utiliser » correspondent à votre demande
• Assurez-vous que le fichier se trouve dans le répertoire ~/.verdent/subagents/
• Vérifiez la syntaxe du frontmatter YAML

Comportement inattendu du sous-agent :

• Revoyez la clarté du prompt système
• Affinez les consignes « Quand l'utiliser » et « Quand ne pas l'utiliser »
• Testez avec une mention @- explicite pour isoler le comportement
• Itérez sur le prompt système en fonction des résultats

Conflits de règles

La règle n'est pas appliquée :

• Vérifiez la priorité des règles (AGENTS.md > VERDENT.md)
• Vérifiez que le fichier se trouve au bon emplacement
• Démarrez une nouvelle conversation pour tester une application fraîche
• Rendez les règles plus précises et directives

Comportement inattendu :

• Recherchez des règles contradictoires dans le même fichier
• Vérifiez si les règles sont trop vagues
• Vérifiez que le bon fichier de règles est modifié
• Utilisez un langage explicite (« Toujours », « Jamais », « Préférer »)

Problèmes d'intégration MCP

Échecs de connexion :

• Vérifiez la syntaxe de mcp.json
• Vérifiez les identifiants d'authentification
• Assurez-vous que le serveur MCP est en cours d'exécution et accessible
• Validez la connectivité réseau

Problèmes d'invocation d'outils :

• Confirmez que le serveur MCP expose les outils attendus
• Vérifiez les formats de paramètres des outils
• Consultez les journaux du serveur MCP pour repérer les erreurs
• Testez le serveur MCP indépendamment

Voir aussi