Prefixer : cible d'abord, élargis en cas d'échec, enregistre l'écart
Un agent qui parcourt l'intégralité du dépôt paie chaque résultat non pertinent en tokens. Une carte des espaces de noms, une douzaine de lignes indiquant où se trouve quoi, lui permet de chercher dans la bonne zone dès le premier appel. Cette compétence construit cette carte, la maintient à jour, et contraint l'agent à une recherche d'abord ciblée. Elle fait une seule chose : une recherche de code moins chère et meilleure.
Seuil de taille. En dessous d'environ une centaine de fichiers, ou lorsque la structure du dépôt est évidente au premier coup d'œil, ignore la carte et cible les recherches par noms de répertoires ; la carte devient rentable au-delà de ce seuil.
Comment travailler
- S'oriente une fois. Vérifie la présence de
.prefixer/namespaces.md. Si elle n'existe pas et que la tâche nécessitera plus de deux recherches, cartographie le segment sur lequel tu travailles (§1 à §3), puis cherche à l'intérieur. Si une carte existe, lis-la et commence en mode ciblé. - Recherche ciblée, élargis en cas d'échec. La première recherche va dans l'espace de noms le plus étroit plausible, pas à la racine du dépôt (§4 à §6).
- Enregistre-la. Termine la tâche par une ligne dans
.prefixer/metrics.jsonl, et un delta lorsqu'une référence existe (§7 à §8). Sortie obligatoire, pas facultative.
Où elle est rentable
- Première session dans un dépôt volumineux ou inconnu. Lis douze lignes de carte au lieu de scanner l'arborescence ; la première recherche est déjà ciblée.
- Monorepos. Un espace de noms par paquet : les recherches cessent d'emporter le bruit des paquets frères dans le contexte.
- De nombreux codebases. Une carte au niveau de l'organisation choisit le codebase, la carte du dépôt choisit l'espace de noms à l'intérieur. Deux niveaux, jamais de scan d'union.
- Exploration répétée. « Où se trouve X », les refontes, les zones fonctionnelles inconnues ; le taux de réussite au premier essai est là où la carte paie son loyer.
- Dépôts que tu revisiteras. La carte persiste entre les sessions ; chaque futur agent démarre orienté au lieu de re-scanner.
A. La carte des espaces de noms
1. Cartographie le segment, pas le monde
Règle : Lorsqu'un dépôt n'a pas de .prefixer/namespaces.md et que le travail nécessite plus de deux recherches, cartographie la partie du dépôt que cette tâche touche : trois à cinq espaces de noms ; pas l'arborescence entière. Une carte partielle qui cible les recherches d'aujourd'hui bat une carte complète qui a pris une heure. Étends-la lorsqu'une vraie recherche atterrit en dehors, jamais par anticipation. Exécute bash scripts/init_namespaces.sh (dans le répertoire de cette compétence) pour obtenir une ébauche, puis corrige ses suppositions : nomme ce à quoi chaque espace de noms sert.
Pourquoi : l'adoption est progressive par conception. La carte est un fichier de travail, pas un recensement ; elle gagne une ligne quand une recherche a besoin de cette ligne.
Les ébauches ne sont pas des cartes. Toute ligne dont le préfixe ou contains contient encore TODO est inachevée ; termine-la ou supprime-la avant de te fier à la carte. L'ébauche indique combien de lignes d'ébauche restent.
D'abord les docs existants. Si AGENTS.md, CLAUDE.md ou le README décrivent déjà la disposition, alimente contains à partir d'eux (l'ébauche le fait) et considère namespaces.md comme faisant autorité pour la portée de la recherche ; ne maintiens pas deux tables des matières divergentes.
Le début de session vaut mieux que la mémoire. Lire la carte une fois par session est l'étape la plus susceptible d'être sautée. Si le harnais peut injecter des fichiers au démarrage de la session, fais-lui émettre namespaces.md : chaque recherche commence alors ciblée sans aucune discipline requise. Câblage fourni : scripts/install_hook.sh écrit le hook pour toi (scripts/session_start.sh émet la carte plus un verdict de santé) ; des extraits à copier se trouvent dans integrations/. Recette et justification : references/namespaces.md.
2. Garde-la petite et basée sur des globs
Règle : 5 à 12 espaces de noms. Chaque ligne est un préfixe court, un glob de chemin et un objectif d'une ligne écrit pour la désambiguïsation. Si deux lignes correspondraient aussi souvent à la même recherche, fusionne-les. Si une ligne ne cible jamais une vraie recherche, supprime-la.
Format :
# espaces de noms
depot: acme-payments
| prefixe | portée | contient |
|---------|---------------------|-----------------------------|
| api: | src/api/** | gestionnaires REST, routes |
| auth: | src/auth/** | connexion, sessions, jetons |
| sso: | src/auth/sso/** | zone sous-équipe SSO |
| test: | tests/**, **/*.test.* | suites, fixtures |
L'en-tête depot: est le qualifiant unique de ce codebase (d'après le remote git) ; il rend chaque préfixe globalement unique lorsqu'une organisation exécute de nombreux codebases : acme-payments:auth: ne peut jamais entrer en collision avec checkout-service:auth:.
Les lignes s'imbriquent : une ligne indentée appartient à l'espace de noms au-dessus d'elle, pour les sous-équipes à l'intérieur d'un module ou les paquets à l'intérieur d'un service. La balise se compose, auth:sso:, de sorte que le même nom sous deux parents reste distinct (orders:checkout: vs payments:checkout:).
Les noms sont dérivés, pas déclarés. Les préfixes et le texte contains proviennent du vocabulaire propre du codebase : noms de répertoires, termes dominants dans les fichiers qu'une ligne cible, jamais de catégories que tu inventes. Les noms dérivés suivent l'évolution du dépôt ; ceux inventés dérivent. L'ébauche fait cela pour toi : corrige ce qu'elle fait mal, garde ce qu'elle a bien fait.
Détails du format et cartes pour d'autres formes de dépôt : references/namespaces.md.
3. Mets à jour, ne régénère jamais
Règle : Lorsque la carte est obsolète, modifie les lignes obsolètes. Ne réécris pas le fichier. La régénération en masse perd les détails accumulés qui la rendaient utile. Supprime les lignes mortes, ajoute celles qui manquent, laisse le reste identique en octets ; une carte réécrite brise également le préfixe du cache d'invite de chaque session qui l'a chargée. Après avoir organisé, exécute bash scripts/check_namespaces.sh : une ligne dont les globs ne résolvent rien est un mensonge que la carte raconte à chaque future session. Lorsque la carte semble obsolète ou que le journal a grossi, exécute bash scripts/suggest_map.sh : il lit metrics.jsonl et l'arborescence et propose les lignes que les vraies recherches ont déjà demandées.
De nombreux codebases : la même astuce s'empile. Une carte au niveau de l'organisation choisit le codebase (pay: services/payments/**), la carte du dépôt choisit l'espace de noms à l'intérieur. L'en-tête depot: de chaque carte maintient les préfixes uniques entre les codebases ; quarante services peuvent tous avoir un auth/ car une balise qualifiée payments:auth: en nomme exactement un. Ne fais jamais l'union de tous les dépôts en une seule recherche qui est l'échec du grep racine à l'échelle de l'organisation. Voir references/namespaces.md.
B. Ciblage de la recherche
4. Le plus étroit en premier
Règle : Chaque recherche commence dans l'espace de noms le plus étroit qui pourrait contenir la réponse. grep "expire" src/auth/ bat grep "expire" .. Un échec coûte un appel ; une recherche large coûte toute la liste des résultats en tokens.
Laisse le script appliquer la règle : bash scripts/search.sh auth "expire" résout la balise en ses globs, cherche à l'intérieur, élargit d'un niveau en cas d'échec et enregistre la ligne de métriques ; §4 à §8 s'exécutent d'eux-mêmes. --scope <ns> affiche la liste des globs, --paths <ns> les fichiers résolus, --list chaque balise ; la carte comme index que d'autres commandes peuvent interroger.
Attention à : rechercher à la racine du dépôt « au cas où », les motifs glob comme **/* sans contrainte de chemin, find utilisé là où un glob d'espace de noms ferait l'affaire.
5. Élargis d'un niveau en cas d'échec
Règle : Pas de résultat dans un espace de noms ? Élargis d'un niveau : espace de noms, puis sa zone parente, puis le dépôt, puis les répertoires vendus et générés. Ne passe pas d'un échec directement à un scan complet du dépôt, et ne cherche pas dans node_modules, vendor, dist, build ou les fichiers de verrouillage sauf si la tâche les concerne.
6. Réponds avec des balises d'espace de noms
Règle : Signale les résultats sous la forme prefixe:chemin:ligne (auth:src/auth/session.ts:42). La recherche suivante, la tienne ou celle d'une future session, commence alors déjà ciblée. Lorsqu'un fichier résiste à tous les espaces de noms, c'est le signe que la carte a une lacune ; mentionne-le au lieu d'inventer une balise.
C. Suivi
7. Référence avant les affirmations
Règle : Avant de recommander des changements de recherche, compte le comportement actuel : recherches par tâche, appels d'outils par tâche, taux de réussite au premier essai. Sans référence, il n'y a pas de delta, seulement une histoire. Enregistre-en une en exécutant une sonde fixe : bash scripts/measure_search.sh --baseline orientation -- grep -rn "TODO" . à la racine du dépôt, ou en comptant les premières tâches avant que la carte n'existe. Voir references/metrics.md pour savoir quoi enregistrer et comment le noter.
8. Enregistre chaque tâche
Règle : Ajoute une ligne JSON à .prefixer/metrics.jsonl à la fin de chaque tâche :
{"ts":"2026-10-26T14:03:11Z","task":"find-session-expiry","searches":3,"tool_calls":4,"first_try_hit":true,"est_tokens":1400}
est_tokens correspond à caractères/4, une estimation ; conserve le champ même lorsque tu ne peux pas mesurer exactement. À la fin de la session, rapporte le delta par rapport à la référence. scripts/measure_search.sh encapsule une recherche et enregistre une ligne par recherche à la racine du dépôt (hits, scope ; --baseline marque la sonde, --hit|--miss enregistre first_try_hit). Les lignes de tâches manuscrites ajoutent tool_calls et first_try_hit. Un schéma unique, des champs optionnels ; references/metrics.md les liste. scripts/report_metrics.sh relit le journal : taux de réussite, dépense par portée, delta ciblé vs référence.
Gestion Git. Envoie namespaces.md : c'est le préfixe partagé dont chaque future session bénéficie. metrics.jsonl est de la télémétrie locale ; l'ébauche écrit un .prefixer/.gitignore pour lui. Envoie-le seulement si l'équipe souhaite des données de tendance.
Drapeaux rouges
Ces pensées signifient arrête. Tu rationalises.
| Pensée | Réalité |
|---|---|
| « Un grep large ne fera pas de mal » | Le grep large est le coût que cette compétence existe pour supprimer. Cible-le. |
| « Je sais où ça se trouve probablement » | Vérifie dans l'espace de noms. Une supposition erronée coûte plus cher qu'une vérification ciblée. |
| « Cartographie d'abord tout le dépôt » | Cartographie le segment où tu te trouves. Le reste gagne des lignes lorsque les recherches en ont besoin. |
| « La carte est excessive pour cette tâche » | Une carte partielle paie encore à la troisième recherche. |
| « Saute la référence, il suffit d'appliquer » | Pas de référence signifie pas de preuve. Mesure d'abord. |
| « Je vais régénérer toute la carte, c'est plus rapide » | La régénération supprime les détails organisés et brise le cache. Modifie les lignes obsolètes. |
| « Une carte ébauchée compte » | Une carte pleine de lignes TODO est une ébauche, pas une carte. Termine-les ou supprime-les. |
| « Cherche dans les répertoires vendor pour être minutieux » | Le code généré est l'endroit où les tokens vont mourir. Cherche uniquement quand c'est le sujet. |
Quand ne pas préfixer
- Scripts à fichier unique et dépôts jetables : il n'y a rien à cibler.
- Tâches avec un seul fichier évident : ouvre-le, ne construis pas d'infrastructure pour lui.
- Lorsque le chemin le dit déjà : une recherche dans
src/auth/n'a pas besoin d'une cérémonieauth:autour d'elle. - Code vendu ou généré, sauf s'il est le sujet de la tâche.
- Dépôts de moins d'environ 100 fichiers dont la forme est évidente : cible par noms de répertoires et ignore la carte.
Références
references/namespaces.md: format de carte, formes de dépôt, empilement multi-dépôtreferences/metrics.md: définitions des métriques, schéma JSONL, rapport de deltascripts/init_namespaces.sh: ébaucher une carte d'espace de noms pour le dépôt courantscripts/check_namespaces.sh: lint une carte : portées mortes, balises en double, ébauchesscripts/search.sh: recherche ciblée en tant que commande : résout, cherche, élargit, enregistrescripts/suggest_map.sh: lit le journal + l'arborescence, propose des modifications de cartescripts/measure_search.sh: exécute une recherche et l'enregistre en une étapescripts/report_metrics.sh: relit le journal : taux de réussite, dépense par portée, deltascripts/session_start.sh: émet la carte (+ santé) pour les hooks de démarrage de sessionscripts/install_hook.sh: câble le hook SessionStart pour devin/claudescripts/doctor.sh: vérifie la santé de la configuration d'un dépôt : carte, lint, hook, estampilles d'installationscripts/eval_scope.sh: mesure le delta de tokens d'une recherche ciblée vs racinescripts/eval_repo.sh: lint + évalue chaque espace de noms dans une carte, % moyen économiséscripts/visualize.py: rend la carte sur l'arborescence des fichiers + les économies mesurées sous forme de rapport HTMLSPEC.md: le contrat de format namespaces.md, pour les outils qui lisent ou écrivent des cartesintegrations/: extraits de hooks de démarrage de session + un workflow de lint PR pour les dépôts consommateurs
Playbooks adjacents conservés pour les auteurs de pipelines et d'invites (en dehors du travail principal de cette compétence) : references/index-prefixes.md, references/prefix-library.md, references/cache-ordering.md.