Wiki
Un wiki de projet est un dossier de pages Markdown qui explique le projet : ce que font ses parties, pourquoi il fonctionne ainsi, et où se trouvent les preuves. Les humains le lisent. Les agents le maintiennent. Chaque nouvelle source, question ou modification de code devrait le laisser un peu plus complet et précis.
Cela suit le modèle « LLM wiki » : conserver les sources brutes, écrire des pages qui les résument et les relient, et tenir un index et un journal pour que l'ensemble reste navigable.
Les règles du dépôt priment d'abord
Si le dépôt a déjà un wiki, lisez son fichier de schéma ou d'instructions (souvent wiki/README.md, wiki/AGENTS.md ou wiki/schema.md) avant de modifier quoi que ce soit. Sa mise en page, ses métadonnées, son style de liens et ses commandes l'emportent sur les valeurs par défaut ici. Utilisez les scripts de wiki du dépôt lorsqu'ils existent, et ne modifiez pas manuellement les fichiers qu'ils génèrent.
Les parties
| Partie | Ce que c'est | Qui l'édite |
|---|---|---|
| Sources | Copies du matériel brut : issues, PRs, articles, notes, transcriptions | Ajoutées une fois, puis jamais modifiées |
| Pages | Explications écrites de sujets, citant les sources et le code | Mises à jour quand les faits changent |
| Schéma | Un fichier contenant les règles du wiki : mise en page, métadonnées, conventions | Modifié délibérément |
| Index | Une liste de chaque page avec un résumé d'une ligne | Régénéré, ou maintenu complet |
| Journal | Une liste datée, en append-only, des modifications apportées au wiki | Une entrée par opération |
Une disposition par défaut pour un nouveau wiki :
wiki/
├── README.md # ce qu'est le wiki et comment l'utiliser
├── schema.md # les règles (l'endroit unique où elles sont écrites)
├── index.md # chaque page, une ligne chacune
├── log.md # ce qui a changé, le plus récent en dernier
├── pages/ # pages thématiques
└── sources/ # matériel brut, inchangé après son ajout
Un petit projet peut s'arrêter là. N'ajoutez des sous-dossiers que lorsqu'il y a suffisamment de pages pour que les gens ne trouvent plus les choses.
Qui a raison quand les sources divergent
Écrivez, dans le schéma, quelle source prévaut pour chaque type d'affirmation. Pour la plupart des projets logiciels :
- Comment se comporte le code aujourd'hui : le code et ses tests.
- Ce qui a été décidé, et pourquoi : le registre des décisions, l'issue ou la PR où cela a été décidé.
- Ce qui est prévu ou en cours : le suivi des issues ou la feuille de route.
Lorsqu'une page et son autorité divergent, corrigez la page et conservez une brève note de ce qui a changé si l'ancienne croyance mérite d'être rappelée. Ne modifiez jamais une source pour la faire correspondre.
Pages
-
Un sujet par page, avec un titre clair. Mettez à jour la page existante plutôt que d'en ajouter une quasi-identique.
-
Citez ce que vous affirmez. Liez vers la source ou nommez le fichier. Un lecteur doit pouvoir vérifier toute affirmation importante.
-
Utilisez des liens Markdown relatifs (
[Analyseur](analyseur.md)) sauf si le wiki utilise déjà un autre style. -
Gardez le frontmatter petit. Un minimum utile :
--- title: Analyseur summary: Comment les fichiers d'entrée sont lus et validés. sources: [sources/issue-42.md] code: [src/parser.ts] updated: 2026-01-31 ---N'ajoutez des champs que lorsqu'une personne ou un script les utilisera.
-
Chaque page est accessible depuis l'index et depuis au moins une page connexe.
Opérations
Créer un nouveau wiki
- Regardez quels documents existent déjà et qui les lit. Ne dupliquez pas un site de documentation fonctionnel.
- Proposez la disposition et le schéma à l'utilisateur, et mettez-vous d'accord avant d'écrire les pages.
- Créez
README.md,schema.md,index.mdetlog.md. - Écrivez quelques pages pour les parties les plus importantes du projet, puis arrêtez-vous et vérifiez avec l'utilisateur avant de remplir le reste.
- Pointez les instructions de l'agent du dépôt (
AGENTS.md,CLAUDE.md) vers le schéma, plutôt que de copier les règles dedans.
Ajouter une source
- Enregistrez le matériel brut sous
sources/, avec sa provenance et sa date. - Lisez-le en entier.
- Trouvez chaque page existante qu'il affecte, et mettez-les à jour. Créez une nouvelle page uniquement pour un sujet qui n'en a aucune.
- Notez tout ce qui contredit les pages actuelles et résolvez-le en utilisant les règles d'autorité.
- Mettez à jour l'index et ajoutez une entrée dans le journal.
Enregistrer une source sans mettre à jour les pages n'est pas terminé. Les pages sont ce que les gens lisent.
Répondre à une question
- Commencez par l'index, puis cherchez dans les titres et le texte des pages.
- Lisez les pages pertinentes et vérifiez les affirmations importantes par rapport à leurs sources ou au code.
- Répondez avec des liens vers les pages et les preuves que vous avez utilisées. Dites où elles divergent ou où le wiki n'a pas de réponse.
- Si la réponse est nouvelle et susceptible d'être redemandée, proposez de l'ajouter au wiki.
Mettre à jour après une modification de code
Quand une modification change le fonctionnement de quelque chose :
- Cherchez dans le wiki les fichiers, fonctions et termes que le changement a touchés.
- Mettez à jour chaque page affectée dans la même PR que la modification du code.
- Mettez à jour l'index si les titres ou les résumés ont changé, et ajoutez une entrée dans le journal.
Vérifier la santé du wiki
Recherchez :
- les liens brisés et les chemins de code qui n'existent plus ;
- les pages sans liens entrants ;
- les pages en double sur le même sujet ;
- les sources qu'aucune page ne cite ;
- les pages qui se contredisent entre elles ou avec le code ;
- un index qui manque des pages ou liste des pages supprimées.
Corrigez les problèmes mécaniques, comme les liens et l'index, directement. Signalez les décisions qui nécessitent un jugement, comme fusionner des pages ou décider quelle affirmation est correcte, à l'utilisateur.
Entrées du journal
Ajoutez une entrée par opération, à la fin de log.md :
## 2026-01-31 14:05 UTC: ingestion | Issue 42, lignes vides en entrée
Ajout de l'issue comme source et mise à jour de la section de validation de la page analyseur.
Incluez toujours l'heure et le fuseau horaire pour que les entrées du même jour restent dans l'ordre.
À ne pas faire
- Modifier une source après l'avoir ajoutée.
- Restructurer ou renommer de grandes parties du wiki sans demander.
- Supprimer des pages parce qu'elles sont obsolètes. Marquez-les comme obsolètes et liez vers ce qui les a remplacées.
- Écrire les mêmes règles à plusieurs endroits. Le schéma est la copie unique.
- Traiter le wiki comme plus autoritaire que le code qu'il décrit.
- Écrire dans un système externe (Confluence, Notion, un suivi de tickets) sans l'approbation de l'utilisateur.