Le hackbook des agents de code : 40 techniques pour livrer plus vite avec l'IA

Écris la carte du repo une fois

DébutantContexte · Équipe

Garde un court fichier d'instructions pour agents à la racine du repo : stack, commandes de build et de tests, conventions, zones interdites. La plupart des agents le lisent au début de chaque session, alors tu arrêtes de te répéter.

▸ Détails

Demande à l'agent de le rédiger à partir du code.
Coupe jusqu'à ce qui serait utile à une nouvelle recrue le premier jour.
Commit-le et mets-le à jour chaque fois que l'agent répète une erreur.

Prompt de départ

Lis ce repository et rédige un fichier d'instructions pour agents (moins de 60 lignes) qui couvre :
- La stack et les dossiers clés
- Les commandes exactes pour installer, builder, linter et tester
- Les conventions de code qu'on suit vraiment (cite des fichiers d'exemple)
- Les dossiers et fichiers qu'il ne faut jamais modifier
Signale ce dont tu n'es pas sûr au lieu de deviner.

Pointe, ne colle pas

DébutantContexte

Donne des chemins de fichiers, des noms de fonctions et des plages de lignes plutôt que de coller du code dans le chat. L'agent lit la version à jour, et tu évites de lui refiler une copie périmée.

Clone un bon exemple

DébutantContexte · Prompts

Nomme un fichier existant comme modèle à suivre. « Fais-le comme celui-là » bat trois paragraphes qui décrivent tes conventions.

▸ Détails

Prompt de départ

Crée [NOUVEL_ÉLÉMENT] en suivant la même structure, le même nommage et la même gestion d'erreurs que [CHEMIN_DU_FICHIER_EXEMPLE]. N'introduis aucun nouveau pattern ni aucune nouvelle librairie. Liste chaque endroit où tu as dû t'en écarter, et pourquoi.

Une session neuve par tâche

DébutantContexte

Les longues conversations accumulent des suppositions périmées et des culs-de-sac. Pars une session propre pour chaque tâche, pour que l'agent raisonne à partir du code et non d'une heure de jasette.

Une note de passation avant de repartir

Utilisateur avancéContexte · Planification

Avant de vider une longue session, fais écrire à l'agent un fichier de passation : objectif, décisions, fichiers touchés, prochaine étape. La session suivante part de cette note au lieu de partir de zéro.

▸ Détails

Prompt de départ

Écris une note de passation dans [CHEMIN_FICHIER_PASSATION] pour une nouvelle session qui va continuer cette tâche. Inclus :
1. L'objectif en une phrase
2. Les décisions prises et pourquoi
3. Les fichiers modifiés jusqu'ici
4. Ce qui est vérifié et ce qui ne l'est pas encore
5. La prochaine étape exacte
Moins de 40 lignes.

Clôture les zones interdites

DébutantContexte · Git et sécurité

Dis explicitement quels dossiers sont hors limites : code généré, migrations, librairies vendorisées, lockfiles. Les agents respectent bien mieux une frontière qu'ils ne la devinent.

Apporte la doc à l'agent

Utilisateur avancéContexte

Pour les librairies qui bougent vite, sauvegarde la page de doc ou le changelog pertinent dans un fichier local et pointe l'agent dessus. Ses données d'entraînement peuvent être en retard sur ta version.

▸ Détails

Vérifie la version de la librairie dans ton lockfile.
Sauvegarde la section de doc correspondante dans un dossier de référence local.
Dis à l'agent de suivre ce fichier plutôt que sa mémoire.

Tiens un glossaire métier

Utilisateur avancéContexte · Équipe

Une courte liste des termes d'affaires et de leur sens dans le code empêche l'agent d'inventer des noms. « Compte » et « Client » ne devraient jamais devenir synonymes par accident.

Résultat, contraintes, terminé quand

DébutantPrompts

Chaque brief répond à trois questions : qu'est-ce qui doit exister à la fin, qu'est-ce qui ne doit pas changer, et comment on sait que ça marche. Un objectif flou donne du code plausible, mais faux.

▸ Détails

