Tutoriel IA : créer un dossier contexte propre pour Cursor, Claude ou Codex

[CrdaN]

Tutoriel IA : créer un dossier contexte propre pour Cursor, Claude ou Codex

Les agents IA deviennent vraiment utiles quand ils comprennent le projet avant de toucher au code. Le problème, c’est que beaucoup de gens ouvrent Cursor, Claude Code ou Codex, collent une demande vague du style “corrige mon bot Discord”, puis s’étonnent que l’agent modifie dix fichiers, casse une config ou parte dans une mauvaise direction.

La solution n’est pas forcément d’avoir un prompt énorme. La solution, c’est d’avoir un petit dossier contexte dans le projet : quelques fichiers courts, lisibles, maintenus, qui expliquent à l’IA comment travailler sans deviner.

C’est valable pour un site, un bot Discord, un outil forum, un script d’automatisation, un projet Minecraft/Palworld, un launcher, un dashboard ou une API. Plus le projet est bricolé dans le temps, plus ce dossier devient rentable.

Le principe​

Un agent IA n’a pas besoin de tout savoir. Il a besoin de savoir où regarder, ce qu’il ne doit pas casser et comment valider son travail.

Le dossier contexte sert donc à répondre à 5 questions :

1. À quoi sert le projet ?
2. Comment il se lance et se teste ?
3. Quelles règles de sécurité sont non négociables ?
4. Quels fichiers sont sensibles ou à éviter ?
5. Quel style de réponse ou de code on attend ?

Sans ça, l’agent reconstruit le contexte à chaque session. Et quand il reconstruit, il peut halluciner.

Structure simple recommandée​

Pas besoin de créer une usine à gaz. Pour la plupart des projets, ce format suffit :

• AGENTS.md : règles de travail pour l’agent IA ;
• PROJECT.md : résumé fonctionnel du projet ;
• RUNBOOK.md : commandes de lancement, test, build, rollback ;
• SECURITY.md : secrets, clés API, fichiers à ne jamais exposer ;
• TASKS.md : tâches en cours, décisions, bugs connus.

Tu peux mettre ces fichiers à la racine du dépôt ou dans un dossier docs/ai/. Personnellement, je préfère au moins AGENTS.md à la racine, car beaucoup d’outils IA le repèrent vite.

AGENTS.md : les règles de conduite​

C’est le fichier le plus important. Il doit être court et direct. L’objectif n’est pas de raconter l’histoire du projet, mais de dire à l’agent comment se comporter.

Exemples de règles utiles :

• ne pas modifier la base de données sans migration explicite ;
• ne jamais afficher les clés API, tokens, cookies ou fichiers .env ;
• préférer une petite correction vérifiable plutôt qu’un gros refactor ;
• lancer les tests avant d’annoncer que c’est terminé ;
• demander confirmation avant suppression ou action externe ;
• garder le style existant du code.

Un bon AGENTS.md évite beaucoup de dégâts, surtout avec les modes agent/autonomous où l’IA peut enchaîner plusieurs actions.

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

PROJECT.md : le résumé que l’IA oublie toujours​

Le PROJECT.md doit expliquer le projet comme si tu briefais un nouveau dev. Il ne doit pas être trop long.

Mets dedans :

• le but du projet ;
• les utilisateurs visés ;
• les principales fonctionnalités ;
• les technologies utilisées ;
• les dossiers importants ;
• les choix déjà décidés.

Exemple : “Ce bot Discord surveille les annonces d’un jeu, résume les patch notes et poste une alerte dans un salon. Il ne doit jamais envoyer de message public sans validation si le mode auto est désactivé.”

Cette phrase simple peut empêcher un agent de faire n’importe quoi avec un webhook.

RUNBOOK.md : lancer, tester, rollback​

Un agent IA ne doit pas deviner comment vérifier son travail. Si les commandes sont écrites clairement, il fera moins d’erreurs.

Le RUNBOOK.md doit contenir :

• installation propre ;
• lancement local ;
• tests rapides ;
• lint/typecheck/build ;
• où lire les logs ;
• comment revenir en arrière.

