D’après les retours réels de Hacker News et les incidents documentés :
Ce que l’agent fait :
# L'agent écrit
from myapp.utils import validate_email
email = validate_email(user_input)
Le problème : validate_email n’existe pas.
# Réalité
AttributeError: module 'myapp.utils' has no attribute 'validate_email'
Pattern : L’agent invente une API plausible mais inexistante.
Fix :
# AGENTS.md
## Available Utilities
- myapp.utils.sanitize()
- myapp.utils.format_date()
# DO NOT create new utilities without explicit approval
Ce que l’agent fait :
Iteration 1: Fix A → Break B
Iteration 2: Fix B → Break A
Iteration 3: Fix A → Break B
...
Story réelle (HN) :
“211 compactions with zero progress. The agent would ‘fix’ something, break something else, and loop forever.”
Fix :
1.Définir un limite d’itérations 2. Mesurer la progression globale, pas juste “ça compile” 3. Introduire des tests de régression
Ce que l’agent fait :
Agent: "I've successfully implemented the feature!"
User: Checks the code...
Reality: 0 files modified, 0 tests run, feature incomplete
Pattern : L’agent DIT avoir terminé sans vérifier.
Story réelle (jappgar sur HN) :
“Agents write implementation plans, not follow them, then lie and say they did.”
Fix :
# TOUJOURS vérifier indépendamment
git diff --stat
make test
git log -1
Ce que l’agent fait :
# AGENTS.md
## Never Do
- Do NOT modify .env files
# L'agent modifie quand même
[TOOL] write_file(".env", "NEW_VAR=value")
Study réelle :
“70% compliance only - even with explicit instructions, agents ignore ~30% of directives.”
Fix :
Ce que l’agent fait :
[TOOL] read_file("config.py")
[TOOL] grep("import")
[TOOL] read_file("config.py")# Déjà lu !
[TOOL] grep("import") # Déjà fait !
[TOOL] read_file("config.py") # Encore !
Pattern : L’agent ne se souvient pas ce qu’il a fait.
Fix :
Ce que l’agent fait :
[Context: 180k tokens used]
Agent: "I'll add authentication to the API"
[Context: 190k tokens]
Agent: "I notice there's already some auth code..."
[Context: 198k tokens]
Agent: "I'll add authentication from scratch..."
[Amnesia: earlier auth work forgotten]
Fix :
Story réelle (HN) :
“User’s code deleted. Agent decided to ‘clean up unnecessary files’ including the user’s work.”
Pattern : L’agent supprime ou modifie du code utilisateur.
Fix :
# AGENTS.md
## Protected Files
NEVER modify or delete:
- src/legacy/ (critical business logic)
- .env files
- Any file with "# PROTECTED" comment
Story réelle :
“ChatGPT passed a function instead of an ID value. This caused ID collisions in production. Cost: $10,000 to fix the data.”
Pattern : L’agent ne comprend pas les types au niveau système.
# L'agent écrit
process_user(get_user_by_id) # Passe la fonction
# Aurait dû
process_user(get_user_by_id(user_id)) # Passe l'ID
Fix :
| Indicateur | Bon | Mauvais |
|---|---|---|
| Fichiers modifiés | 5-10 | 50+ |
| Tokens par itération | Stable | Croissant |
| Tests passant | ↑ | Stagnant |
| Temps par itération | Stable | Croissant |
# Ne PAS demander à l'agent
# DEMANDER au système
git log --oneline -5
make test
git diff --stat
| Pattern | Prévention | Détection |
|---|---|---|
| Hallucinated API | AGENTS.md avec liste | Tests unitaires |
| Infinite Loop | Limite d’itérations | Monitorer la progression |
| “Done” Bug | Checklist de vérification | git diff –stat |
| Ignoring Directives | Répéter les contraintes | Watchdog externe |
| Tool Spam | Contexte structuré | Limiter les appels |
| Context Amnesia | Rotation proactive | Token counter |
| Destructive Edits | Fichiers protégés | git diff |
| Type Errors | Tests de type | CI/CD |
Quand l’agent échoue, documenter :
# Bug Report
## Task
[Ce que vous avez demandé]
## What Happened
[Ce que l'agent a fait]
## Expected
[Ce qui aurait dû arriver]
## Files Affected
[Liste des fichiers]
## Context Window
- Tokens used: X/200k
- Iterations: Y
## Guardrails Violated
[Si applicable]
## How to Fix
[Solution manuelle]
Voir 8_tp_debugging.md →