Guide officiel CONVENTIONS.md : aider.chat/docs/usage/conventions.html • Licence : Apache 2.0
Dans le paysage des outils de développement assistés par IA, Aider (créé par Paul Gauthier) occupe une place à part : celle du pur outil d’ingénierie en ligne de commande (CLI), pensé pour les développeurs seniors qui refusent de quitter leur terminal, leur multiplexeur tmux et leur flux de travail Git.
Là où beaucoup d’assistants génèrent du code « hors-sol » qui viole les invariants du projet (imports mal placés, bibliothèques obsolètes, abstractions inutiles, oubli des tests anti-régression), Aider combine une cartographie AST du dépôt (Repo-Map via Tree-sitter) avec un mécanisme aussi simple que redoutable : le fichier de contrat architectural CONVENTIONS.md (documenté officiellement ici).
1. Pourquoi Aider reste une référence absolue du Pair-Programming en Terminal
Contrairement aux extensions d’IDE lourdes et opaques, Aider fonctionne directement au-dessus de votre dépôt Git local et dialogue avec le modèle de votre choix (Claude Sonnet/Opus, GPT, DeepSeek, Gemini ou un modèle local via Ollama). Sa supériorité technique repose sur quatre piliers :
- La Repo-Map basée sur Tree-sitter (AST + PageRank) : Avant même d’envoyer votre requête au LLM, Aider analyse l’arbre syntaxique abstrait (AST) de l’ensemble de votre dépôt, construit un graphe des dépendances entre symboles (classes, fonctions, signatures, appels croisés) et utilise un algorithme de graph ranking pour injecter dans le contexte uniquement les signatures les plus pertinentes du projet.
- Le mode Architect / Editor : Aider peut séparer la réflexion en deux passes : un modèle « Architecte » (raisonnement profond) conçoit la solution exacte et identifie la cause racine, tandis qu’un modèle « Éditeur » rapide applique chirurgicalement les blocs
SEARCH / REPLACEdans les fichiers sources. - La boucle d’auto-guérison (Lint + Test Auto-Loop) : Dès qu’Aider modifie un fichier, il exécute automatiquement votre linter (
ruff,golangci-lint,eslint) et votre suite de tests (pytest,go test,npm test). Si une erreur survient, la trace d’exécution est réinjectée pour correction immédiate avant tout commit. - Des commits Git atomiques et propres : Chaque modification validée fait l’objet d’un commit Git horodaté avec un message conventionnel précis, permettant un
git diffou un/undoinstantané en une seconde.
2. Le pouvoir de CONVENTIONS.md : Empêcher l’IA de dériver
Même le meilleur LLM possède des réflexes par défaut issus de son corpus d’entraînement généraliste : il aura tendance à utiliser requests au lieu de httpx.AsyncClient, à ajouter des wrappers superflus, à disperser des import au milieu d’une fonction Python ou à oublier vos règles de sécurité internes.
Comme l’explique la documentation officielle Specifying coding conventions (aider.chat/docs/usage/conventions.html), la méthode la plus fiable pour aligner Aider sur les standards de votre équipe consiste à créer un fichier CONVENTIONS.md à la racine du dépôt et à le charger en tant que fichier de contexte en lecture seule (--read) avec mise en cache des prompts (Prompt Caching).
┌────────────────────────────────────────────────────────────────────────────┐
│ FLUX D'EXÉCUTION AIDER + CONVENTIONS.MD │
│ │
│ ┌─────────────────────────┐ ┌──────────────────────────────────────┐ │
│ │ .aider.conf.yml │ │ CONVENTIONS.md (Read-Only + Cached) │ │
│ │ read: CONVENTIONS.md │────▶│ • Top-level imports obligatoires │ │
│ │ cache-prompts: true │ │ • Zéro abstraction / YAGNI (Ponytail)│ │
│ │ auto-test: true │ │ • Typage strict & Validation entrées │ │
│ └─────────────────────────┘ └──────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Contexte envoyé au LLM = System Prompt + CONVENTIONS.md + Repo-Map │ │
│ └──────────────────────────────────────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Patch SEARCH/REPLACE ──▶ Linter + Tests Canaries ──▶ Commit Git │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘
Pourquoi charger CONVENTIONS.md via /read (ou --read) plutôt que /add ?
Dans Aider, la distinction entre /add et /read est fondamentale :
/add fichier.pydonne à Aider le droit de modifier le fichier./read CONVENTIONS.md(ouaider --read CONVENTIONS.md) verrouille le fichier en lecture seule et le place en tête du contexte système afin qu’il bénéficie du Prompt Caching (Anthropic / OpenAI / DeepSeek), réduisant jusqu’à 90 % le coût et la latence des requêtes successives tout en empêchant le LLM d’altérer vos règles !
3. Modèle de fichier CONVENTIONS.md éprouvé en production
Voici un gabarit concret de CONVENTIONS.md combinant hygiène Python/FastAPI, sécurité Zero-Trust et minimalisme Ponytail :
# CONVENTIONS D'INGÉNIERIE (GARDE-FOUS OBLIGATOIRES)
## 1. Philosophie du Code (Minimalisme & Cause Racine)
- Avant de modifier une fonction, vérifie tous ses appelants dans le dépôt.
- Corrige toujours la cause racine au lieu d'ajouter un contournement en aval.
- Zéro sur-ingénierie : n'introduis jamais de classe wrapper, d'interface abstraite ou d'option de configuration que personne n'a demandée.
## 2. Invariants Python & FastAPI
- **Imports Top-Level uniquement** : Tous les `import` doivent obligatoirement figurer en haut du fichier. Aucun `import` local à l'intérieur d'une fonction ou d'une route n'est toléré.
- Toute dépendance tierce importée doit être déclarée dans `requirements.txt`.
- Utilise exclusivement `httpx.AsyncClient(timeout=10.0)` pour les appels HTTP sortants (jamais `requests` synchrone dans une route `async def`).
- Valide systématiquement les payloads entrants et sortants avec des modèles **Pydantic v2** explicites (`ConfigDict(extra="forbid")`).
## 3. Sécurité & Gestion des Secrets
- Ne code jamais en dur de clé API, token, mot de passe ou adresse IP interne.
- Paramètre toujours les requêtes SQL/NoSQL ; n'utilise jamais de f-string pour construire une requête.
## 4. Tests & Non-Régression
- Tout correctif de bug ou nouvel endpoint doit être accompagné d'un test unitaire reproductible dans `tests/`.
4. Automatisation complète via .aider.conf.yml
Pour ne jamais oublier de charger CONVENTIONS.md à chaque ouverture de terminal, il suffit de déclarer la configuration de manière permanente dans le fichier .aider.conf.yml à la racine du projet (ou dans ~/.aider.conf.yml) :
# .aider.conf.yml : Configuration déclarative Aider
read:
- CONVENTIONS.md
# Activation du Prompt Caching pour amortir le coût du contexte en lecture seule
cache-prompts: true
# Mode Architecte pour séparer la conception du patch chirurgical
architect: true
# Vérification automatique à chaque modification de code
auto-lint: true
lint-cmd: "ruff check"
auto-test: true
test-cmd: "pytest -q"
# Commits atomiques propres
auto-commits: true
dirty-commits: false
Dès lors, lancer simplement aider dans le répertoire du projet charge automatiquement vos conventions en lecture seule, active le cache de prompt, vérifie chaque patch via ruff et pytest, et refuse de commiter un code qui casserait un test existant.
5. Conclusion : La discipline écrite transforme la qualité des agents IA
L’enseignement majeur d’Aider et de son système CONVENTIONS.md dépasse le cadre d’un seul outil : la qualité du code produit par une IA est directement proportionnelle à la clarté des invariants architecturaux écrits dans votre dépôt. En versionnant vos règles d’ingénierie dans Git au même titre que votre code source et vos tests canaries, vous transformez un générateur de code probabiliste en un binôme d’ingénierie fiable, prévisible et aligné sur vos standards de production.
- Dépôt GitHub officiel d’Aider : https://github.com/Aider-AI/aider
- Documentation officielle sur
CONVENTIONS.md: https://aider.chat/docs/usage/conventions.html - Dépôt communautaire d’exemples de conventions : https://github.com/Aider-AI/conventions