Intelligence de codebase et graphe mémoire (`codebase-memory`)

Intelligence de codebase et graphe mémoire (codebase-memory)

Cette compétence définit les normes d'ingénierie, les procédures opérationnelles et les contrats d'utilisation d'outils pour explorer, rechercher et comprendre le code à l'aide du graphe de connaissances MCP codebase-memory.

---

Invariant central : le protocole index-d'abord

[!CRITICAL] INVARIANT INDEX-D'ABORD : La ré-indexation automatique en arrière-plan est définitivement désactivée (auto_watch = false) dans cet espace de travail pour éviter les à-coups disque, la surcharge de sérialisation zstd et les ralentissements système lors de l'édition active de fichiers.

Par conséquent, l'agent DOIT TOUJOURS vérifier la fraîcheur de l'index ou déclencher une ré-indexation à la demande (index_repository) avant d'exécuter des recherches dans le graphe de connaissances du code.

Chaque fois que vous devez trouver un symbole, comprendre un module, investiguer un bogue ou préparer un refactoring, exécutez la Porte Index-d'abord avant d'effectuer des appels de recherche.

---

Hiérarchie des outils : Graphe d'abord, Grep ensuite

Lors de la découverte, de la navigation ou de la révision du code, respectez strictement cette hiérarchie de priorité :

flowchart TD
    Tâche[Découverte / Investigation de code] --> Fraîcheur{Index frais ?}
    Fraîcheur -->|Non / Inconnu / Après modifications| Sync[index_repository mode: 'fast' ou 'moderate']
    Fraîcheur -->|Oui| Stratégie{Type de requête}
    Sync --> Stratégie

    Stratégie -->|Symbole / Fonction / Interface| RechercheGraphe[search_graph BM25 ou semantic_query]
    Stratégie -->|Appelants / Appelés / Dépendances| TraceChemin[trace_path callers / callees]
    Stratégie -->|Rayon d'impact des modifications| DetecterModifs[detect_changes diff vers ensemble d'impact]
    Stratégie -->|Code source exact| ObtenirExtrait[get_code_snippet lignes précises]
    Stratégie -->|Couches système & Modules centraux| ObtenirArchitecture[get_architecture nœuds de haute centralité]
    Stratégie -->|Chaînes littérales / Non-code / Ressources| RetourGrep[search_code ou run_command grep]

1. search_graph > grep textuel : Recherche structurée BM25 avec découpage camelCase, boost d'étiquettes (Fonctions +10, Routes +8, Interfaces +5) et plongements vectoriels.
2. trace_path > navigation manuelle de fichiers : Résolution instantanée des chaînes d'appelants et d'appelés multi-sauts.
3. get_code_snippet > view_file sur des fichiers volumineux : Récupère la déclaration exacte et le corps d'un symbole avec les lignes de début/fin et les compteurs d'appels sans gonfler le contexte de l'agent.
4. detect_changes > inspection manuelle des diffs : Mappe les diffs git (since: "HEAD~1", base_branch: "main") directement à leur rayon d'impact transitif.
5. Retour Grep : Utilisez search_code ou run_command (git grep, rg) UNIQUEMENT pour :
   • Texte littéral dans le Markdown (.md), la configuration (.json) ou les feuilles de style (.css).
   • Plages de lignes explicitement signalées sous parse_partial dans index_status.
   • Fichiers exclus par conception via .cbmignore.

---

Workflow opérationnel standard

Étape 1 : Porte de synchronisation de l'index (Première action obligatoire)

Avant d'émettre des requêtes de recherche, déterminez le nom du projet et assurez-vous que le graphe reflète les modifications récentes du système de fichiers.

1. Identifier le nom du projet : Appelez list_projects si l'identifiant du projet est inconnu :

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   (Dans cet espace de travail, le nom de projet dérivé est "D-Scripts-aminwebsite".)

2. Vérifier l'état ou rafraîchir l'index : Si des fichiers ont été créés ou modifiés pendant la session, appelez index_repository :

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • Sélection du mode :
     • mode: "fast" : Analyse incrémentielle, fichiers filtrés, pas de plongements vectoriels sémantiques. Rapide et léger pour le développement actif.
     • mode: "moderate" : Analyse incrémentielle + plongements de similarité vectorielle pour le pontage de concepts en langage naturel.
   • Inspection de la couverture : Vérifiez la réponse pour :
     • parse_partial : Fichiers où certaines plages de lignes avaient des erreurs d'analyse.
     • skipped : Fichiers complètement ignorés (par exemple, binaires ou surdimensionnés).

