juspay/kolu

Escrevendo um post de blog kolu

Um post de blog kolu é um ensaio de engenharia em primeira pessoa baseado no que realmente aconteceu quando algo foi construído — o beco sem saída, a decisão crucial, o bug que ensinou a lição. Sua fonte de verdade são os logs de sessão do Claude Code que produziram o trabalho, não texto de marketing inventado.

Mostre a história, não apenas conte-a. Um bom post se apoia mais em figuras do que em prosa: um gráfico de trajetória, cartões de antes/depois, uma linha do tempo, um diagrama de fluxo, uma barra de comparação, uma captura de tela real — visualização carregando mais do argumento do que texto. Cada figura é baseada em dados reais (timestamps de status, saída de ps, durações medidas); um gráfico é um argumento, nunca decoração. Isso se aplica a todo post, não apenas aos obviamente visuais.

Etapas

1. Localize as sessões do trabalho. Encontre os logs de sessão do Claude Code por trás do recurso (eles ficam em ~/.claude/projects/, um diretório por diretório de trabalho). Mapeie-os deterministicamente rastreando PRs → branches → logs, não por acertos de palavra-chave.

2. Mine-os para obter a história. Leia a narrativa humano/assistente dos logs e extraia o porquê por trás das decisões, as lições difíceis e becos sem saída, os mecanismos concretos e citações literais vívidas. Quando o esforço abranger mais do que algumas sessões, distribua com um fluxo de trabalho ultracode — um agente por transcrição retornando notas estruturadas — depois sintetize as notas em um único resumo, redija a partir dele e execute uma passagem de edição adversarial. O resumo é a espinha dorsal verificada; nunca invente números, datas, citações ou PRs.

3. Escreva na voz do autor. Use a habilidade pg (voz de Paul Graham) a menos que instruído de outra forma, e estabeleça o estilo inline da casa antecipadamente. Combine o registro dos posts existentes; um novo post frequentemente atua como sequência de um. Dê a ele um título não enigmático. O title do frontmatter é um título simples e autoexplicativo que declara o que aconteceu e carrega a recompensa — "Tornando a pipeline CI e2e do Kolu para macOS 14x mais rápida", não um slug e não uma provocação inteligente que o leitor não consegue decifrar até terminar. Deixe o description provocar o gancho concreto (o vazamento de 64 GB, o erro de digitação de um caractere). Esta é uma mudança deliberada dos posts mais antigos com títulos evocativos para títulos que informam o leitor de antemão o que aprenderão — aplique-a a todo novo post. Quando um título permanece deliberadamente evocativo ("O espaço-tempo do código"), dê a ele um subtitle opcional no frontmatter — uma linha simples que decifra a metáfora no que o leitor aprenderá; ele é renderizado como um subtítulo abaixo do título.

4. Conecte-o ao site. Os posts ficam em website/src/content/blog/ sob um slug curto e estável (o nome do arquivo é a URL). Use os componentes do site para marcações, referências a PRs/issues do GitHub e o índice de conteúdo; cite os PRs reais por trás de cada afirmação e dê ao post um esboço de cabeçalhos de dois níveis para que o TOC se aninhe — escreva os cabeçalhos como indicadores simples do ponto de cada seção, não provocações, para que a lista de conteúdos seja lida como o argumento em miniatura. Linke toda tecnologia, ferramenta, biblioteca, formato e produto na primeira menção — [Playwright](https://playwright.dev/), [ffmpeg](https://ffmpeg.org/), um método CDP para sua própria página de documentação — da mesma forma que os posts existentes fazem; uma tecnologia nomeada sem link é uma falha. Quando o conteúdo é uma sequência de etapas ou uma enumeração curta (por exemplo, dois métodos de API que falham, duas pegadinhas), use uma lista ou tabela markdown em vez de um parágrafo denso — mantenha o argumento em prosa, mas pare de esconder conteúdo enumerável em parágrafos (um afrouxamento deliberado específico para posts da regra da habilidade pg de "não substitua argumento por marcadores"). Quando você citar algo que o autor digitou literalmente no campo de prompt da CLI de um agente (Claude Code, Codex, etc.) como um ponto de virada, renderize-o com o componente Prompt (website/src/components/Prompt.astro) — <Prompt>…</Prompt> — não um blockquote simples, para que pareça um humano digitando no campo de entrada do agente; veja auto-demo.mdx para o uso de referência. Equilibre prosa com capturas de tela e código — hospede imagens no site, não use hotlinking.

   Figuras: SVG inline feito à mão, sensível ao tema. Desenhe gráficos diretamente como <svg> inline no MDX (sem biblioteca de gráficos) — veja macos-e2e-lane.mdx para cinco figuras de referência. Pinte cada traço e preenchimento com as propriedades CSS personalizadas --color-* do site (--color-ink, --color-ink-dim, --color-ink-muted, --color-rule-strong, --color-amber, --color-live-alert, --color-live-lime, --color-void, …; a paleta fica em website/src/styles/global.css) para que uma figura acompanhe automaticamente claro/escuro — nunca codifique um valor hexadecimal. Dê a cada <svg> um role="img" e um aria-label descrevendo os dados que ele mostra.

   Pegadinha MDX/SVG (conquistada a duras penas no post da pipeline macOS). O MDX do Astro passa atributos de apresentação SVG camelCase (textAnchor, fontSize) literalmente, e o SVG os ignora silenciosamente — cada rótulo renderiza no padrão de 16px alinhado à esquerda. Use a grafia SVG real em kebab-case de cada atributo: text-anchor, font-size, font-weight, font-family, stroke-width, fill-opacity. Atributos SVG genuinamente camelCase como viewBox permanecem como estão. A olho nu não percebe — detecte medindo getBBox() em um navegador real contra o site construído.

5. Verifique e envie. Construa o site e confirme que ele renderiza, depois verifique cada figura em ambos os temas claro e escuro contra a saída construída com o MCP chrome-devtools — confirme que os rótulos estão realmente posicionados (getBBox()), não meramente presentes no DOM — antes de abrir o PR. Execute apenas a pipeline CI que uma alteração de documentação pode tocar (a construção do site mais formatação e lint — veja a habilidade ci).