撰寫一篇 kolu 部落格文章
kolu 部落格文章是一種第一人稱的工程散文，其基礎是建構某樣東西時實際發生的事 — 死胡同、關鍵決策、以及教會你教訓的 bug。它的真實性來源是產出該工作的 Claude Code 會話記錄，而非虛構的行銷文案。
展現故事，而不僅僅是講述它。 一篇好的文章倚賴圖表勝過文字：軌跡圖、前後對比卡片、時間軸、流程圖、比較柱狀圖、真實的螢幕截圖 — 讓視覺化元素承擔比文字更多的論述。每個圖表都基於真實數據（狀態時間戳、ps 輸出、測量的持續時間）；圖表是論點，絕非裝飾。這適用於每一篇文章，而不僅僅是那些明顯偏重視覺的。
步驟
-
定位工作的會話記錄。 找到功能背後的 Claude Code 會話記錄（它們位於
~/.claude/projects/目錄下，每個工作目錄一個資料夾）。透過追蹤 PR → 分支 → 記錄的方式來確定性地對應它們，而不是依賴關鍵字搜尋。 -
從中挖掘故事。 從記錄中閱讀人類/助理的對話敘事，並提取決策背後的原因、辛苦學到的教訓和死胡同、具體的機制，以及生動的逐字引述。當工作橫跨超過少數幾個會話時，使用超程式碼工作流程 — 每個記錄指派一個代理，負責回傳結構化的筆記 — 然後將這些筆記綜合成一份摘要，據此起草，並執行一輪對抗性的編輯檢查。這份摘要就是經過事實查核的主幹；切勿捏造任何數字、日期、引述或 PR。
-
用作者的口吻撰寫。 除非另有指示，否則使用
pg技能（Paul Graham 風格），並在一開始就訂好內文的格式規範。配合現有文章的措辭風格；新文章經常作為某篇現有文章的續篇。為它取一個非謎語式的標題。 Frontmatter 中的title是一個直白、不言自明的標題，說明發生了什麼事並承載著核心收穫 — 例如「讓 Kolu 的 macOS 端到端 CI 通道提速 14 倍」，而不是一個無意義的短語或一個讀者必須讀完整篇文章才能解讀的巧妙預告。讓description預告具體的鉤子（例如 64 GB 的記憶體洩漏、一個字元的 typo）。這是刻意從早期那些暗示性標題的文章轉變，轉向能讓讀者在一開始就知道他們會學到什麼的標題 — 將此規則應用於每篇新文章。當一個標題刻意保留暗示性時（例如「程式碼的時空」），請在 frontmatter 中提供一個可選的subtitle— 一行直白的文字，用以解讀該隱喻，讓讀者明白他們將學到的內容；它會以標題下方副標的形式呈現。 -
整合到網站中。 文章位於
website/src/content/blog/目錄下，使用簡短、穩定的 slug（檔名即為 URL）。使用網站的元件來處理提示框、GitHub PR/issue 引用以及目錄；為每個主張引用真實的 PR，並為文章提供二級標題的大綱，以便目錄可以嵌套 — 將標題寫成每個章節重點的直白路標，而不是謎語，這樣目錄列表本身就讀起來像是一個微縮的論點。在每個技術、工具、函式庫、格式和產品首次被提及時為其加上連結 — 例如[Playwright](https://playwright.dev/)、[ffmpeg](https://ffmpeg.org/)、一個 CDP 方法連到其自己的文檔頁面 — 就像現有文章所做的那樣；一個被命名的技術卻沒有連結就是一個失誤。當內容是一連串的步驟或一個簡短的列舉（例如兩個 API 方法都失敗了、兩個陷阱），請使用 Markdown 列表或表格，而不是一個密集的段落 — 將論點保留在散文中，但停止將可列舉的內容隱藏在段落中（這是刻意針對特定文章放寬pg技能中「不要用列表取代論點」的規則）。當你引用作者在關鍵時刻實際鍵入代理 CLI 提示框的文字時（例如 Claude Code、Codex 等），請使用Prompt元件（website/src/components/Prompt.astro）來呈現 — 使用<Prompt>…</Prompt>— 而不是普通的引用區塊，這樣它讀起來就像是人類正在代理的輸入欄位中打字；請參閱auto-demo.mdx以了解參考用法。平衡散文與螢幕截圖和程式碼 — 在網站中託管圖片，不要使用外部連結。圖表：手工製作內聯 SVG，且具主題感知能力。 直接在 MDX 文件中繪製圖表作為內聯
<svg>（無需圖表函式庫） — 請參閱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），這樣圖表就能自動適應淺色/深色主題 — 絕不要硬編碼十六進制顏色值。為每個<svg>加上role="img"屬性和一個aria-label屬性，用以描述它所顯示的數據。MDX/SVG 陷阱（在 macOS-lane 文章中得來的經驗）。 Astro 的 MDX 會直接傳遞駝峰式 (camelCase) 的 SVG 呈現屬性（例如
textAnchor、fontSize），而 SVG 會默默地忽略它們 — 每個標籤都會以 16px 左對齊的預設值呈現。請使用每個屬性的真正連字號 (kebab-case) SVG 拼寫：text-anchor、font-size、font-weight、font-family、stroke-width、fill-opacity。真正是駝峰式的 SVG 屬性（例如viewBox）則保持不變。用肉眼檢查很容易忽略這個問題 — 請透過在一個真正的瀏覽器中對建置後的網站測量getBBox()來發現它。 -
驗證並發布。 建置網站並確認它能正確呈現，然後對建置後的輸出，使用 Chrome DevTools MCP 在淺色和深色兩種主題下驗證每個圖表 — 確認標籤確實被放置了（透過
getBBox()），而不僅僅是存在於 DOM 中 — 然後再開啟 PR。僅執行文件變更可能觸及的 CI 通道（網站建置加上格式化與 lint — 請參閱ci技能）。