juspay/kolu

Escribir un blog post kolu

Un blog post kolu es un ensayo de ingeniería en primera persona basado en lo que realmente sucedió cuando se construyó algo: el callejón sin salida, la decisión crucial, el error que enseñó la lección. Su fuente de verdad son los registros de sesión de Claude Code que produjeron el trabajo, no un texto de marketing inventado.

Muestra la historia, no solo la cuentes. Un buen post se apoya en figuras más que en prosa: un gráfico de trayectoria, tarjetas de antes/después, una línea de tiempo, un diagrama de flujo, una barra comparativa, una captura de pantalla real — la visualización carga más argumento que el texto. Cada figura se basa en datos reales (marcas de tiempo de estado, salida de ps, duraciones medidas); un gráfico es un argumento, nunca decoración. Esto aplica a todos los posts, no solo a los obviamente visuales.

Pasos

1. Localiza las sesiones del trabajo. Encuentra los registros de sesión de Claude Code detrás de la funcionalidad (están en ~/.claude/projects/, un directorio por directorio de trabajo). Mapealos de manera determinista trazando PRs → ramas → registros, no por coincidencias de palabras clave.

2. Extrae la historia de ellos. Lee la narrativa humana/asistente de los registros y extrae el porqué detrás de las decisiones, las lecciones duramente aprendidas y los callejones sin salida, los mecanismos concretos y las citas textuales vívidas. Cuando el esfuerzo abarque más de un puñado de sesiones, distribuye el trabajo con un flujo de trabajo ultracode — un agente por transcripción que devuelva notas estructuradas — luego sintetiza las notas en un único resumen, redacta a partir de él y ejecuta una pasada de edición adversarial. El resumen es la columna vertebral verificada; nunca inventes números, fechas, citas o PRs.

3. Escribe en la voz del autor. Usa la habilidad pg (voz de Paul Graham) a menos que se indique lo contrario, y establece el estilo de la casa en línea desde el principio. Iguala el registro de los posts existentes; un post nuevo a menudo funciona como secuela de uno anterior. Dale un título no críptico. El title del frontmatter es un encabezado simple y autoexplicativo que indica lo que sucedió y contiene la recompensa — "Haciendo el carril CI e2e de macOS de Kolu 14x más rápido", no un slug ni un teaser ingenioso que el lector no pueda descifrar hasta terminar. Deja que el description anticipe el gancho concreto (la fuga de 64 GB, el error tipográfico de un carácter). Este es un cambio deliberado respecto a los posts anteriores con títulos evocativos hacia títulos que le dicen al lector de antemano lo que aprenderá — aplícalo a cada post nuevo. Cuando un título se mantiene deliberadamente evocativo ("El espacio-tiempo del código"), dale un subtitle opcional en el frontmatter — una línea simple que descifra la metáfora en lo que el lector aprenderá; se renderiza como un subtítulo debajo del título.

4. Conéctalo al sitio. Los posts viven en website/src/content/blog/ bajo un slug corto y estable (el nombre del archivo es la URL). Usa los componentes del sitio para llamadas, referencias a PRs/issues de GitHub y la tabla de contenidos; cita los PRs reales detrás de cada afirmación y dale al post un esquema de encabezados de dos niveles para que la TOC se anide — escribe los encabezados como indicadores simples del punto de cada sección, no como teasers, de modo que la lista de contenidos se lea como el argumento en miniatura. Enlaza cada tecnología, herramienta, biblioteca, formato y producto en su primera mención — [Playwright](https://playwright.dev/), [ffmpeg](https://ffmpeg.org/), un método CDP a su propia página de documentación — como hacen los posts existentes; una tecnología nombrada sin enlace es un error. Cuando el contenido sea una secuencia de pasos o una enumeración breve (por ejemplo, dos métodos API que fallan cada uno, dos problemas), usa una lista o tabla de Markdown en lugar de un párrafo denso — mantén el argumento en prosa, pero deja de esconder contenido enumerable en párrafos (una relajación deliberada y específica del post de la regla "no reemplaces argumentos con viñetas" de la habilidad pg). Cuando cites algo que el autor escribió literalmente en el cuadro de comandos CLI de un agente (Claude Code, Codex, etc.) como un punto de inflexión, renderízalo con el componente Prompt (website/src/components/Prompt.astro) — <Prompt>…</Prompt> — no con un blockquote simple, para que se lea como un humano escribiendo en el campo de entrada del agente; consulta auto-demo.mdx para el uso de referencia. Equilibra la prosa con capturas de pantalla y código — aloja las imágenes en el sitio, no hagas hotlinking.

   Figuras: SVG inline escrito a mano, con soporte de tema. Dibuja los gráficos directamente como <svg> inline en el MDX (sin biblioteca de gráficos) — consulta macos-e2e-lane.mdx para cinco figuras de referencia. Colorea cada trazo y relleno con las propiedades CSS personalizadas --color-* del sitio (--color-ink, --color-ink-dim, --color-ink-muted, --color-rule-strong, --color-amber, --color-live-alert, --color-live-lime, --color-void, …; la paleta está en website/src/styles/global.css) para que una figura siga automáticamente el tema claro/oscuro — nunca codifiques un valor hexadecimal. Dale a cada <svg> un role="img" y un aria-label que describa los datos que muestra.

   Problema MDX/SVG (duramente ganado en el post del carril macOS). El MDX de Astro pasa los atributos de presentación SVG en camelCase (textAnchor, fontSize) literalmente, y SVG los ignora silenciosamente — cada etiqueta se renderiza con el valor predeterminado de 16px alineado a la izquierda. Usa la ortografía SVG real en kebab-case de cada atributo: text-anchor, font-size, font-weight, font-family, stroke-width, fill-opacity. Los atributos SVG genuinamente en camelCase como viewBox se quedan como están. Una revisión superficial lo pasa por alto — atrápalo midiendo getBBox() en un navegador real contra el sitio construido.

5. Verifica y entrega. Construye el sitio y confirma que se renderiza, luego verifica cada figura en ambos temas, claro y oscuro contra la salida construida con el MCP de chrome-devtools — confirma que las etiquetas están realmente colocadas (getBBox()), no meramente presentes en el DOM — antes de abrir el PR. Ejecuta solo el carril CI que un cambio de documentación pueda tocar (la construcción del sitio web más el formateo y lint — consulta la habilidad ci).