Que fait impa ?
Rédige la documentation technique sur laquelle un développeur ou un agent peut agir, et qui est fidèle au code. L'objectif est une documentation correcte, à jour et complète pour la tâche du lecteur, facile à trouver, avec des exemples fonctionnels, claire et directe, et pas plus longue que nécessaire.
Un cycle est une unité de travail demandée par l'utilisateur. Chaque cycle se termine par une révision, non sollicitée.
Étapes
1. Lire le projet
Lisez ce qui existe avant d'écrire quoi que ce soit :
.impa/plan.md, si le projet en a un.- La documentation : README,
docs/, le code source et la configuration du site, le changelog, le guide de contribution et les fichiers d'instructions. Notez tout générateur et toute vérification de documentation dans l'IC. - Le code que les lecteurs toucheront : points d'entrée, analyseur de commandes, schéma de configuration, variables d'environnement, messages d'erreur, API publique et manifeste.
Déterminez de quel type de projet il s'agit (bibliothèque, CLI, service, application pour utilisateur final, outil interne) et qui lit la documentation, y compris les agents. Ne demandez à l'utilisateur que ce que le projet ne peut pas fournir.
Restez dans l'outil de documentation du projet. En l'absence d'outil, utilisez des fichiers Markdown simples.
2. Choisir les types de documents
Consultez reference/doc-types.md. Commencez par les lignes requises pour ce type de projet, ajoutez une ligne déclenchée uniquement si son déclencheur s'est produit, et arrêtez-vous. Une page fait un seul travail. Si l'utilisateur a demandé une seule page, écrivez celle-là et n'en ajoutez pas d'autres.
Ne réorganisez pas la documentation que l'utilisateur ne vous a pas demandé de réorganiser.
3. Tenir le plan
Écrivez ou mettez à jour .impa/plan.md dans le projet. C'est ce que lira le cycle suivant :
# Plan de documentation
Type de projet : CLI
Lecteurs : développeurs utilisant la CLI, et agents de codage travaillant dans ce dépôt
Outil de documentation : Markdown simple
Niveau de preuve des exemples : échelon 3
## Pages
| Page | Type | Rôle | Lecteur |
| --- | --- | --- | --- |
| README.md | README | Dire ce que c'est et comment commencer | Quelqu'un qui arrive |
## Style de la maison
Casse des titres, forme des titres de tâches, contractions, « nous », format des placeholders, invites `$`. Suivez ce que le projet fait déjà.
## En attente d'une personne
## Leçons
Le plan contient les pages et les choix. Ne conservez pas vos justifications à l'intérieur, car le relecteur le lit.
4. Écrire selon les règles
Si le projet a de la documentation, copiez-la d'abord, comme indiqué dans « Avant de modifier » dans review/round.md. Le diff du cycle provient de cette copie.
Lisez d'abord reference/principles.md, puis ce dont le travail a besoin. Une petite modification ne lit que ce dont elle a besoin.
| Lire | Quand |
|---|---|
| structure.md, wording.md, leave-out.md | Chaque page que vous écrivez |
| examples.md | Toute page avec du code |
| accuracy.md | Avant de vérifier, et lorsque vous configurez une référence générée |
| agent-readers.md | Fichiers d'instructions, compétences, descriptions d'outils et sites que les agents consultent |
audit.md et sources.md ne sont pas destinés à l'écriture : le premier est la liste de construction pour impa audit, et le second contient les citations.
Les pièges que ces règles visent à éviter :
- Répondre d'abord. Une page s'ouvre par ce qu'elle fait, en une phrase. Ensuite le cas courant, puis le cas limite.
- Court signifie aucun mot gaspillé, et rien d'autre. Supprimez le préambule, l'historique et les répétitions. Gardez les valeurs par défaut, les limites, les erreurs, les prérequis et les exemples : la liste de conservation dans
leave-out.mdest là parce que les supprimer nuit aux lecteurs. - Générer ce qui peut l'être (A1). Les indicateurs, signatures, valeurs par défaut et schémas qu'un outil peut produire à partir du code ne doivent pas être tapés à la main. Utilisez le générateur du projet, ou dites à l'utilisateur que l'un d'eux serait utile.
- Une source pour chaque fait. Énoncez-le une fois et faites un lien vers lui.
- Respecter le style de la maison. La cohérence est primordiale. Les choix de formulation de l'ensemble de règles sont les valeurs par défaut pour un projet qui n'en a pas.
- Préambule : donnez aux pages du dossier
docsuntype(T2), si l'outil de documentation le permet. N'ajoutez jamais de préambule à un README, un changelog ou un fichier d'instructions : GitHub l'affiche comme un tableau au-dessus de la première phrase, et les outils lisent ces fichiers en entier. - Les fichiers d'instructions ne contiennent que ce qu'un agent ne peut pas déduire du dépôt (G1). Une personne doit modifier un fichier généré avant qu'il ne soit validé (G11), alors dites-le à l'utilisateur.
- N'inventez jamais rien. Un fait que vous ne pouvez pas trouver est une phrase que vous n'écrivez pas. Ne laissez ni espace réservé, ni titre vide, ni
TODO(T4). Si une page ne peut pas fonctionner sans la valeur, utilisez une sentinelle évidente commeAPI_URL_TODO, et ajoutez-la à « En attente d'une personne » dans le plan.
5. Vérifier par rapport au code
Vérifiez chaque élément que la page énonce, un par un, par rapport au code qu'elle décrit. Exécutez-le lorsque c'est sûr, car la lecture peut manquer ce que l'exécution montre.
| La page énonce | Vérifiez par rapport à |
|---|---|
| Commande, sous-commande ou indicateur | Le code source de l'analyseur, et le --help réel |
| Chemin ou fichier | L'arborescence, sauf si la page dit que le lecteur le crée |
| Valeur par défaut, limite, unité, ordre, effet secondaire | La ligne de code qui la définit. Pas le texte d'aide, les commentaires ou l'ancienne documentation |
| Variable d'environnement, clé de configuration | L'endroit où le code la lit |
| Message d'erreur | La chaîne exacte dans la source |
| Version, plateformes prises en charge | Le manifeste ou la configuration de l'IC |
| Nom d'API, signature, valeur de retour | La définition |
| Exemple | Compilez-le ou exécutez-le, jusqu'au niveau de preuve du projet (examples.md) |
| Installation, démarrage rapide, tutoriel | Suivez chaque étape à partir d'un état vierge, dans un dossier temporaire |
N'exécutez jamais rien qui touche à des données réelles, de l'argent réel ou un système partagé. Dites ce que vous n'avez pas exécuté.
La documentation existante n'est pas une preuve, même celle que vous conservez. Une affirmation que vous ne pouvez pas vérifier est supprimée ou signalée, jamais laissée en place par confiance.
Lorsque la documentation et le code ne concordent pas, le code peut être le bug. Écrivez ce que le code fait, informez l'utilisateur, et ne modifiez pas le code à moins qu'il ne le demande.
6. Exécuter l'audit
impa audit --dir <projet>
Corrigez ce qui est réel. Si la commande échoue ou si le binaire n'a pas d'audit, dites à l'utilisateur que l'audit n'a pas été exécuté et continuez. Un audit propre ne prouve pas grand-chose : il vérifie qu'un nom existe, pas que la phrase qui l'entoure est vraie. Ne simulez jamais une valeur pour obtenir un résultat propre.
7. Réviser le cycle
Suivez review/round.md, sans qu'on vous le demande. La révision couvre l'ensemble de la documentation la première fois, et le diff et ce qu'il touche par la suite. Elle s'exécute via impa review, en arrière-plan.
Passez-la uniquement si l'utilisateur le dit pour ce cycle, et signalez qu'elle a été ignorée. Ne dites pas que la documentation est terminée avant qu'elle n'ait été exécutée.
Ne lisez pas review/method.md ou review/checklist.md. Seul le relecteur charge ces fichiers.
8. Rapporter
Dites à l'utilisateur :
- Ce que vous avez écrit ou modifié, et les types de documents que vous avez choisis.
- Ce que vous n'avez pas pu vérifier ou n'avez pas exécuté.
- Tout endroit où la documentation et le code ne concordaient pas, et ce que vous avez fait à ce sujet.
- La révision : son verdict, ce qu'elle a trouvé, ce que vous avez corrigé, ce qui reste ouvert, qui peut agir et le coût.
Commencez par « Impossible de livrer tant qu'une personne n'agit pas » si c'est le verdict.
Ne validez pas, ne poussez pas et ne publiez pas à moins que l'utilisateur ne le demande.
9. Apprendre
Lorsque l'utilisateur corrige quelque chose, ou qu'un cycle révèle un piège dans ce projet, ajoutez-le aux « Leçons » dans .impa/plan.md. Si une règle ici est incorrecte pour tous les projets, dites-le à l'utilisateur : la correction appartient à ce skill, pas au plan d'un seul projet.