Même si ton projet n’a pas encore de vrais tests, écris au moins une vérification minimale : lancer le script, vérifier une route, ouvrir une page, exécuter un dry-run, ou inspecter le diff.

SECURITY.md : éviter la bêtise classique​

Les agents IA sont très bons pour aider, mais ils peuvent aussi ouvrir un fichier trop sensible “pour comprendre”. Le SECURITY.md sert à poser des limites.

À mettre dedans :

• où sont les secrets, sans écrire leur valeur ;
• quels fichiers ne doivent pas être lus ou affichés inutilement ;
• quelles actions externes demandent validation : email, post forum, Discord, API de paiement, suppression serveur ;
• comment utiliser des variables d’environnement ;
• comment faire un dry-run avant publication.

Important : ne transforme pas ce fichier en coffre-fort. Il décrit les règles, pas les secrets.

TASKS.md : la mémoire courte du projet​

Pour les agents, un TASKS.md bien tenu est souvent plus utile qu’un long historique de chat.

Tu peux y mettre :

• tâches en cours ;
• bugs connus ;
• décisions récentes ;
• idées à faire plus tard ;
• points à ne pas refaire.

Exemple : “Ne pas remplacer le système de tags XenForo : l’API attend tags[], pas une liste dans le corps du message.” Ce genre de note évite de répéter la même erreur toutes les semaines.

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

Bonnes pratiques​

1. Garder les fichiers courts

Si ton AGENTS.md fait 800 lignes, personne ne le maintiendra. L’IA le lira peut-être, mais les humains non. Mieux vaut 40 lignes utiles que 400 lignes floues.

2. Mettre à jour après les vraies décisions

Quand tu changes une règle importante, écris-la. Pas besoin de documenter chaque virgule, mais les décisions qui évitent des bugs doivent rester.

3. Séparer contexte et secrets

Le contexte doit aider l’IA. Les secrets doivent rester dans .env, un gestionnaire de secrets ou la config serveur. Ne colle jamais une clé “pour que l’agent comprenne”.

4. Ajouter une commande de vérification minimale

Un agent qui ne peut pas tester va souvent conclure trop vite. Donne-lui au moins une commande ou une procédure claire.

5. Préciser les actions externes

Publier sur un forum, envoyer un message Discord, appeler une API payante ou modifier une fiche produit : ce n’est pas la même chose qu’éditer un fichier local. Écris ce qui demande validation.

Exemple concret pour un bot Discord gaming​

Pour un bot Discord qui poste des news de jeux, le dossier contexte pourrait dire :

• le bot récupère des sources officielles ;
• il prépare un brouillon ;
• il ne poste pas automatiquement dans les salons publics sans mode validé ;
• les tokens Discord restent dans .env ;
• le test minimal est un dry-run qui affiche le message sans l’envoyer ;
• les titres doivent être clairs, pas clickbait.

Avec ça, Cursor, Claude ou Codex comprend tout de suite le cadre. Sans ça, il risque de coder une publication directe ou d’ajouter une dépendance inutile.

Mon avis​

Le dossier contexte, c’est le meilleur petit investissement pour travailler avec des agents IA. Ce n’est pas spectaculaire, mais ça change tout : moins d’hallucinations, moins de modifications dangereuses, moins de temps perdu à rebriefer l’outil.

Pour Cheat-Gam3, c’est particulièrement utile pour les projets qui touchent aux forums, bots Discord, scripts de veille, outils IA, marketplaces ou serveurs de jeu. Dès qu’il y a des comptes, des clés, des messages publics ou des données sensibles, l’agent doit avoir des rails.

Si vous utilisez déjà Cursor, Claude Code, Codex ou ChatGPT pour coder, commencez simple : créez un AGENTS.md aujourd’hui, ajoutez un RUNBOOK.md demain, puis améliorez au fil des vraies erreurs. Un bon contexte n’est pas un roman. C’est une barrière de sécurité et un accélérateur de travail.