Notion · Pratique et outillage
README et documentation
Le fichier d’accueil d’un projet : à quoi il sert, où sont les choses, où on en est. C’est la première chose qu’un collaborateur, ou un agent, lit en arrivant.
Comment ça marche
Un README est un fichier texte, en Markdown, placé à la racine d’un projet. C’est la page d’accueil : la première chose qu’on voit en ouvrant le dossier, et sur GitHub, la première chose affichée. Il dit à quoi sert le projet, comment il est organisé, comment s’en servir, et où on en est. Rien de technique en soi ; de l’organisation écrite.
Avec les agents, le README prend une importance nouvelle. Un agent lancé dans un projet ne sait rien de ce projet. S’il trouve un README clair, il comprend en quelques secondes où chercher et où écrire. S’il n’en trouve pas, il explore au hasard, devine, et se trompe. La plupart des fichiers de consignes commencent par « lis le README avant de commencer ». Il devient aussi la mémoire du projet : ce qui a été décidé, ce qui reste à faire, survit aux sessions et aux personnes.
Un exemple concret
# Relances clients
À quoi ça sert. Produire chaque lundi les relances des factures impayées, prêtes à relire. Lancé par la commande /relances depuis ce dossier.
Où est quoi. exports/ : les exports comptables du lundi, un fichier par semaine, nommés AAAA-MM-JJ.csv. gabarits/ : les trois modèles de relance (premier rappel, second, mise en demeure). sorties/ : les relances produites, un dossier par semaine. scripts/ : le programme qui fait le travail. tests/ : ses tests.
Comment ça marche. Le script lit le dernier export, repère les factures en retard, choisit le gabarit selon l’ancienneté, et écrit les relances dans sorties/. Rien n’est envoyé.
Où on en est. En production depuis mars. À faire : gérer les clients avec échéancier (voir notes/echeanciers.md). Bloqué : l’export ne contient pas les avoirs, demandé au comptable le 14 octobre.
Décisions. Pas de relance automatique des clients publics (décidé en avril, voir notes/decisions.md).
Un agent qui lit ce fichier sait où sont les exports, ce qu’il ne doit pas faire, et ce qui est en attente. Un nouveau collègue aussi.
Ce que ça change pour une équipe
- Les agents travaillent au bon endroit. Un README qui dit où sont les choses évite les fichiers créés n’importe où et les mauvais fichiers modifiés.
- Le projet survit aux personnes. Celui qui l’a construit part ; le README reste, et le suivant reprend.
- L’état du projet est connu. « Où on en est » remplace les réunions de synchronisation et les questions répétées.
- La documentation devient une habitude légère. Une page, mise à jour en fin de session, plutôt qu’un manuel jamais écrit.
Les limites et les erreurs fréquentes
- Le README périmé. Il décrit une organisation d’il y a six mois. Tout le monde se fie à lui et se trompe. Mettre à jour à chaque session, ou faire mettre à jour.
- Le README manuel. Trente pages que personne ne lit. Une page, et des liens vers les détails.
- Pas de README du tout. Chaque projet, même petit, en mérite un. Un agent peut l’écrire à partir du dossier en deux minutes ; on relit.
- Oublier « où on en est ». C’est la section la plus utile et la plus souvent absente. Fait, en cours, bloqué : trois lignes.
Pour aller plus loin
Un README tenu à jour sert d’index au projet et de point d’entrée pour les agents de code, qui le lisent avant d’agir. La documentation vivante (décisions, conventions) se place à côté, en Markdown, versionnée avec le code.
Où ça se situe chez Opora
Programme 04 · Construire des agentsIngénierie agentique pour les équipes techniques
Tenir un README qui sert d’index au projet et de point d’entrée pour les agents, c’est une habitude que nous installons dès le premier atelier du programme Construire des agents.
Questions fréquentes
Que doit contenir un README ?
Trois choses : à quoi sert le projet, où sont les choses (les dossiers et ce qu’ils contiennent), et où on en est (ce qui est fait, ce qui est en cours, ce qui bloque). Une page. Les détails vont dans d’autres fichiers, que le README indique.
Quelle différence avec le fichier de consignes de l’agent ?
Le README décrit le projet ; le fichier de consignes dit à l’agent comment travailler dessus. Le README est lu par les humains et les agents ; le fichier de consignes est surtout pour l’agent. Souvent, le fichier de consignes commence par « lis le README ».
Comment le garder à jour ?
En le traitant comme une partie du travail, pas comme une tâche à part : à la fin d’une session, on met à jour la section « où on en est ». Un agent peut le faire sur consigne. Un README périmé est pire qu’absent, parce qu’on le croit.