Writing technical articles and blog posts. Use when creating articles in docs/articles/ or blog content explaining patterns, techniques, or lessons learned.
All articles must follow writing-voice rules.
Use this pattern when you need to:
docs/articles/ or blog-style engineering posts.Title should BE the takeaway, not a topic. "Write Context to a File, Not a Prompt" not "Context Management in Agent Workflows".
Lead with a strong opening paragraph that states the key insight in plain language. Reader should get it in 5 seconds. Then go straight into code. Don't force a blockquote or pull-quote after the opening; if the insight needs a quotable summary, the opening paragraph already is one.
Code speaks louder than prose. Show real examples from actual codebases, not abstract foo/bar illustrations. If the code is self-explanatory, don't over-explain.
Section headings should make claims, not announce topics. The reader should know your position from the heading alone.
Bad (topic headings):
What's in the binary
How Go and Rust compare
Why tree-shaking is difficult
Good (argument headings):
Go and Rust: Your code IS the binary
Bun (and Deno/Node): Your code rides on top of a VM
Why tree-shaking the runtime is brutally hard
The first set describes what the section is about. The second set tells you what the section argues. A reader who only skims headings should walk away with the article's core argument.
This applies to the title too: "Bun Compile Is 57MB Because It's Not Your Code" is an argument. "Understanding Bun Compile Binary Size" is a topic.
Write like you're explaining to a peer, not presenting to an audience. Short declarative sentences. Opinions stated plainly. Concessions acknowledged without hedging.
Bad (formal article-speak):
The resulting bundle size of the
bun build --compilecommand is notably large. With careful analysis, we can identify several contributing factors.
Good (direct, conversational):
A
console.log("Hello World")compiles to 57MB. Your code adds almost nothing. The binary is the entire Bun runtime.
Parenthetical asides, dashes for emphasis, and sentence fragments are all fine when they serve clarity. "Stripping the JIT? Now your code runs 10-100x slower." reads better than a formally constructed alternative.
ASCII diagrams, tables, and before/after code blocks are tools to reach for when they clarify something prose can't. They are not required ingredients.
Use a diagram when showing flow or architecture that's hard to describe linearly. Use a table when there's a genuine comparison with 3+ items. Use before/after code when the contrast IS the point. Skip all of them when the article doesn't need them.
When you have multiple independent reasons for something, write them as regular prose with natural transitions. Don't use numbered bold headings (**1. Bold heading** followed by explanation)—that pattern is one of the most recognizable AI writing tells.
This is the most important section. Good articles alternate between prose and visuals. The reader's eye should bounce: context → code → explanation → diagram → implication. Neither prose nor code should dominate for long stretches.
[1-2 sentences: what the problem is]
\`\`\`typescript
// code showing the problem
const result = table.find(id); // O(n) scan every time
\`\`\`
[1 sentence: why this is bad, bridge to solution]
\`\`\`typescript
// code showing the solution
const result = index.get(id); // O(1) lookup
\`\`\`
[1-2 sentences: what this means for the reader]
[Paragraph explaining the problem]
[Paragraph explaining the approach]
[Paragraph explaining the implementation]
[Paragraph explaining the result]
\`\`\`typescript
// single code block at the bottom
\`\`\`
The first version lets the reader verify each claim against code as they go. The second forces them to hold four paragraphs in memory, then mentally map them to code.
The opening paragraph carries the entire article. If someone reads nothing else, this paragraph should give them the insight.
Bad (topic announcement):
In this article, we'll explore how context management works in agent workflows and discuss some approaches to improving it.
Good (insight up front):
Write your context to a file, not a prompt. When a conversation spawns sub-agents, each one starts with a blank slate. If the context lives in a spec file on disk, every agent can read it fresh instead of relying on copy-pasted prompt fragments that drift.
The bad version tells the reader what the article is about. The good version tells them the answer. They'll keep reading to see why.
If the article originates from a voice transcript, chat brainstorm, or spoken-out-loud reasoning, the user's own phrases ARE the voice of the article. Reconstructing them in "better" English strips out the cadence that made the insight land in the first place — and the user won't recognize their own thought on the page. They'll bounce.
The test: would the user, skimming their own article a week later, feel the impetus that made them want to write it? If the opening is polished into generic technical prose, no.
Use the user's exact phrases in the first paragraph. Not paraphrased, not smoothed. The raw phrase — lightly cleaned for grammar, never for cadence. Even mildly awkward phrasing ("I knew it was a smell because…") is better than a cleaner rewrite, because it's what the user actually thinks and how they'll remember the article.
If there's a core code transformation, it lands in the first ~100 words. Before / after, both visible in the first scroll. The prose explains; the code IS the article. Burying the code transformation below context-setting paragraphs means the reader never reaches it.
Lift specific phrases verbatim from the transcript. If the user said "I knew I had made a Svelte-specific version" — use that line, don't rewrite it to "I had created a framework-specific adapter." The specificity of the original phrasing is the voice.
Fidelity beats polish. When you're drafting from a transcript, err on the side of preserving the user's phrasing even when a more elegant sentence is available. The user wrote the insight in their head once; the article should match that mental version so they can still feel it when they re-read.
The tight coupling between framework-specific adapters became apparent during the implementation phase. A pattern emerged where reactive tracking was being used as an event subscription mechanism, suggesting a deeper architectural issue.
I realized I had made a Svelte-specific version. I knew it was a smell because I was calling
$effectjust to trackauth.token. That suggested to me I actually wanted an imperativeonTokenChange— and the only reason that API didn't exist was that I'd been wrapping Svelte on Svelte.
The first version is publishable. The second version sounds like someone thinking out loud, which is what the user was doing when they handed you the transcript.
When you need to explain how something works between code blocks, show the mechanism. Don't describe it abstractly.
Bad (abstract narration):
The system uses a layered approach to handle data storage efficiently. Each layer provides a different level of abstraction, allowing consumers to interact with data at the appropriate granularity for their use case.
Good (shows the mechanism):
RowStorewrapsCellStore, which wrapsYKeyValueLww. Each layer adds one thing:YKeyValueLwwhandles conflict resolution,CellStoreparses cell keys into row/column pairs, andRowStoremaintains an in-memory index for O(1) lookups. The consumer only seesRowStore.
The first version could describe anything. The second version could only describe this system.
Bullet lists and numbered lists: max 1-2 of each per article. If you need more, convert to prose or a table.
Section headings: use sparingly. Not every paragraph needs a heading. Let content flow naturally between ideas using bridge sentences (see writing-voice "Connect ideas without headers").
Bold text: avoid in body content. Use sparingly if needed for emphasis.
No space-dash-space: use colons, semicolons, or em dashes per writing-voice.
No rigid template: structure should fit the content, not the other way around. Some articles need a "Problem/Solution" flow; others just show code and explain. Don't force sections.
Don't follow a single template. Structure should fit the content. Some common shapes:
Problem → fix (short, practical): State the problem, show the code that fixes it, explain why. No diagrams, no tables, no extra sections. 30-50 lines.
Mechanism explainer (medium): Explain how something works under the hood, alternating prose and code. Diagrams when the flow is non-obvious. 50-80 lines.
Comparison or tradeoff analysis (longer): Show two or more approaches with real code from each. A table can help here because the comparison IS the point. ASCII diagrams when architecture differs between approaches. 80-150 lines.
The shape emerges from the content. If you find yourself adding a diagram or table to fill a perceived gap, you don't need it.
foo/bar code examples**1. Bold heading** pattern)Most "journey to an insight" articles still work better as punchy. Use narrative only when the discovery process itself is the insight and can't be compressed.
When narrative fits: specific details ("750 lines", not "a large file"), direct statements over manufactured drama, build to an insight rather than starting with it.
End with a plain statement of the implication. Don't reach for a grand summary or a clever sign-off. If the article showed that X solves Y, just say what that means for the reader in one or two sentences. Avoid closing with superlatives ("the most elegant", "truly powerful") or calls to action ("try it today!").
