Journal de session
Écrit un enregistrement durable d'une session de travail. Ces journaux sont considérés comme la vérité de référence par quiconque les lit ensuite — y compris vous, dans six semaines, sans aucun de ce contexte. La précision compte plus que le polissage.
Quand exécuter ceci
- Une vague de construction, correction, audit ou recherche vient de se terminer
- Une session se termine et il y a un état dont la suivante aurait besoin
- Quelque chose a été diagnostiqué et le mécanisme mérite d'être conservé
Ne l'exécutez pas pour un travail trivial. Un correctif d'une ligne n'a pas besoin d'un journal.
Où cela va
Là où le projet conserve ses enregistrements de session — un répertoire docs/sessions/, un coffre de notes, un wiki. Demandez une fois si ce n'est pas évident, puis restez cohérent.
Un nom de fichier portant la date et une brève description se trie et se scanne bien : YYYY-MM-DD Brève Description.md.
Étapes
1. Rassembler les faits avant d'écrire
N'écrivez pas de mémoire de la conversation uniquement. Collectez :
- Numéros de PR, SHA de commits, horodatages de migration, IDs de déploiement
- Ce qui a été effectivement vérifié, et par quelle commande
- Ce qui a échoué, et ce qui est toujours ouvert
- Tout ce que seul un humain peut faire
Si un fait ne peut pas être confirmé, marquez-le comme non confirmé plutôt que de le supprimer ou de l'affirmer.
2. Rédiger le corps
# AAAA-MM-JJ — <ce qui a été diagnostiqué ou livré>
<Une ligne nommant comment le travail a été mené : qui a planifié, qui a construit, qui a révisé.>
## Ce qui s'est passé
- Mécanisme d'abord. Pourquoi cela s'est produit, pas seulement quoi.
- Preuves concrètes : numéros de PR, SHA, horodatages, nombres de lignes, lignes de journal.
- Distinguez clairement ce qui est prouvé de ce qui est inféré.
## Correctif
1. Étapes numérotées. Chacune indique ce qui a été vérifié et comment.
## Règles de NE-PAS-FAIRE permanentes
<Seulement si la session a produit des interdictions. Ancrez chacune dans l'incident qui l'a causée.>
## Éléments restants — nécessite un humain
- [ ] Choses que seulement eux peuvent faire
Liens : <documents connexes>
Si le système de notes utilise le frontmatter, incluez un champ outcome : une phrase complète indiquant ce qui est maintenant vrai qui ne l'était pas auparavant. C'est la ligne la plus lue du fichier. Faites-en une déclaration réelle, pas une étiquette.
3. Les deux sections que tout le monde oublie
## Éléments restants et le pied de page des liens sont obligatoires. Ce sont les deux sections qui portent la valeur en avant et les deux plus souvent omises — dans un coffre, mesuré sur 230 journaux existants, elles n'apparaissaient que dans ~21 % et ~28 % d'entre eux.
Écrivez les deux, à chaque fois. Si rien n'est vraiment retenu pour un humain, écrivez Aucun — rien n'est retenu. plutôt que de supprimer le titre.
4. Marquer chaque affirmation
Étiquetez chacune VÉRIFIÉ (comment) ou SUPPOSÉ (pourquoi non vérifié) en ligne. Ne les brouillez pas.
« Vérifié » doit signifier qu'un humain ou une commande l'a effectivement confirmé. Une affirmation concernant la production nécessite une requête contre la production — pas un test réussi, pas une PR fusionnée, pas un déploiement vert.
5. Résoudre chaque lien avant d'enregistrer
Vérifiez chaque cible de lien par rapport à un fichier réel avant de l'écrire. Un système de notes accumule rapidement des références cassées, et un journal plein de liens morts est un journal que personne ne croit.
6. Mettre à jour l'état du projet
Si le travail a modifié le statut d'un projet, ajoutez une section d'état datée au document principal de ce projet — le plus récent en premier, ajoutez en tête, ne réécrivez jamais l'historique.
Si le travail a fait progresser un programme avec un document de transmission, mettez-le à jour sur place afin que la session suivante reprenne correctement.
7. Réinjecter les leçons
Si l'utilisateur a corrigé quelque chose pendant la session, écrivez la leçon quelque part de durable — un fichier de règles, un magasin de mémoire, cette compétence elle-même. C'est ainsi que les corrections cessent de se répéter.
Style maison
- Spécifique et falsifiable. Les résumés vagues sont pires que rien ici.
- Ne jamais revendiquer un statut sans dire comment il a été vérifié.
- Menez par les mauvaises nouvelles. Ne les enterrez pas.
- Écrivez pour un lecteur qui n'a aucun de votre contexte.
À ne pas faire
- Ne pas écraser un journal existant. Lisez d'abord, puis modifiez.
- Ne pas écrire dans des répertoires générés automatiquement.
- Ne pas créer de fichiers temporaires ou de sorties de construction à côté des notes.