---

Étape 2 : Découverte des symboles et de la structure (search_graph)

Trouvez les fonctions, interfaces, types, composants et définitions de routes.

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• Découverte en langage naturel : Utilisez query pour la recherche par mot-clé / BM25 (par exemple "transition de thème de basculement", "routage de locale").
• Motif de nom exact : Utilisez name_pattern pour le filtrage par regex (par exemple ".*Provider.*", ".*Skeleton.*").
• Recherche conceptuelle sémantique : Utilisez semantic_query: ["i18n", "langue", "changement"] (nécessite un tableau de chaînes) pour combler les lacunes de vocabulaire.
• Gestion de la troncature (has_more) : Si la réponse renvoie "has_more": true, paginez en ajoutant "offset": <décalage_actuel + limite>.

---

Étape 3 : Traçage des relations et rayon d'impact

Ne modifiez jamais une fonction ou une interface sans inspecter ses dépendants.

1. Tracer les appelants et les appelés (trace_path) :

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound" : Identifie tous les appelants qui dépendent de cette fonction (rayon d'impact).
   • direction: "outbound" : Identifie les fonctions aval appelées par ce symbole.
   • direction: "both" : Chaîne d'appel bidirectionnelle complète.

2. Mapper l'ensemble d'impact du diff Git (detect_changes) : Avant de commiter ou de finaliser des modifications, évaluez le rayon d'impact :

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

Étape 4 : Récupération chirurgicale du code (get_code_snippet)

Au lieu de consommer du contexte en visualisant des fichiers entiers avec view_file, récupérez les implémentations exactes des symboles :

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

La réponse inclut :

• Les start_line et end_line exactes
• Le code source propre du symbole
• Les compteurs d'appelants et d'appelés directs

---

Étape 5 : Exploration de l'architecture haut niveau (get_architecture)

Lors de l'orientation dans un nouveau sous-système ou de la compréhension de la topologie du système :

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

Identifie les principaux composants architecturaux centraux, les dépendances centrales et la hiérarchie des couches.

---

Matrice de référence des outils MCP paresseux

Capacité	Outil	Paramètres obligatoires	Paramètres facultatifs clés
Vérifier l'état	index_status	project	N/A
Déclencher l'indexation	index_repository	repo_path	mode ("fast", "moderate", "full"), persistence
Lister les projets	list_projects	Aucun	N/A
Rechercher des symboles	search_graph	project	query, name_pattern, semantic_query, limit, offset
Tracer la chaîne d'appels	trace_path	project, function_name	direction ("inbound", "outbound", "both"), depth, mode
Récupérer la source	get_code_snippet	project, qualified_name	include_neighbors
Rayon d'impact	detect_changes	project	base_branch, since, scope ("impact", "files"), depth
Architecture	get_architecture	project	aspects (["hub_nodes"], ["layers"], ["all"])
Texte littéral	search_code	project, query	file_pattern, case_sensitive, limit

---

Garde-fous et anti-patrons courants

Anti-patron	Norme opérationnelle correcte
Rechercher sans vérifier la fraîcheur de l'index	Appelez toujours index_repository(mode: "fast") ou vérifiez avec index_status d'abord, car la surveillance automatique est désactivée.
Utiliser grep pour trouver des définitions de fonctions	Appelez search_graph avec le nom du symbole ; il renvoie les noms qualifiés, les chemins de fichiers exacts, les plages de lignes et les compteurs d'appels.
Lire 1000 lignes d'un fichier pour voir 1 fonction	Appelez get_code_snippet avec le qualified_name du symbole.
Lire manuellement chaque fichier pour trouver les appelants	Appelez trace_path avec direction: "inbound".
Supposer que le graphe est 100% complet	Le graphe est "au mieux". Si index_status liste des fichiers sous parse_partial, utilisez le grep textuel pour ces plages de lignes spécifiques.
Activer auto_watch	N'activez jamais auto_watch ; gardez-le false pour maintenir des performances de développement interactives optimales.