Designing for agentic systems is mostly bookkeeping

Most of what makes an agentic framework work in production isn't the model. It's the bookkeeping around it — what the agent is allowed to know, where its outputs go, and which decisions need a human signature before they leave the building.

This post is a kitchen-sink test for the blog renderer. Every element below should look intentional. If it doesn't, the styles need work.

Headings carry the structure

A second-level heading is the main divider in a long post. It should feel like a chapter break — visible in the table of contents but not shouty.

Third-level headings

These are for sub-points inside a section. They should be clearly subordinate to h2, not competing with it.

Fourth-level

Rare, but used occasionally for inline structure. Should still be readable.

Inline formatting

A paragraph can contain bold text for emphasis, italic text for tone, and inline code for technical references like getRelatedPosts() or environment variables like SITE_URL. Links should be obvious — like this one to the Vike documentation — without screaming for attention.

You should also be able to use strikethrough when you change your mind mid-paragraph, and combine bold and italic if the moment calls for it.

Code blocks

Here's a TypeScript example. Syntax highlighting comes from Shiki at build time, so there's no client-side highlighter to ship.

import { useData } from "vike-react/useData";
import type { BlogPost } from "../../data/blog-types";

export function getRelatedPosts(slug: string, limit = 3): BlogPost[] {
  const current = posts.find((p) => p.slug === slug);
  if (!current) return [];

  return posts
    .filter((p) => p.slug !== slug)
    .map((p) => ({
      post: p,
      score:
        p.tags.filter((t) => current.tags.includes(t)).length +
        (p.category === current.category ? 1 : 0),
    }))
    .filter(({ score }) => score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, limit)
    .map(({ post }) => post);
}

A shell example, for completeness:

npm run build:blog
npm run build
npx wrangler pages deploy dist/client

And a JSON example showing what the manifest looks like:

{
  "posts": [
    {
      "slug": "test-post-kitchen-sink",
      "title": "Designing for agentic systems is mostly bookkeeping",
      "date": "2026-04-11",
      "tags": ["ai", "agentic-frameworks"]
    }
  ]
}

Blockquotes

Blockquotes are for the moments when somebody else said it better, or when you want to slow the reader down for a paragraph.

The first principle is that you must not fool yourself — and you are the easiest person to fool. Most production agent failures I've seen start with a developer convincing themselves the system "basically works" because the happy path passes.

Multi-paragraph quotes also work:

Knowledge management isn't a tool problem. It's a discipline problem.

The teams that win at it are the ones who treat the lifecycle of a fact — capture, review, decay, retirement — as seriously as they treat the lifecycle of a feature.

Lists

Unordered lists, for parallel ideas:

• Capture happens at the boundary, not inside the agent
• Review is a separate step with separate tooling
• Decay is automatic unless someone re-confirms
• Retirement is explicit and audited

Ordered lists, for sequences:

1. Define what the agent is allowed to know
2. Define where its outputs are allowed to go
3. Define which decisions need a human in the loop
4. Wire the audit trail before you wire the model

Nested lists, when the structure demands it:

• Capture stage
  • From conversation logs
  • From git history
  • From code review comments
• Review stage
  • Automatic dedup
  • Human approval for novel claims
  • Promotion to canonical KB

Images

Cover images and inline images both render through the same path. Here's an inline placeholder you can swap with a real asset later:

The image gets a soft shadow and rounded corners automatically. No need to remember the wrapper class.

Video links

YouTube and Vimeo links render as plain links in markdown. For now, embed by pasting the URL on its own line:

Watch the talk: Designing agentic systems for production

A future version of this site can auto-detect video URLs and replace them with <iframe> embeds during the build step. For now, treat them as link cards.

Tables

Tables are for comparisons that don't fit a sentence:

Pattern	Where it lives	Audit cost	When to use
Tool call	Inside the agent	Low	Read-only operations
Action proposal	Outside the agent	Medium	Writes, sends, deletions
Human-in-the-loop	Outside the agent	High	Anything that touches prod
Async signed action	Outside the agent	High	Cross-team boundaries

Horizontal rules

Sometimes the structure needs a hard break.

---

After the rule, you should feel like you've moved to a different beat. Use sparingly.

Closing thoughts

If everything above renders cleanly — headings step down properly, code blocks have a dark background and syntax colors, the blockquote has its indigo bar, tags appear as pills below the title, and the images have rounded corners with a soft shadow — the renderer is in good shape.

If something looks off, fix it here before the first real post. The goal is that every future post can focus on the writing, not the styling.