juspay/kolu

Einen Kolu-Blogbeitrag schreiben

Ein Kolu-Blogbeitrag ist ein technischer Essay aus der Ich-Perspektive, der auf dem basiert, was tatsächlich passiert ist, als etwas gebaut wurde – die Sackgasse, die tragende Entscheidung, der Bug, der die Lektion lehrte. Seine Wahrheitsquelle sind die Claude Code Sitzungsprotokolle, die die Arbeit hervorgebracht haben, nicht erfundene Marketingtexte.

Zeige die Geschichte, erzähle sie nicht nur. Ein guter Beitrag stützt sich auf Abbildungen mehr als auf Prosa: ein Verlaufsdiagramm, Vorher/Nachher-Karten, eine Zeitleiste, ein Flussdiagramm, ein Vergleichsbalken, ein echter Screenshot – Visualisierung, die mehr vom Argument trägt als Text. Jede Abbildung basiert auf echten Daten (Status-Zeitstempel, ps-Ausgabe, gemessene Dauern); ein Diagramm ist ein Argument, niemals Dekoration. Dies gilt für jeden Beitrag, nicht nur für die offensichtlich visuellen.

Schritte

1. Finde die Sitzungen der Arbeit. Suche die Claude Code Sitzungsprotokolle hinter dem Feature (sie liegen unter ~/.claude/projects/, ein Verzeichnis pro Arbeitsverzeichnis). Ordne sie deterministisch zu, indem du PRs → Branches → Logs zurückverfolgst, nicht durch Stichworttreffer.

2. Grabe nach der Geschichte. Lies die Mensch/Assistent-Erzählung aus den Protokollen und extrahiere das Warum hinter Entscheidungen, die mühsam erlernten Lektionen und Sackgassen, die konkreten Mechanismen und lebendige wörtliche Zitate. Wenn der Aufwand mehr als eine Handvoll Sitzungen umfasst, verteile die Arbeit mit einem Ultracode-Workflow – ein Agent pro Transkript, der strukturierte Notizen zurückgibt – fasse dann die Notizen zu einer einzigen Zusammenfassung zusammen, schreibe daraus und führe einen adversarischen Editorendurchlauf durch. Die Zusammenfassung ist das faktengeprüfte Rückgrat; erfinde niemals Zahlen, Daten, Zitate oder PRs.

3. Schreibe es in der Stimme des Autors. Verwende das pg-Skill (Paul Graham Stimme), sofern nicht anders angegeben, und lege den Inline-Stil des Hauses vorab fest. Passe das Register der bestehenden Beiträge an; ein neuer Beitrag fungiert oft als Fortsetzung zu einem bestehenden. Gib ihm einen nicht kryptischen Titel. Der Frontmatter-title ist eine schlichte, selbsterklärende Überschrift, die angibt, was passiert ist und den Nutzen transportiert – „Making Kolu's macOS e2e CI lane 14x faster“, kein Slug und kein cleverer Teaser, den der Leser erst nach dem Lesen entschlüsseln kann. Lass die description den konkreten Haken andeuten (das 64-GB-Leck, der Ein-Zeichen-Tippfehler). Dies ist eine bewusste Abkehr von den älteren Beiträgen mit evokativen Titeln hin zu Titeln, die dem Leser von Anfang an sagen, was er lernen wird – wende dies auf jeden neuen Beitrag an. Wenn ein Titel bewusst evokativ bleibt („The spacetime of code“), gib ihm einen optionalen subtitle im Frontmatter – eine klare Zeile, die die Metapher in das entschlüsselt, was der Leser lernen wird; es wird als Untertitel unter dem Titel dargestellt.

