đ§© Aider â Guide complet pour le dĂ©veloppement agentique terminal-first
Guide IDEO-Lab extrĂȘmement densifiĂ© consacrĂ© Ă Aider : pair-programming IA dans le terminal, intĂ©gration Git, repo map, modes code/ask/architect, commandes slash, lint/test, providers LLM, watch mode IDE, voice/web/images, conventions projet, workflow Django/Python, sĂ©curitĂ© et playbook senior de production.
Positionnement
Terminal-first, Git-native, repo-aware : la place dâAider dans le dev agentique.
TerminalGit-nativeCLIInstallation & config
Installation propre, clés API, .env, .aider.conf.yml, premiers réglages.
SetupuvConfigWorkflow Git-native
Auto-commits, diff, undo, dirty files, branches et PR review.
GitDiffUndoRepo Map & contexte
Cartographie du dépÎt, symboles, fichiers read-only, budget tokens.
Repo MapContextTokensModes Chat
code, ask, architect, help : choisir le bon mode selon le risque.
CodeAskArchitectCommandes slash
/add, /drop, /diff, /run, /test, /lint, /web, /voice, /editor.
CommandsCLIRunbookLint, tests & CI
Boucle qualité : patch, linter, test ciblé, correction, CI.
TestsLintCIModÚles & coûts
Providers, modĂšles locaux/cloud, architect/editor, weak model, prompt cache.
ModelsCostProvidersIDE, Watch & Voice
AI!, AI?, watch mode, web pages, images, clipboard et voice-to-code.
IDEWatchVoiceDjango/Python
Models, migrations, services, commands, admin, templates et tests Django.
DjangoPythonMigrationsSécurité & gouvernance
Secrets, données privées, commandes dangereuses, attribution et audit.
SecurityGovernanceAuditPlaybook & sources
MĂ©thode senior quotidienne, prompts prĂȘts, troubleshooting et sources.
PlaybookSeniorSourcesAider en une phrase
Aider est un outil de pair-programming IA qui fonctionne principalement dans le terminal. Il travaille dans un dĂ©pĂŽt Git local, lit les fichiers nĂ©cessaires, applique des modifications, affiche des diffs, lance des commandes et peut crĂ©er des commits automatiquement. Sa valeur est moins âspectaculaire IDEâ que discipline terminal + Git + tests + contexte contrĂŽlĂ©.
Dans le monde du dĂ©veloppement agentique, Aider occupe une place claire : un copilote Git-native pour dĂ©veloppeurs qui savent dĂ©jĂ travailler avec branches, commits, scripts, tests, CI et revue de diff. Câest donc trĂšs adaptĂ© au backend, Django/Python, DevOps, scripts, maintenance et refactoring progressif.
Diagramme mental
Developer intent
|
v
aider terminal session
|
+-- Git repo
+-- Repo map
+-- Files in chat
+-- Read-only conventions
+-- Lint/test commands
|
v
LLM pair programmer
|
+-- edit files
+-- show diff
+-- run tests
+-- commit changes
|
v
Human review / PR / CIAider vs IDE agents
| Outil | Point dâentrĂ©e | Force | Risque | Usage idĂ©al |
|---|---|---|---|---|
| Aider | Terminal + Git | Commits auditables, repo map, scripts. | Moins visuel, demande discipline CLI. | Backend, scripts, Django, refactor, CI. |
| Cursor | IDE IA | Plan Mode, agent visuel, navigation. | Accept-all trop facile. | Dév quotidien dans IDE. |
| Windsurf | IDE + Cascade | Flow state, UI, context awareness. | Peut masquer la complexité. | Full-stack avec rendu visuel. |
| Claude Code | CLI agentique | Exploration terminal profonde. | Commandes puissantes Ă cadrer. | Debug et autonomie shell. |
Cas dâusage trĂšs rentables
Bug reproductible
Stack trace + test ciblé + patch minimal + commit.
Refactor progressif
Extraction de service, renommage, découpage sans rewrite global.
Tests de régression
Demander un test qui Ă©choue dâabord, puis le fix.
Scripts & DevOps
Makefile, shell, YAML CI, management commands.
Documentation
Runbooks, README, conventions, modes opératoires.
Maintenance legacy
Comprendre un module ancien sans le réécrire.
Aider is strongest when the task can be: - scoped to a few files - validated by an exact command - committed as one clean diff - reviewed by a human
Limites et anti-patterns
| Anti-pattern | Conséquence | Correction |
|---|---|---|
| âFix everythingâ | Diff Ă©norme, architecture inventĂ©e. | Une mission, un patch. |
| Pas de tests | Confiance artificielle. | /test ciblé ou test-cmd. |
| Repo sale | Travail humain et IA mélangés. | Commit/stash avant session. |
| Pas de conventions | Style générique du modÚle. | CONVENTIONS.md en read-only. |
| Secrets dans logs | Risque sécurité. | Masquer, filtrer, .env.example. |
Installer Aider proprement
La documentation officielle propose plusieurs mĂ©thodes : aider-install, one-liners, uv, pipx, pip, Docker, Codespaces ou Replit. Le principe professionnel est dâisoler Aider de lâenvironnement applicatif.
| Méthode | Commande type | Avantage | Surveillance |
|---|---|---|---|
| aider-install | python -m pip install aider-install | Simple, isolé. | PATH, version Python. |
| uv | uv tool install --force --python python3.12 --with pip aider-chat@latest | Rapide, reproductible. | uv installé. |
| pipx | pipx install aider-chat | Bon pour outils CLI. | Compatibilité Python. |
| pip | python -m pip install -U aider-chat | Simple. | Utiliser venv. |
| Docker | docker run ... aider | Isolation forte. | Volumes, UID, clés. |
cd /path/to/project aider --model sonnet --api-key anthropic=YOUR_KEY aider --model o3-mini --api-key openai=YOUR_KEY aider --model deepseek --api-key deepseek=YOUR_KEY
PrĂ©paration dâun dĂ©pĂŽt sĂ©rieux
- Travailler dans une branche dédiée.
- Vérifier
git status. - Créer
CONVENTIONS.md. - Documenter commandes test/lint/check.
- Ăviter logs, dumps, media, builds.
project/
app/
tests/
docs/
architecture.md
runbook.md
scripts/
test.sh
lint.sh
CONVENTIONS.md
.aider.conf.yml
.env.example.aider.conf.yml
Aider peut charger .aider.conf.yml depuis le home, la racine Git ou le dossier courant. Le fichier chargé en dernier prend priorité.
model: anthropic/claude-3-7-sonnet-20250219 weak-model: openai/gpt-4o-mini editor-model: openai/gpt-4o read: - CONVENTIONS.md - docs/architecture.md - docs/runbook.md map-refresh: auto map-tokens: 4096 auto-lint: true lint-cmd: - "python: ruff check" test-cmd: "python manage.py test" auto-test: false pretty: true notifications: true
| Option | RĂŽle | Conseil |
|---|---|---|
| model | ModĂšle principal. | Fort pour bug/refactor. |
| weak-model | Commit/résumé. | Rapide et moins cher. |
| read | Docs read-only. | Conventions, architecture. |
| test-cmd | Commande test. | Simple et fiable. |
Clés API et .env
Ă faire
# .env - never commit ANTHROPIC_API_KEY=... OPENAI_API_KEY=... DEEPSEEK_API_KEY=... # .gitignore .env .aider.chat.history.md .aider.llm.history
à éviter
- paste production tokens into chat - commit .env - include customer data in logs - expose local secrets in prompts
Pourquoi Git est le cĆur dâAider
Aider fonctionne particuliÚrement bien dans Git : chaque modification IA peut devenir un commit, donc un artefact relu, annulé, comparé, poussé en PR et validé en CI.
| Mécanisme | Valeur |
|---|---|
| Auto-commit | Trace chaque modification IA. |
| Dirty files | Sépare modifications humaines et IA. |
| /diff | Review immédiate. |
| /undo | Rollback rapide. |
| /git | Commandes Git depuis la session. |
Workflow de branche
git checkout main git pull git checkout -b fix/aider-auth-timeout git status aider --read CONVENTIONS.md app/auth.py tests/test_auth.py # inside aider /ask explain the timeout path without editing /code implement the smallest fix and add one regression test /test python manage.py test tests.test_auth.TimeoutTests /diff git push -u origin fix/aider-auth-timeout
Rollback et annulation
| Besoin | Commande | Usage |
|---|---|---|
| Annuler dernier patch Aider | /undo | En session. |
| Inspecter dernier commit | git show | Review complĂšte. |
| Revenir localement | git reset --soft HEAD~1 | Avant push. |
| Annuler en branche partagée | git revert SHA | AprÚs push. |
Messages de commit utiles
| Faible | Utile |
|---|---|
| fix stuff | fix(auth): handle provider timeout response |
| update tests | test(importer): add duplicate row regression case |
| refactor | refactor(billing): extract invoice total service |
--attribute-commit-message-author --attribute-commit-message-committer --attribute-co-authored-by --commit-prompt "Write concise Conventional Commit messages with scope."
Repo Map : carte concise du dépÎt
Aider construit une carte du repo contenant fichiers, classes, fonctions, signatures et symboles importants. Cela permet au modÚle de comprendre le code sans charger tout le dépÎt.
| ĂlĂ©ment | UtilitĂ© |
|---|---|
| Chemins | Orientation dans gros dépÎt. |
| Classes/fonctions | API interne et signatures. |
| Ranking | Priorise ce qui tient dans le budget tokens. |
Ajouter les bons fichiers
aider app/services/payment.py tests/test_payment.py /add app/models.py /read-only CONVENTIONS.md /read-only docs/architecture.md /drop app/old_experiment.py /ls /tokens /map /map-refresh
| Commande | RĂŽle | PiĂšge |
|---|---|---|
| /add | Fichier modifiable. | Trop de fichiers. |
| /read-only | Référence non modifiable. | Docs obsolÚtes. |
| /drop | Retirer du contexte. | Oublier un fichier utile. |
| /tokens | Surveiller budget. | Ignorer saturation. |
Bon contexte vs mauvais contexte
Bon contexte
- Erreur exacte.
- Fichiers concernés.
- Test ciblé.
- Conventions read-only.
- Contraintes explicites.
Mauvais contexte
- Tout le repo éditable.
- Logs énormes.
- Vieilles versions.
- Objectifs mélangés.
- Prompt vague.
Bad: Fix the search system. Good: /ask Analyze this failing test only. Do not edit files. Explain why it fails and propose one minimal patch.
Réglages pratiques
| Réglage | Effet | Valeur pratique |
|---|---|---|
| map-tokens | Taille repo map. | 2048-8192. |
| map-refresh | Recalcul carte. | auto. |
| read | Docs permanentes. | Conventions courtes. |
| /tokens | ContrÎle budget. | AprÚs réponses incohérentes. |
Les modes de chat
| Mode | Commande | Comportement | Usage |
|---|---|---|---|
| code | /code | Modifie le code. | Patch validé. |
| ask | /ask | Répond sans modifier. | Diagnostic, plan. |
| architect | /architect | Architecte + editor model. | Refactor complexe. |
| help | /help | Aide sur Aider. | Options et commandes. |
/chat-mode ask /chat-mode code /chat-mode architect /code implement the approved patch /ask explain this module without editing
Workflow sûr : ask puis code
/ask Explain the import pipeline. Do not edit. Then: /code Implement option B only. Keep public behavior unchanged. Run the targeted test.
Architect / Editor mode
Le mode architect envoie dâabord la demande Ă un modĂšle architecte qui propose la solution, puis Ă un modĂšle Ă©diteur qui applique les modifications. Il peut ĂȘtre meilleur pour les tĂąches difficiles, mais plus cher et plus lent.
aider --architect --model openai/o3 --editor-model anthropic/claude-3-7-sonnet-20250219 app/services/search.py tests/test_search.py
| RĂŽle | Mission | Risque |
|---|---|---|
| Architect | Concevoir. | Plan trop ambitieux. |
| Editor | Appliquer. | Diff incomplet. |
| Weak model | Commit/résumé. | Approximation. |
Matrice de choix
| Situation | Mode | Instruction |
|---|---|---|
| Comprendre bug | /ask | Analyze only. |
| Fix trivial | /code | Change only this function. |
| Refactor multi-fichiers | /architect | One step at a time. |
| Migration DB | /ask dâabord | No migration yet. |
| Question outil | /help | Explain the command. |
Commandes slash essentielles
| Commande | Catégorie | Usage |
|---|---|---|
| /add | Contexte | Ajouter fichier éditable. |
| /read-only | Contexte | Ajouter doc non modifiable. |
| /drop | Contexte | Libérer contexte. |
| /ls | Contexte | Voir fichiers connus. |
| /map | Repo map | Afficher carte. |
| /tokens | Budget | Voir tokens. |
| /diff | Review | Voir diff. |
| /undo | Rollback | Annuler dernier patch. |
| /run | Execution | Lancer commande. |
| /test | Validation | Lancer test et corriger. |
| /lint | Qualité | Linter/corriger. |
| /web | Contexte | Ajouter page web. |
| /voice | Input | Dicter. |
| /editor | Prompt long | Ăcrire prompt structurĂ©. |
Session type
aider --read CONVENTIONS.md app/services/importer.py tests/test_importer.py > /ask Explain why duplicate rows are not detected. Do not edit files. > /ask Propose one minimal patch and the exact regression test. > /code Implement the minimal patch only. > /test python manage.py test tests.test_importer.DuplicateImportTests > /diff > /commit fix(importer): detect duplicate rows before batch insert
Exécution contrÎlée
| Commande | Comportement | Usage |
|---|---|---|
| /run python manage.py check | Lance et peut ajouter sortie. | Check Django. |
| /test python manage.py test app.tests.X | Corrige si échec. | Boucle test-fix. |
| /lint | Linte fichiers. | AprĂšs patch. |
| /git status | Commande Git brute. | ContrĂŽle local. |
/editor pour prompts sérieux
/editor Mission: Fix management command progress reporting. Scope: - edit only import_data.py - do not change models - do not create migrations Constraints: - keep --verbosity support - add counters and summary Validation: python manage.py import_data --dry-run --limit 10 --verbosity 2 python manage.py test app.tests.test_import_command
Boucle qualité
| Niveau | Commande | Valeur |
|---|---|---|
| Syntaxe | Built-in / ruff | Erreurs immédiates. |
| Unitaire ciblé | /test test spécifique | Preuve du bug. |
| Suite app | python manage.py test app | Régression locale. |
| CI | Pipeline complet | Validation finale. |
Configurer tests et linters
auto-lint: true lint-cmd: - "python: ruff check" - "python: python -m py_compile" test-cmd: "python manage.py test" auto-test: false
| Option | Avantage | Conseil |
|---|---|---|
| auto-lint true | Feedback rapide. | Ă activer. |
| auto-test true | Preuve continue. | Si tests rapides. |
| /test ciblé | Rapide. | Idéal gros Django. |
Test first avec Aider
/ask Find the missing regression test. Do not edit production code. /code Add only the failing regression test. /test python manage.py test importer.tests.test_duplicates /code Implement the smallest production fix. /test python manage.py test importer.tests.test_duplicates
CI et pre-commit
Local: ruff check python manage.py check python manage.py makemigrations --check --dry-run python manage.py test app
CI: install lint type check migration check unit tests integration tests coverage block merge on failure
Providers et modĂšles
Aider peut travailler avec des modĂšles cloud et locaux via OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, Ollama, LM Studio, Azure, Bedrock, Vertex AI et autres API compatibles.
| Famille | Usage fort | Attention |
|---|---|---|
| Raisonneur | Architecture, bug complexe. | Coût/latence. |
| Ăditeur | Diffs prĂ©cis. | Moins conceptuel. |
| Weak model | Commit/résumé. | Pas pour décisions. |
| Local LLM | Confidentialité. | Qualité variable. |
| OpenRouter/API compatible | Flexibilité. | Gouvernance provider. |
Combiner deux modĂšles
aider --architect --model openai/o3 --editor-model anthropic/claude-3-7-sonnet-20250219 --weak-model openai/gpt-4o-mini app/services/reporting.py tests/test_reporting.py
| Choix | Effet | Conseil |
|---|---|---|
| ModÚle fort partout | Qualité, coût. | Tùches critiques. |
| Weak model | Coût réduit. | Commits/résumés. |
| Editor model | Meilleurs edits. | Tester sur repo réel. |
Limiter les coûts
| Levier | Réduit | Risque |
|---|---|---|
| /drop | Tokens. | Retirer utile. |
| read-only docs | Répétition. | Docs obsolÚtes. |
| weak model | Coûts. | Approximation. |
Benchmark interne
Tasks: 1. Fix a failing unit test. 2. Add a Django command option. 3. Refactor one service function. 4. Add validation without DB change. 5. Improve template JS. Measure: - files changed - diff size - tests passed - human corrections - token cost - elapsed time - rollback complexity
Watch mode : Aider depuis ton IDE
Avec --watch-files, Aider surveille les fichiers et repĂšre des commentaires AI, AI! ou AI?.
aider --watch-files
def normalize_url(url):
# Add validation for empty and malformed URLs. AI!
...
# Explain why this strips query parameters. AI?| Marqueur | Effet | Usage |
|---|---|---|
| AI | Instruction contextuelle. | Préparer notes. |
| AI! | Déclenche modification. | Patch local. |
| AI? | Pose question. | Comprendre bloc. |
Web, images, clipboard
/web https://docs.example.com/api/v2/auth /paste screenshot_login_error.png /paste error_trace.txt Update the client to match the documented API. Do not change unrelated files.
| Contexte | Utile pour | Filtre |
|---|---|---|
| Page doc API | SDK, client HTTP. | Version de doc. |
| Screenshot | Bug UI/CSS. | Masquer données. |
| Trace | Debug backend. | Supprimer tokens. |
Voice-to-code
La voix est utile pour décrire un problÚme rapidement. Pour du code de production, relire et reformuler la transcription avant exécution.
/voice # Then edit: Use ask mode. Do not edit files. Summarize the suspected bug and ask for confirmation.
Remote, Docker, Codespaces
| Environnement | Avantage | Risque | Conseil |
|---|---|---|---|
| VS Code terminal | IDE + CLI. | Contexte non automatique. | watch/comments. |
| SSH dev server | Proche réel. | Confusion prod. | Prompt clair, jamais prod. |
| Codespaces | Sandbox cloud. | Secrets/coûts. | Secrets gérés. |
| Docker | Isolation. | Volumes/UID. | Wrapper script. |
Workflow Django
Django est trÚs adapté à Aider : structure claire, tests, commandes, apps, services, templates et migrations. La clé est de limiter le périmÚtre.
aider --read CONVENTIONS.md myapp/services/importer.py myapp/tests/test_importer.py /ask Explain why duplicate detection fails. Do not edit. /code Add one regression test and minimal fix. /test python manage.py test myapp.tests.test_importer
Models et migrations
| Action | Risque | Procédure |
|---|---|---|
| Ajouter champ | default, null, lock. | Plan DB avant code. |
| Renommer champ | Perte données. | Migration manuelle. |
| Ajouter index | Lock/coût/champ long. | Validation explicite. |
| Unique | Doublons existants. | Audit data avant contrainte. |
/ask Analyze migration impact only. Do not create migrations. Include SQL lock risk, rollback path and tests.
Management commands
Prompt: Improve this command. Scope: - add --dry-run - add --limit - add --verbosity-aware logging - add final counters - do not change models Validation: python manage.py import_keywords --dry-run --limit 10 --verbosity 2 python manage.py test tech_glossary.tests.test_import_keywords
| ĂlĂ©ment | Attendu |
|---|---|
| --dry-run | Aucune écriture DB. |
| --limit | Traitement borné. |
| --verbosity | Logs adaptés. |
| Counters | created, updated, skipped, errors. |
Templates HTML et JS
/code Create one new modal using the existing kcard / ig-modal pattern. Do not rewrite the whole template. Add only: - one card - one modal - one tab group - no global JS rewrite
| Risque | Prévention |
|---|---|
| Balise non fermée | Diff minimal + validation HTML. |
| JS global cassé | Ne pas toucher handlers existants. |
| CSS dupliqué | Réutiliser classes. |
Menaces principales
| Risque | Exemple | Protection |
|---|---|---|
| Secrets | Token dans log. | Masquer, .env non commité. |
| Données clients | Email/contrat en trace. | Anonymiser. |
| Commandes dangereuses | flush, drop, reset. | Validation humaine. |
| Dépendances | Package non contrÎlé. | Approval + scan. |
| Hallucination | API inexistante. | Tests et diff review. |
CONVENTIONS.md sécurité
# Security conventions for Aider - Never read or modify .env files. - Never paste secrets into chat. - Never add production credentials to code. - Never run destructive database commands. - Ask before adding dependencies. - Ask before creating migrations. - Auth, permissions and crypto changes require tests. - Do not weaken validation to make tests pass. - Prefer explicit failure over silent fallback.
Attribution et audit
Aider peut annoter lâauteur/committer ou le message de commit. En Ă©quipe, cette traçabilitĂ© aide la revue et lâapprentissage.
--attribute-commit-message-author --attribute-commit-message-committer --attribute-co-authored-by
Déploiement en équipe
| Maturité | RÚgles | Indicateurs |
|---|---|---|
| Solo | Conventions locales. | Diff size, tests. |
| Petite équipe | PR + CI + conventions. | Rework, bugs post-merge. |
| Entreprise | Policy modÚles, données, audit. | Coûts, adoption, incidents. |
Rollout: 1. Pilot with 2 senior developers. 2. Define allowed providers. 3. Create conventions. 4. Build 10 approved workflows. 5. Measure speed and defects. 6. Expand after review.
Méthode quotidienne
1. git status 2. git checkout -b task/aider-small-scope 3. identify exact target files 4. start aider with read-only conventions 5. /ask diagnosis only 6. approve minimal plan 7. /code implement one patch 8. /test targeted command 9. /diff and human review 10. push branch and PR
| Ătape | Question de contrĂŽle |
|---|---|
| Avant patch | Quels fichiers doivent changer ? |
| AprÚs patch | Le diff est-il limité ? |
| Avant commit | Quel test prouve le résultat ? |
| Avant PR | Le message explique-t-il le pourquoi ? |
Prompts prĂȘts
Diagnostic: /ask Analyze this failure. Do not edit files. Identify code path, likely cause and minimal fix. Patch: /code Implement the minimal fix only. Do not refactor unrelated code. Add or update one regression test. Review: /ask Review the last diff for security, performance, compatibility, migration risk and hidden behavior changes. Rollback: /ask Explain how to safely rollback the last change. Do not edit files. Django migration: /ask Analyze migration impact only. Do not create migrations.
Dépannage
| SymptĂŽme | Cause | Correction |
|---|---|---|
| Trop de fichiers modifiés | Scope vague. | /drop + prompt étroit. |
| Réponse incohérente | Contexte saturé. | /tokens, /ls, /map-refresh. |
| Tests non lancés | test-cmd absent. | Configurer ou /test ciblé. |
| Coût trop élevé | Historique long. | Nouvelle session, /drop, weak model. |
| Erreur provider | Clé ou modÚle. | /models, env vars. |
Sources et repÚres vérifiés
- Aider official website â terminal pair programming, repo map, Git integration, 100+ languages, voice/web/images, lint/test et chiffres publics.
- Aider documentation â installation, usage, modes chat, commandes, conventions, lint/test, YAML config.
- Repository map docs â carte concise du dĂ©pĂŽt, symboles, signatures et ranking par graphe.
- Git integration docs â auto-commit, dirty files, /diff, /undo, attribution.
- Cursor guide attachĂ© â layout IDEO-Lab rĂ©utilisĂ© : kgrid/kcard, modals, tabs, boutons Copy/Print/Close, CSS clair.
URLs: https://aider.chat/ https://aider.chat/docs/ https://aider.chat/docs/install.html https://aider.chat/docs/usage/modes.html https://aider.chat/docs/usage/commands.html https://aider.chat/docs/repomap.html https://aider.chat/docs/git.html https://aider.chat/docs/usage/lint-test.html https://aider.chat/docs/usage/conventions.html https://aider.chat/docs/config/aider_conf.html