Prompt de départ

Objectif : [CE QUI DOIT EXISTER QUAND TU AS FINI]
Contexte : [FICHIERS OU TICKET PERTINENTS]
Contraintes : [CE QUI NE DOIT PAS CHANGER, LIBRAIRIES À UTILISER OU À ÉVITER]
Terminé quand : [COMMANDE QUI DOIT PASSER] et [COMPORTEMENT QUE JE PEUX VÉRIFIER À LA MAIN]
Travaille par petites étapes et arrête-toi si une contrainte te bloque.

Des questions avant le code

DébutantPrompts · Planification

Demande à l'agent de lister ses questions de clarification avant d'écrire quoi que ce soit. Dix secondes de réponses t'épargnent vingt minutes dans la mauvaise direction.

▸ Détails

Prompt de départ

Avant d'écrire du code, pose-moi jusqu'à 5 questions de clarification sur [TÂCHE]. Pose seulement celles dont tu ne peux pas trouver la réponse en lisant le repository. Ensuite, attends mes réponses.

Fais-le reformuler

DébutantPrompts

Demande à l'agent de reformuler la tâche et son approche en trois puces. Si la reformulation est à côté, tu as attrapé le malentendu avant qu'il devienne un diff.

Une tâche par prompt

DébutantPrompts

Mélanger un bug fix, un refactor et une nouvelle fonctionnalité dans une seule demande brouille le diff et la revue. Fais-en des tâches séparées, même si elles touchent le même fichier.

Dis ce qu'il ne faut pas faire

DébutantPrompts · Git et sécurité

Les agents aiment en faire plus que demandé. Une courte liste de « ne fais pas » les empêche d'ajouter des dépendances, de renommer des choses ou de faire le ménage dans du code sans rapport.

▸ Détails

Prompt de départ

Pendant que tu fais [TÂCHE] :
- N'ajoute aucune nouvelle dépendance
- Ne renomme et ne déplace aucun fichier existant
- Ne refactorise pas de code en dehors de [PÉRIMÈTRE]
- Ne modifie pas les tests sauf si je le demande
Si tu penses qu'un de ces points est nécessaire, arrête-toi et demande-moi.

Colle l'erreur telle quelle

DébutantPrompts · Vérification

Donne l'erreur complète, la stack trace et la commande exacte qui l'a produite. Une erreur paraphrasée envoie l'agent chercher à la mauvaise place.

Le plan d'abord, le code ensuite

DébutantPlanification

Demande un plan écrit avec les fichiers à toucher et l'ordre des changements, révise-le, puis donne le go. Corriger un plan prend une minute; corriger un diff prend un après-midi.

▸ Détails

Prompt de départ

N'écris pas de code tout de suite. Propose un plan pour [TÂCHE] :
- Fichiers à créer ou à modifier, et pourquoi
- Ordre des changements
- Comment chaque étape sera vérifiée
- Risques ou inconnues
Je vais le réviser avant que tu commences.

Le plan comme checklist dans le repo

Utilisateur avancéPlanification

Garde le plan dans une checklist markdown que l'agent coche au fur et à mesure. Elle survit aux redémarrages de session et te montre l'avancement d'un coup d'œil.

Des tranches minces et verticales

Utilisateur avancéPlanification

Découpe les fonctionnalités en tranches minces de bout en bout, chacune fonctionnelle et testable seule. Les agents réussissent bien mieux cinq petites victoires qu'un seul grand saut.

▸ Détails

Demande à l'agent de découper la fonctionnalité en tranches qui roulent chacune de bout en bout.
Construis et vérifie une tranche par session.
Commit après chaque tranche au vert.

Un spike, puis à la poubelle

Utilisateur avancéPlanification

Laisse l'agent bâtir un prototype jetable pour découvrir où sont les parties difficiles. Ensuite, jette-le et recommence avec un plan propre, nourri de ce que tu as appris.

Demande trois options

DébutantPlanification

Demande deux ou trois approches avec leurs compromis avant d'en choisir une. Tu restes l'architecte, et l'agent fait souvent ressortir une option à laquelle tu n'avais pas pensé.

