Documentation fondée sur les preuves
Une affirmation n'est une documentation que si elle porte les moyens de la vérifier. Cette compétence est la norme et la carte : dix canons, et où chacun est défini, appliqué et ensemencé.
C'est un navigateur, pas une copie secondaire. Chaque loi ci-dessous a exactement un domicile — c'est le canon 3, et un navigateur qui reformulerait la doctrine enfreindrait la règle qu'il indexe. L'énoncé complet de chaque canon, sa justification et sa mise en œuvre se trouvent dans documentation.md → Les canons.
Les dix canons
- Une affirmation porte son adresse —
fichier:ligne, une commande et sa sortie, un nom de test ; une leçon nomme son commit. - Les nombres sont calculés, jamais reformulés.
- Chaque fait a exactement un domicile — les autres créent un lien, jamais une redite.
- Une référence résout à partir de l'endroit où le document est lu — pas de l'endroit où il vit.
- Un vert que personne n'a vu devenir rouge n'est pas une preuve.
- Un contrôle prouve sa portée et rien au-delà.
- Le silence n'est pas un succès — demandez ce qu'un mécanisme imprime quand il n'a pas regardé.
- Une estimation n'est jamais annoncée comme une mesure — une règle énonce sa condition de preuve.
- Ce qui n'a pas été vérifié est imprimé à côté de ce qui l'a été.
- Le document est livré dans le changement qui l'a rendu vrai — et une correction est ajoutée, jamais écrasée.
Ils sont épistémiques : ce qui fait d'une affirmation une documentation. La couche opérationnelle — que faire sur un déclencheur donné, avec un contrôle et un critère de sortie — se trouve dans learned.md. Quand les deux semblent dire la même chose, le canon est le pourquoi et la règle est le comment.
Où aller ensuite
| Vous allez… | Lisez | Parce que |
|---|---|---|
| configurer la documentation d'un projet à partir de zéro | documentation.md → L'inventaire | quatre questions à répondre avant la première ligne de travail |
| enregistrer une décision pour qu'elle survive à son auteur | Registres et identifiants + templates/decisions.md | identifiants en mode append-only, marqueurs de bordure, un seul domicile par décision |
| modifier quelque chose sans orpheliner la documentation | La boucle de documentation + La matrice de propagation | quels documents un changement implique, en commençant par la méta-ligne |
| décider où un fait appartient | Source unique de vérité | deux domiciles se contredisent le jour où l'un d'eux est mis à jour |
| construire un contrôle qui ne peut pas mentir | gates.md | trois axes, l'échelle de mise en application, l'armement progressif, le sondage |
| faire confiance à un mécanisme qui signale un succès | gates.md → Faux succès | l'échec qui supprime la raison de vérifier |
| câbler un contrôle dans les outils propres de l'agent | hooks.md | le contrat du hook, et pourquoi un garde qui a planté autorise l'action |
| auditer la documentation qu'un projet possède déjà | setup.md | sept passes, les moins chères d'abord, le résultat est un plan de correction |
| reporter une leçon à la prochaine exécution | retrospective.md | tamponnez d'abord (le déclencheur à froid le lit), puis éliminez jusqu'à un maximum de dix ; chaque leçon nomme son commit |
| ensemencer un contrôle dans un projet hôte | templates/docgate.sh | il s'ensemence en vert : dormant là où il n'y a pas encore d'entrée |
| affirmer qu'un agent se comporte correctement | tdd.md → Quand la chose testée est un agent — nommé plutôt que lié, car les liens hors répertoire de ce navigateur se brisent quand un empaqueteur livre cette compétence seule | l'adresse est un identifiant de trace et l'assertion qui a été exécutée (canon 1) ; un juge que personne n'a vu contester est un vert que personne n'a vu devenir rouge (canon 5) |
| mener un changement complet jusqu'à la recette | tâche-pipeline | cette compétence est la norme ; celle-là décrit comment un changement atteint le dépôt |
Quand cela s'applique
La frontière est : « cela sera lu comme vrai. » Un registre de décision, un README, un rapport de recette, un runbook, un journal des modifications pour les utilisateurs, un constat d'audit, une affirmation que quelque chose a été vérifié.
Pas via cette compétence : un brouillon, une réflexion à voix haute, une réponse dans un chat, un message de commit, un commentaire de code. Exiger un fichier:ligne pour « laissez-moi vérifier cela » est le moyen le plus rapide d'apprendre à un agent à contourner la règle là où elle protège réellement quelque chose.
Phrase de refus — « без доков » / « sur parole ». Cela fonctionne sur une tâche qui passerait autrement par ici : faites-la directement et dites à voix haute que l'affirmation n'est pas étayée, plutôt que de présenter une estimation comme une mesure (canon 8).
Le test unique
Avant de livrer un document, lisez-le pour trouver la phrase qui vous embarrasserait si quelqu'un demandait « comment le sais-tu ? » — et soit donnez à cette phrase son adresse, soit supprimez-la. Tout ce qui précède est cette question, rendue mécanique.