4. Binde es in die Website ein. Beiträge liegen in website/src/content/blog/ unter einem kurzen, stabilen Slug (der Dateiname ist die URL). Verwende die Komponenten der Website für Hervorhebungen, GitHub PR/Issue-Verweise und das Inhaltsverzeichnis; zitiere die echten PRs hinter jeder Behauptung und gib dem Beitrag eine zweistufige Überschriften-Gliederung, damit das Inhaltsverzeichnis verschachtelt wird – schreibe die Überschriften als klare Wegweiser des jeweiligen Abschnittspunkts, nicht als Teaser, damit die Inhaltsliste wie das Argument in Miniaturform gelesen wird. Verlinke jede Technologie, jedes Werkzeug, jede Bibliothek, jedes Format und jedes Produkt bei seiner ersten Erwähnung – [Playwright](https://playwright.dev/), [ffmpeg](https://ffmpeg.org/), eine CDP-Methode zu ihrer eigenen Dokumentationsseite – so wie es die bestehenden Beiträge tun; eine benannte Technologie ohne Link ist ein Fehler. Wenn der Inhalt eine Abfolge von Schritten oder eine kurze Aufzählung ist (z. B. zwei API-Methoden, die jeweils fehlschlagen, zwei Fallstricke), verwende eine Markdown-Liste oder -Tabelle anstelle eines dichten Absatzes – behalte das Argument in Prosa, aber höre auf, aufzählbaren Inhalt in Absätzen zu verstecken (eine bewusste beitragsspezifische Lockerung der pg-Skill-Regel „ersetze Argumente nicht durch Aufzählungspunkte“). Wenn du etwas zitierst, das der Autor buchstäblich in die CLI-Eingabeaufforderung eines Agenten (Claude Code, Codex usw.) eingegeben hat, als Wendepunkt, rendere es mit der Prompt-Komponente (website/src/components/Prompt.astro) – <Prompt>…</Prompt> – nicht mit einem einfachen Blockzitat, damit es wie ein Mensch gelesen wird, der in das Eingabefeld des Agenten tippt; siehe auto-demo.mdx für die Referenzverwendung. Balanciere Prosa mit Screenshots und Code aus – hoste Bilder in der Website, verwende keine Hotlinks.

   Abbildungen: handgezeichnetes Inline-SVG, themenbewusst. Zeichne Diagramme direkt als Inline-<svg> im MDX (keine Diagrammbibliothek) – siehe macos-e2e-lane.mdx für fünf Referenzabbildungen. Färbe jeden Strich und jede Füllung mit den CSS-Custom-Properties der Website (--color-ink, --color-ink-dim, --color-ink-muted, --color-rule-strong, --color-amber, --color-live-alert, --color-live-lime, --color-void, …; die Palette lebt in website/src/styles/global.css), sodass eine Abbildung automatisch Hell/Dunkel verfolgt – kodiere niemals einen Hex-Wert fest. Gib jedem <svg> ein role="img" und ein aria-label, das die angezeigten Daten beschreibt.

   MDX/SVG-Falle (mühsam beim macOS-Lane-Beitrag erlernt). Astros MDX gibt camelCase-SVG-Präsentationsattribute (textAnchor, fontSize) wörtlich weiter, und SVG ignoriert sie stillschweigend – jedes Label wird mit dem 16px linksbündigen Standard gerendert. Verwende die tatsächliche kebab-case-SVG-Schreibweise jedes Attributs: text-anchor, font-size, font-weight, font-family, stroke-width, fill-opacity. Echte camelCase-SVG-Attribute wie viewBox bleiben unverändert. Durch bloßes Hinsehen wird es übersehen – erkenne es, indem du getBBox() in einem echten Browser gegen die gebaute Seite misst.

5. Verifiziere und veröffentliche. Baue die Website und bestätige, dass sie rendert, dann überprüfe jede Abbildung in sowohl dem hellen als auch dem dunklen Thema gegen die gebaute Ausgabe mit dem Chrome-Devtools-MCP – bestätige, dass Labels tatsächlich platziert sind (getBBox()), nicht nur im DOM vorhanden – bevor du den PR eröffnest. Führe nur die CI-Lane aus, die eine Änderung an der Dokumentation berühren kann (der Website-Build plus Formatierung und Linting – siehe das ci-Skill).