▸ Détails

Prompt de départ

Propose 3 approches différentes pour [PROBLÈME]. Pour chacune : une courte description, les fichiers touchés, le principal compromis et ce qui pourrait mal tourner. Recommande-en une et explique pourquoi. Pas de code pour l'instant.

Fais le pré-mortem du plan

Utilisateur avancéPlanification · Vérification

Demande : « Suppose que ce plan a échoué en production. Qu'est-ce qui a mal tourné? » L'agent est étonnamment bon pour attaquer un plan qu'il n'est pas en train de défendre.

▸ Détails

Prompt de départ

Suppose que le plan dans [FICHIER_DU_PLAN] a été livré et a causé un incident une semaine plus tard. Liste les 5 causes les plus probables, de la plus à la moins probable, et le changement au plan qui éviterait chacune.

Donne-lui un moyen de se vérifier

DébutantVérification

Donne à l'agent les commandes exactes de tests, de lint et de vérification de types, et exige qu'elles passent avant qu'il dise « terminé ». Un agent avec une boucle de rétroaction corrige ses propres erreurs.

▸ Détails

Prompt de départ

Après chaque changement, roule [COMMANDE_DE_TESTS] et [COMMANDE_DE_LINT]. Ne déclare pas la tâche terminée tant que les deux ne passent pas. Si quelque chose échoue trois fois de suite, arrête-toi et explique ce que tu as essayé.

Une seule commande de vérif rapide

Utilisateur avancéVérification · Équipe

Regroupe le lint, les types et les tests unitaires rapides dans une seule commande qui roule en une minute environ. Plus la vérif est bon marché, plus l'agent (et toi) la lancerez souvent.

Un test qui échoue d'abord

Utilisateur avancéVérification

Pour un bogue, fais écrire à l'agent un test qui reproduit le problème et confirme qu'il échoue. Ensuite, corrige. « Réglé » veut maintenant dire quelque chose que tu peux prouver.

▸ Détails

Prompt de départ

Bogue : [DESCRIPTION ET ÉTAPES POUR REPRODUIRE]
1. Écris un test qui reproduit ce bogue. Roule-le et montre-moi qu'il échoue.
2. Seulement ensuite, corrige le code.
3. Roule le test de nouveau, puis toute la suite, et montre les deux sorties.

Lis le diff, pas le résumé

DébutantVérification

Le résumé de l'agent, c'est son opinion sur ce qu'il a fait; le diff, c'est ce qu'il a vraiment fait. Révise le diff chaque fois, surtout les fichiers que tu n'attendais pas.

Un réviseur à l'œil neuf

Utilisateur avancéVérification

Ouvre une nouvelle session et demande-lui de réviser le diff comme un ou une senior sceptique. Sans le contexte de l'écriture, l'agent repère des problèmes qu'il aurait autrement défendus.

▸ Détails

Prompt de départ

Tu révises une pull request que tu n'as pas écrite. Révise les changements de [BRANCH] par rapport à [BRANCH_DE_BASE]. Cherche : bogues, cas limites oubliés, erreurs non gérées, problèmes de sécurité et changements hors du périmètre annoncé ([PÉRIMÈTRE]). Classe les constats par gravité. Ne corrige rien pour l'instant.

Demande les reçus

DébutantVérification

Quand l'agent dit que les tests passent, demande la sortie réelle de la commande. Ça révèle vite les vérifs sautées, roulées à moitié ou jamais lancées.

Méfie-toi des tests trafiqués

Utilisateur avancéVérification · Git et sécurité

Sous pression pour passer au vert, un agent peut affaiblir des assertions, sauter des tests ou coder un cas spécial pour l'entrée du test. Regarde les changements aux fichiers de tests avec une méfiance accrue.

Vérifie l'interface de tes yeux

DébutantVérification

Des tests qui passent ne veulent pas dire que la page a l'air correcte. Pour du travail d'interface, ouvre-la toi-même, ou laisse l'agent prendre des captures si ton setup le permet, avant de dire que c'est fini.

