Chapitre 1.1 — Un agent, pas un chatbot

⏱️ TL;DR — Claude Code n’est pas une zone de chat qui « connaît » ton projet et te rend du code. C’est un agent : il tourne dans une boucle perçois → raisonne → agis → observe, en utilisant des outils (lire un fichier, écrire, lancer une commande, chercher). Il ne sait rien de ton repo tant qu’il ne l’a pas lu, et il oublie tout à la fin de la session sauf ce que tu as rendu persistant. Intégrer ça change radicalement ta façon de demander : tu ne « décris » plus, tu cadres un environnement de travail.

🎯 Objectifs

• Distinguer un chatbot (une réponse par message) d’un agent (une boucle d’actions vers un objectif).
• Décrire la boucle agentique de Claude Code et le rôle des outils.
• Comprendre les trois conséquences pratiques : l’agent part ignorant, son contexte est limité, sa mémoire est volatile.
• Reformuler une demande « façon chatbot » en demande « façon agent ».

Le déclic

Prends deux façons de demander la même chose.

Façon chatbot (ce que beaucoup font) :

« Voici mon composant <Button> (copier-coller de 60 lignes). Peux-tu me faire un <IconButton> dans le même style ? »

Façon agent :

« Crée un <IconButton> cohérent avec nos composants existants. Regarde src/components/Button.tsx pour le style et src/components/ui/ pour nos conventions. »

La deuxième est plus courte et donne un meilleur résultat. Pourquoi ? Parce que dans le premier cas tu traites l’outil comme une boîte qui ne voit que ton message. Dans le second, tu lui dis où aller chercher — et il ira lire les fichiers, en déduire les conventions, et produire quelque chose qui s’intègre. C’est ça, un agent : il agit sur ton environnement, il ne se contente pas de répondre.

💡 Réflexe d’architecte — Ne colle pas ce que l’agent peut aller lire lui-même. Pointe-le vers la source. Un bon prompt ressemble souvent plus à un ticket (« fais X, les conventions sont là, le modèle est ce fichier ») qu’à une dissertation.

La boucle agentique

Un chatbot, c’est une fonction : message → réponse. Un agent, c’est une boucle qui continue jusqu’à ce que l’objectif soit atteint :

À chaque tour, l’agent choisit un outil et observe le résultat, puis recommence. Les outils typiques de Claude Code :

Quand tu vois Claude Code « réfléchir », puis lire trois fichiers, lancer les tests, éditer, relancer les tests — tu regardes la boucle tourner. Il ne devine pas ; il observe. C’est pour ça qu’il est fiable sur un vrai codebase là où un simple LLM en chat hallucine des API.

⚠️ Piège — Croire que l’agent « a déjà lu tout ton projet ». Non. Au démarrage, il ne connaît que ce que tu lui dis et ce que le harness lui injecte automatiquement (dont ton CLAUDE.md). Le reste, il doit aller le lire. Si tu lui demandes de modifier une fonction sans lui dire où elle est, son premier pas sera… de la chercher. Autant lui donner le chemin.

Trois conséquences qui changent tout

1. L’agent part ignorant (mais curieux)

Chaque session démarre quasiment à zéro sur ton projet. Il compensera en explorant, mais l’exploration coûte (du temps, du contexte) et peut partir dans la mauvaise direction. → D’où l’importance de lui donner des points d’entrée (Partie 2) et un CLAUDE.md (Partie 3).

2. Son contexte est limité et périssable

Tout ce qu’il « voit » tient dans une fenêtre de contexte de taille finie. Plus la session est longue, plus elle se remplit (fichiers lus, sorties de commandes, raisonnement). Quand c’est trop plein, il faut compacter ou repartir propre. → C’est le sujet du chapitre 1.3 et de la Partie 5.

3. Sa mémoire entre sessions est ce que TU rends persistant

Ferme la session, et le contexte disparaît. Ce qui survit, c’est ce qui est écrit sur le disque : ton code, ton CLAUDE.md, tes skills, ta config. → Bien piloter Claude Code, c’est en grande partie transformer des instructions volatiles en artefacts persistants. Tout le playbook tourne autour de ça.

💡 Réflexe d’architecte — Chaque fois que tu te surprends à répéter une consigne (« utilise nos alias d’import », « pas de any »), demande-toi : est-ce que je devrais rendre ça persistant ? Une règle répétée = candidate pour le CLAUDE.md (si c’est une convention) ou pour un hook (si c’est mécanique et vérifiable).

Reformuler « chatbot → agent »

Un exercice mental à faire jusqu’à ce qu’il devienne automatique :

Ce que ça implique pour la suite

Ce basculement est la clé de voûte. Les parties suivantes ne sont que des déclinaisons :

• Cadrer un projet (P2) = donner à l’agent le bon environnement de départ.
• CLAUDE.md (P3) = rendre tes conventions persistantes.
• Cohérence (P4) = ancrer le design pour qu’il n’improvise pas.
• Hooks (P7) = automatiser le vérifiable au lieu de le répéter.
• Subagents (P8) = déléguer une sous-boucle isolée.

✏️ Exercices

Exercice 1 — Chasse au chatbot. Reprends tes 3 derniers prompts à Claude Code. Pour chacun, repère : as-tu collé du code qu’il aurait pu lire ? As-tu donné un critère de fin (« les tests passent », « ça build ») ? Réécris-les « façon agent ».

Exercice 2 — Trace la boucle. Lance une petite tâche réelle (« ajoute un champ dueDate optionnel à mon type Task ») et observe les outils que l’agent enchaîne. Note l’ordre : cherche-t-il d’abord ? lit-il un fichier ? édite-t-il puis vérifie-t-il ?

🧠 Quiz de révision

Chapitre suivant : Installation & surfaces — installer Claude Code et choisir le bon terrain de jeu.