Comment tracer et corriger les dysfonctionnements d'un agent IA dans une base de code
makedreamJuly 30, 2026
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
Lorsque l'on connecte un agent IA comme Claude Code ou Codex à un dépôt backend de plus de 100 000 lignes, on est d'abord impressionné par la vitesse. Puis, à un moment donné, à cause de quelques lignes de prompt mal formulées, l'IA franchit les limites et va jusqu'à modifier des utilitaires communs ou des fichiers de configuration d'environnement. Les journaux de session gonflent jusqu'à atteindre plusieurs mégaoctets, le build plante, et après avoir passé une heure à parcourir le Git Diff pour trouver le fichier responsable, on se dit qu'il aurait mieux valu tout coder soi-même depuis le début.
Pour donner de l'autonomie à un agent tout en évitant les dommages inutiles sur les fichiers, il faut un isolement strict au niveau matériel et un système de suivi des traces visualisable.
Les fichiers d'instructions en langage naturel comme CLAUDE.md ou .aiignore ont tendance à être contournés par l'agent lorsque la fenêtre de contexte rallonge. Les requêtes au niveau du prompt ne restent que des recommandations : dès que l'agent perd le fil du contexte, l'exécution des outils franchit la barrière sans hésiter.
Pour bloquer physiquement les accès de l'agent, il faut placer directement à la racine du projet un moteur de contrôle de permissions déterministe : .claude/settings.json.
json { "permissions": { "deny": [ "Edit(src/core/config/**)", "Edit(src/shared/utils/**)", "Read(./.env*)", "Bash(rm -rf *)" ], "ask": [ "Edit(src/api/v1/legacy/**)" ] } }
Après avoir défini des règles de blocage explicites, il est plus sûr de verrouiller une seconde fois au niveau du système de fichiers. Pour les scripts de build de production ou les fichiers de clés de sécurité, le plus propre est de retirer les droits d'écriture au niveau de l'OS.
.claude/settings.json à la racine du projet.permissions.deny la configuration d'environnement, les chemins des utilitaires communs et les commandes Bash destructrices.chmod 444 .env*.En contrôlant ainsi les permissions, vous pouvez éliminer une grande partie des erreurs de build causées par une modification imprévue des modules communs par l'IA.
Si vous ne conservez les journaux de session (.jsonl) que dans l'environnement local de chaque développeur, il sera difficile d'identifier la cause le jour où un effet secondaire se produira. Configurez un workflow GitHub Actions pour compacter et vérifier les traces de session au moment de la création d'une PR.
`yaml
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
`
En combinant un moteur d'analyse basé sur Rust ou Tree-sitter pour vérifier si l'agent est sorti de son périmètre, vous pouvez faire échouer immédiatement le build CI en cas de modification d'un module parent hors des limites autorisées.
Il est utile de calculer le niveau de risque des modifications en se basant sur la connectivité des nœuds plutôt que sur le simple nombre de lignes de code.
Ici, représente le nombre de fichiers modifiés, et la connectivité 3D moyenne des nœuds altérés. Si le seuil est dépassé, configurez l'envoi d'un lien vers la carte de visualisation 3D via une notification Slack pour que le réviseur puisse évaluer immédiatement le niveau de risque.
Lorsque l'agent a mis le pagaille, au lieu d'annuler l'ensemble des commits, il faut retracer la ligne du temps pour ne restaurer de manière sélective que les fichiers corrompus. Une fois la plage horaire spécifique du dysfonctionnement extraite, utilisez jq pour récupérer le prompt et le chemin de raisonnement de ce moment précis dans le journal JSONL.
bash jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") | {timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}' \ ./.claude/sessions/session_abc123.jsonl
Une fois la cause confirmée, procédez à la restauration en la divisant selon les 3 étapes suivantes :
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)En utilisant cette méthode, vous pouvez récupérer proprement les fichiers endommagés sans risquer d'effacer le code qui fonctionne correctement.
Dans un environnement monorepo, lorsque le nombre de nœuds passe à plusieurs dizaines de milliers, l'outil de visualisation lui-même peut planter. Et si le navigateur ralentit, le débogage devient pénible. Pour exclure les répertoires inutiles du rendu, il faut définir un filtre d'exclusion clair dans mindwalk.config.json.
json { "visualization": { "excludePatterns": [ "**/node_modules/<strong>", "</strong>/vendor/<strong>", "</strong>/.git/<strong>", "</strong>/dist/<strong>", "</strong>/coverage/<strong>", "</strong>/*.log", "**/*.pb.go" ], "maxDepth": 5, "groupingStrategy": "directory-segmented" } }
Enfin, lorsque vous lancez le pipeline de visualisation ou les outils d'analyse dans un conteneur Docker en arrière-plan, vous devez limiter l'allocation des ressources pour éviter que l'IDE local ne se bloque.
mindwalk.config.json pour exclure les nœuds des répertoires de dépendances de la visualisation.--cpus="1.5" et --memory="2g" lors de l'exécution du conteneur.--nice=19 à la fin de la commande d'exécution du processus en arrière-plan pour réduire la priorité CPU au niveau le plus bas.