Sommaire
Série « Apprendre à coder avec l’IA » — Article 2/7
RSS
Le RSS envoie les nouveaux articles dans le lecteur de votre choix, sans algorithme ni newsletter.
TL;DR
Un agent de code travaille mieux lorsque le besoin, la stack, les conventions et les critères de validation sont explicites. Préparer le projet ne consiste pas à écrire un prompt de cinquante lignes. Il s’agit de prendre soi-même les décisions qui structurent l’apprentissage.
Le premier prompt ne devrait pas demander du code
Quand on découvre Claude Code ou Codex, la tentation est immédiate : décrire une application et regarder l’agent la fabriquer.
Pour notre mini-dashboard, cela donnerait :
Crée un dashboard Next.js moderne qui affiche l’état de mes serveurs.
Ajoute les appels API, les tests et une belle interface.
Ce prompt peut produire beaucoup de fichiers. Il ne dit pourtant presque rien.
Quelles métriques faut-il afficher ? D’où viennent-elles ? Que voit l’utilisateur pendant le chargement ? Comment signaler une API indisponible ? L’authentification fait-elle partie du périmètre ? Qu’est-ce qui permet de considérer le travail comme terminé ?
Lorsque ces décisions manquent, l’agent les prend. Le junior découvre ensuite une architecture qu’il n’a ni choisie ni comprise.
Commencer par une fiche de besoin courte
Notre première version peut tenir dans quelques lignes :
# Mini-dashboard — périmètre V1
## Objectif
Afficher l’état synthétique d’un serveur à partir d’une API simulée.
## Métriques
- état du service ;
- charge CPU en pourcentage ;
- mémoire utilisée et totale ;
- espace disque utilisé et total.
## États à gérer
- chargement ;
- succès ;
- API indisponible ;
- réponse invalide.
## Hors périmètre
- authentification réelle ;
- base de données ;
- historique des métriques ;
- graphiques temps réel.
Ce document oblige à distinguer le besoin réel des idées qui pourraient venir plus tard.
Définir ce que « terminé » signifie
Une tâche vague pousse l’agent à s’arrêter lorsqu’il estime le résultat satisfaisant. Une tâche vérifiable lui donne une limite.
Pour la carte CPU :
## Critères d’acceptation
- La carte affiche une valeur comprise entre 0 et 100.
- Une unité `%` est visible.
- Une valeur absente ou invalide ne provoque pas de crash.
- Un état explicite remplace la métrique invalide.
- Le comportement principal est couvert par un test.
Ces critères ne sont pas réservés aux chefs de projet. Ils apprennent au développeur à transformer une intention en comportement observable.
Choisir une stack sans collectionner les dépendances
Notre socle sera volontairement classique :
- TypeScript pour expliciter les structures de données ;
- React pour construire les composants ;
- Next.js pour le cadre applicatif ;
- Vitest et React Testing Library pour les tests unitaires ciblés ;
- une validation d’exécution pour les données externes, si le besoin est confirmé.
Next.js intègre directement TypeScript et fournit sa configuration lors de la création du projet. Sa documentation TypeScript reste la référence pour le comportement actuel. Pour les tests, le guide officiel présente plusieurs options, notamment Vitest, Jest, Playwright et Cypress.
Le choix d’un outil doit répondre à une question. « L’IA connaît cette bibliothèque » n’est pas un critère d’architecture.
Dessiner une architecture assez petite pour être comprise
Une première organisation pourrait être :
src/
app/
page.tsx
components/
MetricCard.tsx
ServerOverview.tsx
features/
server-status/
api.ts
schema.ts
types.ts
test/
Cette arborescence n’est pas une vérité universelle. Elle matérialise simplement trois responsabilités :
- récupérer les données ;
- vérifier leur forme ;
- les afficher.
Si le junior ne peut pas expliquer la raison d’un dossier, ce dossier est peut-être prématuré.
Écrire les règles permanentes du dépôt
Claude Code peut lire des instructions de projet dans CLAUDE.md. Codex utilise notamment AGENTS.md pour les conventions durables du dépôt. Les documentations officielles décrivent la mémoire et les instructions de Claude Code ainsi que la personnalisation de Codex.
Notre fichier de règles pourrait contenir :
# Règles du projet
- Utiliser TypeScript en mode strict.
- Ne pas employer `any` sans justification écrite.
- Ne pas ajouter de dépendance sans expliquer le besoin et les alternatives.
- Séparer l’accès API de l’affichage.
- Valider toute donnée externe avant son utilisation.
- Modifier peu de fichiers par étape.
- Présenter un plan avant toute modification importante.
- Exécuter le typage, le lint et les tests pertinents.
- Signaler clairement ce qui n’a pas pu être vérifié.
Ce fichier ne doit pas devenir une constitution illisible. Une règle mérite d’y entrer lorsqu’elle est stable, concrète et vérifiable.
Demander une analyse avant l’implémentation
Le premier échange utile avec l’agent peut ressembler à ceci :
Analyse la fiche de besoin et les règles du dépôt.
Ne modifie aucun fichier.
Je veux que tu :
1. identifies les décisions encore manquantes ;
2. proposes un découpage en tâches de moins d’une heure ;
3. listes les risques techniques ;
4. indiques comment vérifier chaque étape ;
5. me poses des questions au lieu de choisir silencieusement.
Le junior doit ensuite challenger le plan. Pourquoi cette dépendance ? Pourquoi un composant client ? Pourquoi ce test ? Que se passe-t-il avec une réponse invalide ?
Préparer Git avant de laisser l’agent agir
Avant la première modification :
- initialise le dépôt ;
- vérifie les fichiers suivis ;
- crée un premier commit propre ;
- assure-toi que les secrets et fichiers locaux sont ignorés ;
- apprends à afficher un diff et à revenir à un état connu.
Un historique propre ne sert pas seulement à réparer une erreur. Il permet de comparer ce que l’agent a annoncé avec ce qu’il a réellement modifié.
La préparation fait déjà partie de l’apprentissage
À ce stade, nous n’avons presque rien codé. Pourtant, nous avons travaillé des compétences fondamentales : cadrer, découper, choisir, prévoir et vérifier.
C’est précisément ce que le prompt « fais-moi toute l’application » aurait rendu invisible.
Dans le prochain article, nous verrons comment trouver, inspecter et adapter des skills sans transformer le projet en collection de règles contradictoires.