Un worktree par agent

Utilisateur avancéEn parallèle · Git et sécurité

Donne à chaque agent en parallèle son propre worktree git et sa propre branch. Ils peuvent builder et tester en même temps sans écraser les fichiers des autres.

▸ Détails

Crée un worktree par tâche, chacun sur sa propre branch.
Lance une session d'agent dans chaque worktree.
Merge une branch à la fois, en roulant les vérifs après chaque merge.

Découpe selon les frontières de fichiers

Utilisateur avancéEn parallèle · Planification

Les tâches en parallèle devraient toucher des parties différentes du code. Si deux tâches modifient les mêmes fichiers, fais-les l'une après l'autre et évite-toi les conflits de merge.

Les petites corvées en arrière-plan

DébutantEn parallèle

Confie les petites corvées bien définies (une passe sur les coquilles, une mise à jour de dépendance, un test manquant) à un agent en arrière-plan pendant que tu te concentres sur le problème difficile.

Fais courir deux approches

Utilisateur avancéEn parallèle · Planification

Quand tu hésites entre deux designs, demande à deux agents de les implémenter dans des branches séparées. Comparer du code qui roule bat débattre d'hypothèses.

Un agent éclaireur, un agent bâtisseur

Utilisateur avancéEn parallèle · Contexte

Laisse une session enquêter (lire le code, suivre un flux, écrire ses constats dans un fichier) pendant qu'une autre implémente à partir de ces constats. Le bruit de recherche reste hors du contexte du bâtisseur.

▸ Détails

Prompt de départ

Enquête sur le fonctionnement de [FONCTIONNALITÉ OU FLUX] dans ce code. Ne modifie aucun code. Écris tes constats dans [FICHIER_DE_NOTES] : points d'entrée, fichiers clés, flux de données et tout ce qui est surprenant. Moins de 50 lignes.

Commit avant de déléguer

DébutantGit et sécurité

Démarre chaque tâche d'agent à partir d'un arbre de travail propre. Si le résultat est mauvais, tu le jettes en une commande au lieu de tout démêler à la main.

Petits commits, historique lisible

DébutantGit et sécurité

Demande à l'agent de faire un commit après chaque étape vérifiée, avec un message clair. Tu obtiens des points de retour et un historique que les réviseurs peuvent suivre.

Garde les secrets hors de portée

DébutantGit et sécurité

Ne laisse pas de vrais identifiants dans des fichiers que l'agent peut lire. Utilise un fichier env d'exemple avec de fausses valeurs et des comptes de test à portée limitée pour tout ce qu'il doit rouler.

Mets un verrou sur les commandes dangereuses

DébutantGit et sécurité · Équipe

La plupart des agents te laissent décider quelles actions demandent ton approbation. Garde les suppressions, les force push, les migrations et les déploiements derrière un oui humain.

Une branch par tâche, une PR par branch

DébutantGit et sécurité · Équipe

Le travail des agents passe par le même flux de pull request et de revue que le travail humain. Pas de push direct sur main, pas de voie spéciale pour le code écrit par l'IA.

Transforme les erreurs répétées en règles

DébutantÉquipe · Contexte

Quand l'agent fait deux fois la même erreur, ajoute une ligne au fichier d'instructions. En quelques semaines, ce fichier devient le meilleur document d'accueil de ton équipe.

Bâtis une librairie de prompts d'équipe

Utilisateur avancéÉquipe · Prompts

Sauvegarde les prompts qui ont marché dans un dossier partagé du repo, avec des placeholders pour les parties qui changent. Les bons prompts deviennent des actifs d'équipe plutôt que des trucs personnels.

▸ Détails

Crée un dossier de prompts dans le repo.
Ajoute un prompt seulement après qu'il a marché sur une vraie tâche.
Révise les changements de prompts en pull request, comme n'importe quel code.

Le hackbook des agents de code : 40 techniques pour livrer plus vite avec l'IA

Les 40 hacks

Bon hack ou mauvaise habitude?

Pannes fréquentes et solutions

Prépare ton repo en 20 minutes

Petit test