kolu ブログ記事の執筆
kolu ブログ記事とは、実際に起こったこと (行き詰まり、重要な決断、教訓を与えたバグ) を一次情報とする一人称のエンジニアリングエッセイです。その情報源は、作業を生み出した Claude Code のセッションログであり、創作されたマーケティングコピーではありません。
語るだけでなく、見せること。 優れた記事は散文よりも図に重きを置きます。推移グラフ、Before/After カード、タイムライン、フロー図、比較棒グラフ、実際のスクリーンショット — テキストよりも多くの主張を伝える可視化です。すべての図は実際のデータ (ステータスのタイムスタンプ、ps の出力、計測された所要時間) に基づいており、グラフは議論であって飾りではありません。これは明らかに視覚的な記事だけでなく、すべての記事に当てはまります。
手順
-
作業のセッションを特定する。 機能の背後にある Claude Code のセッションログを見つけます (ログは
~/.claude/projects/以下、ワーキングディレクトリごとに一つのディレクトリ)。キーワードヒットではなく、PR → ブランチ → ログ を辿ることで決定的にマッピングします。 -
ログからストーリーを抽出する。 ログから人間とアシスタントの対話を読み解き、決定の背景、苦労して得た教訓や行き詰まり、具体的なメカニズム、生き生きとした逐語的な引用を引き出します。作業が数セッションを超える場合は、ウルコードワークフロー で展開します — トランスクリプトごとに1つのエージェントが構造化されたメモを返し、それらのメモを統合してダイジェストを作成し、そこから下書きを書いて、敵対的な編集パスを実行します。ダイジェストは事実確認済みの背骨であり、数値、日付、引用、PR を決して捏造してはいけません。
-
著者の声で書く。 特に指示がない限り
pgスキル (Paul Graham スタイル) を使用し、インラインのハウススタイルは事前に決めておきます。既存の記事のトーンに合わせます。新しい記事は多くの場合、既存の記事の続編としてペアになります。タイトルは難解にしない。 frontmatter のtitleは、何が起こったかを平易かつ自己説明的に述べ、見返りを含む見出しにします — 「Making Kolu's macOS e2e CI lane 14x faster」であって、スラッグや、読み終えるまで解読できない巧妙なティーザーではありません。descriptionには具体的なフック (64 GB のリーク、一文字のタイポ) を記載します。これは、読者が何を学べるかを冒頭で伝えるタイトルへの意図的なシフトであり、すべての新しい記事に適用します。タイトルをあえて示唆的にする場合 (「The spacetime of code」) は、frontmatter にオプションのsubtitleを追加します — メタファーを読者が学べる内容に解読する、平易な一文です。これはタイトルの下にデッキとして表示されます。 -
サイトに組み込む。 記事は
website/src/content/blog/以下に、短く安定したスラッグ (ファイル名が URL) で配置します。サイトのコンポーネントを使用して、コールアウト、GitHub PR/Issue 参照、目次を生成します。各主張の背後にある実際の PR を引用し、記事には2レベルの見出しアウトラインを設定して TOC がネストされるようにします — 見出しは各セクションのポイントを平易に示す標識とし、ティーザーにしないことで、目次が議論のミニチュアとして機能するようにします。すべての技術、ツール、ライブラリ、フォーマット、製品について、最初の言及時にリンクを貼ります —[Playwright](https://playwright.dev/)、[ffmpeg](https://ffmpeg.org/)、CDP メソッドはそのドキュメントページへ — これは既存の記事と同じ方式です。名前のある技術にリンクがないのは不備です。内容が一連の手順や短い列挙 (例：2つのAPIメソッドがそれぞれ失敗する、2つのハマりどころ) である場合、密集した段落ではなくマークダウンリストまたはテーブルを使用します — 議論は散文に保ちますが、列挙可能な内容を段落に隠すのをやめます (pgスキルの「議論を箇条書きで置き換えない」ルールに対する、記事固有の意図的な緩和です)。著者が転換点としてエージェントの CLI プロンプトボックス (Claude Code、Codex など) に実際に入力した内容を引用する場合は、Promptコンポーネント (website/src/components/Prompt.astro) を使用して<Prompt>…</Prompt>のようにレンダリングします — 単なる引用ブロックではありません。これにより、人間がエージェントの入力フィールドに入力しているように見えます。使用例はauto-demo.mdxを参照してください。散文とスクリーンショットやコードのバランスを取ります — 画像はサイトにホストし、ホットリンクは避けます。Figure: 手書きのインライン SVG、テーマ対応。 チャートはチャートライブラリを使わず、MDX 内に直接インライン
<svg>として描画します — 参考となる5つの Figure はmacos-e2e-lane.mdxを参照してください。すべての線と塗りつぶしには、サイトの--color-*CSS カスタムプロパティ (--color-ink、--color-ink-dim、--color-ink-muted、--color-rule-strong、--color-amber、--color-live-alert、--color-live-lime、--color-void、…。パレットはwebsite/src/styles/global.cssにあります) を使用して色を付け、Figure が自動的にライト/ダークテーマに追従するようにします — 16進数の値をハードコードしてはいけません。各<svg>にrole="img"と、表示するデータを説明するaria-labelを設定します。MDX/SVG の落とし穴 (macOS-lane 記事で苦労して得た知見)。 Astro の MDX は camelCase の SVG 表示属性 (
textAnchor、fontSize) をそのまま通し、SVG はそれらを静かに無視します — すべてのラベルが 16px 左揃えのデフォルトでレンダリングされます。各属性には実際のケバブケースの SVG スペルを使用します:text-anchor、font-size、font-weight、font-family、stroke-width、fill-opacity。viewBoxのような真の camelCase SVG 属性はそのままにします。目視では見逃します — 実際のブラウザで ビルドされた サイトに対してgetBBox()を測定して確認します。 -
検証して出荷する。 サイトをビルドしてレンダリングされることを確認し、ライトテーマとダークテーマの両方 で各 Figure をビルド出力に対して chrome-devtools MCP を使って確認します — ラベルが実際に配置されていること (
getBBox()) を確認します。単に DOM に存在するだけでは不十分です。PR を開く前に行います。 ドキュメント変更が触れる可能性のある CI レーンのみを実行します (ウェブサイトビルドとフォーマット、lint —ciスキルを参照)。