Que fait indexion-agent-orient ?
Générer et utiliser un brief de structure pré-édition pour que les agents de codage apprennent les propriétaires probables, les surfaces consommatrices et les emplacements d'édition dangereux avant de mettre en œuvre.
Aperçu
Cette compétence aide les agents de codage à comprendre la structure du projet avant d'apporter des modifications. Elle crée un brief de structure pré-édition (BSPÉ) qui documente :
- Propriétaires probables : quels développeurs ou équipes possèdent ou maintiennent des parties spécifiques du code.
- Surfaces consommatrices : quelles parties du système utilisent ou dépendent du code à modifier.
- Emplacements d'édition dangereux : les endroits où une modification pourrait facilement introduire des régressions ou casser des dépendances.
Pourquoi c'est utile
Sans ce brief, un agent de codage peut modifier du code sans comprendre son contexte, ce qui peut entraîner :
- Des conflits de propriété (modifier du code appartenant à une autre équipe).
- Des régressions inattendues (casser des consommateurs en aval).
- Des modifications dans des zones dangereuses qui devraient être évitées.
En générant et en utilisant un BSPÉ, l'agent peut prendre des décisions plus éclairées sur où et comment modifier le code, réduisant ainsi les risques et améliorant la collaboration avec les développeurs humains.
Plateformes prises en charge
- Claude Code
- Cursor
- Codex
- Tout agent de codage standard capable d'exécuter des outils en ligne de commande et de lire des fichiers.
Utilisation
Générer un brief
indexion orient generate [--path <chemin_du_projet>] [--output <fichier_de_sortie>]
Cela analyse le projet dans <chemin_du_projet> (par défaut, le répertoire courant) et génère un BSPÉ dans <fichier_de_sortie> (par défaut, ORIENT.md).
Consulter un brief
indexion orient show [--brief <chemin_du_brief>]
Affiche le BSPÉ actuel dans le terminal.
Mettre à jour un brief
indexion orient update [--path <chemin_du_projet>] [--brief <chemin_du_brief>]
Régénère le BSPÉ pour refléter les changements récents dans le projet.
Comment ça marche
- Analyse du projet : L'outil examine les métadonnées du projet (par exemple,
CODEOWNERS,package.json, configs), l'historique des commits Git (qui a modifié quoi), et effectue une analyse statique pour identifier les dépendances entre modules. - Construction du brief : Sur la base de l'analyse, il crée un fichier Markdown structuré avec des sections pour les propriétaires probables, les surfaces consommatrices et les emplacements d'édition dangereux.
- Utilisation par l'agent : Avant toute modification, l'agent de codage lit le BSPÉ (généralement nommé
ORIENT.md) et l'utilise pour guider ses décisions de mise en œuvre.
Exemple de sortie
# Brief de structure pré-édition pour mon-projet
## Propriétaires probables
| Fichier/Module | Propriétaire probable | Raison |
|----------------|----------------------|--------|
| `src/auth/` | `@equipe-auth` | Fichier CODEOWNERS |
| `src/api/` | `alice-dev` | 85% des commits récents |
## Surfaces consommatrices
| Module consommé | Modules consommateurs |
|-----------------|-----------------------|
| `src/lib/helpers.js` | `src/api/routes.js`, `src/auth/middleware.js` |
## Emplacements d'édition dangereux
- `src/core/engine.js` : Modification risquée – de nombreux consommateurs en aval. Envisagez d'ajouter plutôt une extension.
- `config/database.js` : Ne modifiez pas sans coordination avec l'équipe d'infrastructure.
Intégration avec les agents de codage
Ajoutez ce qui suit à l'instruction système ou au fichier de règles de votre agent pour vous assurer qu'il utilise le brief :
Avant de modifier le code, lisez
ORIENT.mddans le répertoire racine du projet. Utilisez-le pour identifier les propriétaires probables, les surfaces consommatrices et les emplacements d'édition dangereux. Évitez de modifier le code dans les zones dangereuses, et informez le développeur si vos modifications affectent des surfaces consommatrices appartenant à d'autres.
Configuration
Vous pouvez personnaliser le comportement via des variables d'environnement :
INDEXION_ORIENT_PATH: Chemin vers le répertoire du projet (par défaut, le répertoire courant).INDEXION_ORIENT_OUTPUT: Nom du fichier de sortie (par défaut,ORIENT.md).INDEXION_ORIENT_DEPTH: Profondeur d'analyse pour les dépendances (par défaut, 2).
Licence
MIT