撰写一篇 kolu 博客文章
一篇 kolu 博客文章是一篇第一人称工程随笔，基于实际发生的构建过程——死胡同、关键决策、教会教训的 Bug。其事实来源是产生该工作的 Claude Code 会话日志，而非虚构的营销文案。
展示故事，而非仅仅讲述。 好的文章依赖图形胜于文字：轨迹图、前后对比卡片、时间线、流程图、对比柱状图、真实截图——可视化比文本承载更多论证内容。每个图形都基于真实数据（状态时间戳、ps 输出、测量时长）；图表是一种论证，绝非装饰。这一点适用于每篇文章，不仅仅是那些明显可视化的文章。
步骤
-
定位工作的会话。 找到功能背后的 Claude Code 会话日志（它们位于
~/.claude/projects/下，每个工作目录对应一个子目录）。通过追踪 PR → 分支 → 日志来确定性地映射它们，而不是通过关键字搜索。 -
挖掘故事。 从日志中读取人类/助手之间的叙述，提取决策背后的原因、来之不易的教训和死胡同、具体的机制以及生动的逐字引述。当工作量超过少数几个会话时，使用 ultracode 工作流 展开——为每个会话记录分配一个代理，返回结构化注释——然后将这些注释综合成一份摘要，从中起草，并进行对抗性编辑审阅。摘要是经过事实核查的脊梁；切勿捏造数字、日期、引述或 PR。
-
以作者的口吻撰写。 除非另有指示，否则使用
pg技能（Paul Graham 口吻），并事先确定内联文体风格。与现有文章的语体保持一致；新文章通常是对某篇旧文章的续篇。给它一个非晦涩的标题。 前置元数据中的title是一个直白、不言自明的标题，陈述发生了什么事并传达收益——例如“将 Kolu 的 macOS e2e CI 通道提速 14 倍”，而不是一个无法解析的缩写或巧妙的诱饵。让description暗示具体的吸引点（例如 64 GB 泄漏、一个字符的排版错误）。这是有意从早期富有暗示性的标题向能事先告诉读者将学到什么的标题的转变——将其应用于每一篇新文章。当标题有意保持富有暗示性时（例如“代码的时空”），在前置元数据中给它一个可选的subtitle——一行直白的话，将隐喻解密为读者将学到什么；它作为副标题呈现在主标题下方。 -
将其接入网站。 文章存放在
website/src/content/blog/下的短且稳定的 slug 中（文件名即 URL）。使用站点的组件来处理标注、GitHub PR/问题引用和目录；为每个主张引用真实的 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 会原样传递驼峰式 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技能）。