juspay/kolu

Rédiger un article de blog kolu

Un article de blog kolu est un essai d'ingénierie à la première personne ancré dans ce qui s'est réellement passé lors de la construction de quelque chose — l'impasse, la décision déterminante, le bug qui a enseigné la leçon. Sa source de vérité est constituée des journaux de session Claude Code qui ont produit le travail, et non d'un contenu marketing inventé.

Montrez l'histoire, ne vous contentez pas de la raconter. Un bon article s'appuie davantage sur des figures que sur du texte : un graphique de trajectoire, des cartes avant/après, une chronologie, un diagramme de flux, une barre de comparaison, une capture d'écran réelle — la visualisation porte une plus grande partie de l'argumentation que le texte. Chaque figure est ancrée dans des données réelles (horodatages de statut, sortie ps, durées mesurées) ; un graphique est un argument, jamais une décoration. Cela s'applique à chaque article, pas seulement aux plus visuels.

Étapes

1. Localisez les sessions du travail. Trouvez les journaux de session Claude Code derrière la fonctionnalité (ils se trouvent sous ~/.claude/projects/, un répertoire par répertoire de travail). Cartographiez-les de manière déterministe en traçant les PR → branches → journaux, et non par des correspondances de mots-clés.

2. Extrayez-en l'histoire. Lisez le récit humain/assistant dans les journaux et extrayez le pourquoi des décisions, les leçons durement acquises et les impasses, les mécanismes concrets et les citations textuelles vivantes. Lorsque l'effort couvre plus de quelques sessions, répartissez la tâche avec un workflow ultracode — un agent par transcription qui renvoie des notes structurées — puis synthétisez les notes en un seul résumé, rédigez à partir de celui-ci et effectuez une passe de relecture contradictoire. Le résumé est l'épine dorsale vérifiée ; n'inventez jamais de chiffres, de dates, de citations ou de PR.

3. Rédigez dans la voix de l'auteur. Utilisez la compétence pg (voix de Paul Graham) sauf indication contraire, et établissez le style maison en ligne dès le début. Adaptez le registre aux articles existants ; un nouvel article fait souvent office de suite à un autre. Donnez-lui un titre non cryptique. Le title du frontmatter est un titre simple et explicite qui indique ce qui s'est passé et porte le bénéfice — « Accélérer 14x la pipeline CI e2e macOS de Kolu », et non un slug ou un teaser malin que le lecteur ne peut pas décoder avant d'avoir fini. Laissez la description dévoiler l'accroche concrète (la fuite de 64 Go, la faute de frappe d'un caractère). Il s'agit d'un changement délibéré par rapport aux anciens articles aux titres évocateurs, vers des titres qui indiquent d'emblée au lecteur ce qu'il va apprendre — appliquez-le à chaque nouvel article. Lorsqu'un titre reste délibérément évocateur (« L'espace-temps du code »), donnez-lui un subtitle optionnel dans le frontmatter — une ligne simple qui décrypte la métaphore en ce que le lecteur apprendra ; elle s'affiche comme un sous-titre sous le titre.

4. Intégrez-le dans le site. Les articles se trouvent dans website/src/content/blog/ sous un slug court et stable (le nom du fichier est l'URL). Utilisez les composants du site pour les appels, les références aux PR/Issues GitHub et la table des matières ; citez les vraies PR derrière chaque affirmation et donnez à l'article un plan à deux niveaux de titres pour que la table des matières s'imbrique — rédigez les titres comme de simples indicateurs du point de chaque section, et non comme des teasers, de sorte que la liste du contenu se lise comme un argument en miniature. Mettez en lien chaque technologie, outil, bibliothèque, format et produit dès sa première mention — [Playwright](https://playwright.dev/), [ffmpeg](https://ffmpeg.org/), une méthode CDP vers sa propre page de documentation — comme le font les articles existants ; une technologie nommée sans lien est une erreur. Lorsque le contenu est une séquence d'étapes ou une courte énumération (par exemple, deux méthodes d'API qui échouent chacune, deux pièges), utilisez une liste ou un tableau Markdown au lieu d'un paragraphe dense — gardez l'argument en prose, mais cessez de cacher le contenu énumérable dans des paragraphes (un assouplissement délibéré et spécifique à l'article de la règle de la compétence pg « ne remplacez pas l'argument par des puces »). Lorsque vous citez quelque chose que l'auteur a littéralement tapé dans la zone de commande CLI d'un agent (Claude Code, Codex, etc.) comme point de bascule, rendez-le avec le composant Prompt (website/src/components/Prompt.astro) — <Prompt>…</Prompt> — et non un simple bloc de citation, afin qu'il se lise comme un humain qui tape dans le champ de saisie de l'agent ; voir auto-demo.mdx pour l'utilisation de référence. Équilibrez le texte avec des captures d'écran et du code — hébergez les images dans le site, ne faites pas de hotlinking.

   Figures : SVG inline rédigé à la main, adapté au thème. Dessinez les graphiques directement sous forme de <svg> inline dans le MDX (pas de bibliothèque de graphiques) — voir macos-e2e-lane.mdx pour cinq figures de référence. Coloriez chaque trait et remplissage avec les propriétés personnalisées CSS --color-* du site (--color-ink, --color-ink-dim, --color-ink-muted, --color-rule-strong, --color-amber, --color-live-alert, --color-live-lime, --color-void, … ; la palette se trouve dans website/src/styles/global.css) afin qu'une figure suive automatiquement le mode clair/sombre — ne codez jamais une valeur hexadécimale en dur. Donnez à chaque <svg> un role="img" et un aria-label décrivant les données qu'il affiche.

   Piège MDX/SVG (durement gagné sur l'article sur la pipeline macOS). Le MDX d'Astro transmet littéralement les attributs de présentation SVG en camelCase (textAnchor, fontSize), et SVG les ignore silencieusement — chaque libellé s'affiche à la taille par défaut de 16 pixels alignée à gauche. Utilisez l'orthographe SVG réelle en kebab-case de chaque attribut : text-anchor, font-size, font-weight, font-family, stroke-width, fill-opacity. Les attributs SVG réellement en camelCase comme viewBox restent tels quels. Un simple coup d'œil ne suffit pas à le détecter — repérez-le en mesurant getBBox() dans un vrai navigateur sur le site construit.

5. Vérifiez et publiez. Construisez le site et confirmez qu'il s'affiche, puis vérifiez chaque figure dans les deux thèmes clair et sombre sur la sortie construite avec le MCP chrome-devtools — confirmez que les libellés sont réellement placés (getBBox()), et pas seulement présents dans le DOM — avant d'ouvrir la PR. Exécutez uniquement la pipeline CI qu'un changement de documentation peut toucher (la construction du site plus le formatage et le lint — voir la compétence ci).