Tutoriel IA : créer un journal de passation pour agents Cursor, Claude et Codex

[CrdaN]

Tutoriel IA : créer un journal de passation pour agents Cursor, Claude et Codex
Quand on utilise plusieurs agents IA sur un même projet, le vrai problème n’est pas toujours le code : c’est la mémoire du travail en cours. Un petit journal de passation évite beaucoup de confusion.​

Cursor, Claude Code, Codex, ChatGPT, Copilot… chaque outil peut être excellent sur une tâche précise. Mais dès qu’on alterne entre plusieurs agents, ou qu’on reprend un projet le lendemain, un problème revient vite : l’agent ne sait plus exactement ce qui a été tenté, pourquoi ça a bloqué, et ce qu’il ne faut surtout pas refaire.

Résultat classique : on relance la même analyse, on retouche les mêmes fichiers, on oublie une décision, ou un nouvel agent propose un plan déjà refusé. Pour un bot Discord, un site communautaire, un outil marketplace, un script d’automatisation ou un projet web, ça finit par faire perdre du temps.

La solution est simple : créer un journal de passation, version propre et courte. Pas une documentation énorme. Juste un fichier que l’agent lit au début et met à jour à la fin.

À quoi sert un journal de passation ?

Un journal de passation répond à trois questions :

• Qu’est-ce qui a été fait ?
• Pourquoi certaines décisions ont été prises ?
• Quelle est la prochaine action sûre ?

C’est très utile quand :

• vous passez de Cursor à Claude Code ou Codex ;
• vous lancez un agent le matin puis un autre le soir ;
• vous travaillez sur plusieurs branches ;
• vous avez un bot ou un outil qui touche à des clés API ;
• vous voulez éviter les modifications en boucle ;
• vous devez relire rapidement l’état du projet avant de dire “go”.

Le but n’est pas de tout raconter. Le but est de garder les décisions importantes et les limites de sécurité.

Où mettre le fichier ?

Sur un projet perso ou communautaire, je conseille un fichier simple :

• `AI_HANDOFF.md` à la racine du projet ;
• ou `.ai/HANDOFF.md` si vous préférez ranger les fichiers IA ;
• ou `docs/ai-handoff.md` si votre documentation est déjà dans `docs/`.

Évitez de le mettre dans un dossier temporaire que personne ne relira. Le fichier doit être visible, versionnable avec Git, et facile à ouvrir.

Attention : ce fichier ne doit jamais contenir de secrets. Pas de token Discord, pas de clé OpenAI, pas de cookie, pas de mot de passe, pas d’URL privée sensible.

La structure qui marche bien

Un bon journal de passation est court. Si le fichier devient un roman, les agents vont mal le lire ou le résumer trop vite.

Pour voir le contenu, vous devez réagir aux messages avec l'une de ces réactions :

Réagir, Love, Haha, Oula, Triste, Colère

Ce modèle suffit dans 90% des cas. Il donne assez de contexte à l’agent sans transformer le projet en usine à gaz.

Comment l’utiliser avec un agent IA

Au début d’une session, demandez à l’agent de lire le journal avant de proposer quoi que ce soit.

Bonne consigne :

Lis `AI_HANDOFF.md`, puis résume l’état actuel en 5 lignes. Ne modifie rien tant que je n’ai pas validé la prochaine étape.

Ensuite seulement, vous autorisez l’analyse ou la modification. À la fin, demandez une mise à jour courte du fichier.

Mets à jour `AI_HANDOFF.md` avec ce qui a changé, les décisions prises, les tests lancés et la prochaine étape. N’ajoute aucun secret.

Ça paraît basique, mais ça change vraiment le workflow : chaque agent arrive avec un minimum de mémoire utile.

Ce qu’il faut noter, et ce qu’il faut éviter

À noter :

• les fichiers modifiés ;
• les décisions techniques ;
• les tests qui passent ou échouent ;
• les pistes abandonnées ;
• les zones risquées ;
• les questions bloquantes ;
• les consignes de sécurité du projet.

À éviter :

• copier-coller des logs énormes ;
• stocker des clés API ou tokens ;
• écrire des prompts interminables ;
• noter des suppositions comme si elles étaient confirmées ;
• mettre à jour le journal sans relire le diff.

Le journal doit rester utile pour un humain. Si vous ne pouvez pas le relire en moins de deux minutes, il est trop long.

Cas pratique : bot Discord ou outil forum

Imaginez un bot Discord communautaire avec une commande `/support`. Cursor a commencé à refactorer les commandes, puis vous voulez demander à Codex d’ajouter un cache ou à Claude de revoir la sécurité.

Sans journal, le nouvel agent risque de repartir de zéro.

Avec journal, il voit rapidement :

• où sont les commandes ;
• quelle branche est utilisée ;
• quel fichier contient les variables d’environnement ;
• quels tests existent ;
• quelle approche a déjà été refusée ;
• quels fichiers sont interdits sans validation.

C’est particulièrement important dès qu’il y a une base de données, des permissions Discord, des webhooks, un espace admin ou des clés API.

Prompt de passation prêt à copier

Pour voir le contenu, vous devez réagir aux messages avec l'une de ces réactions :

Réagir, Love, Haha, Oula, Triste, Colère

Petit conseil Git

Si le journal est dans le repo, relisez son diff comme n’importe quel fichier. Un agent peut parfois écrire trop de détails, ou noter une hypothèse fausse. Le fichier doit aider le prochain run, pas polluer le projet.

Vous pouvez aussi décider que `AI_HANDOFF.md` reste local et non versionné si le projet est public. Dans ce cas, ajoutez-le au `.gitignore`, mais gardez-le propre quand même.

Conclusion

Un journal de passation IA, c’est petit, simple, et très rentable. Il évite aux agents de tourner en rond, facilite le passage entre Cursor, Claude, Codex ou ChatGPT, et garde les décisions importantes visibles.

Pour Cheat-Gam3, c’est un réflexe à prendre sur tous les projets communautaires : un agent peut coder vite, mais il travaille mieux quand il sait ce qui s’est déjà passé.