Skip to content

CONCEPT Cited by 2 sources

Markdown as agent-friendly format

Definition

Markdown as agent-friendly format is the structural property of Markdown — line-per-record, natural column alignment, grep-friendly prefixes, headings as implicit structure — that makes it materially easier for LLM-based coding agents to consume than nested-JSON or binary trace formats carrying the same information.

The argument is empirical, not prescriptive: the same model, same agent harness, same underlying profile data produces "radically better optimization suggestions" when the data is reshaped from nested JSON to Markdown. (Source: sources/2026-04-21-vercel-making-turborepo-96-faster-with-agents-sandboxes-and-humans)

Canonical heuristic

From Anthony Shew's 2026-04-21 Turborepo performance post verbatim:

"if something is poorly designed for me to work with, it's poorly designed for an agent, too. This isn't necessarily a comment about work quantity, but more so about interfaces. If something is hard for me to read, it stands to reason it's hard for an agent to read, too. This idea has its limits, but you'll see it quickly pay dividends in a moment."

The heuristic is not absolute — humans and agents have different cognitive profiles — but the overlap is large enough that human-readability-first format design is usually the right starting point for agent-consumed data.

Structural properties of Markdown that help

  • Line-per-record. grep / awk / sed / head all work; the agent can iterate through the file line by line without context-aware parsing.
  • Column-aligned tables. Tabular data (e.g. per- function self-time + total-time + location in a profile) stays visually structured.
  • Headings as implicit hierarchy. ## Hot Functions / ## Call Tree let the agent jump to a section without parsing an outer structure.
  • Code blocks for pre-formatted text. Type signatures, stack traces, file paths nest naturally.
  • Plain text. No encoding-decoding round trip; no escapedstring\"with\"quotes.

Structural properties of JSON that hurt

Reading Chrome Trace Event Format JSON as an agent, Shew observed verbatim:

"An LLM can theoretically read through and parse all this, but...well...just look at it. Function identifiers split across lines, irrelevant metadata mixed in with timing data, not grep-friendly. I pointed an agent at the file and watched it struggle through grep calls, trying to piece together function names from different lines, unsuccessfully trying to filter out noise. It was fumbling through this file in the same way I would."

The pathology is specifically that JSON encoded for interactive UI consumption (Perfetto flame-graph-render loads) optimises for the visualiser's parser, not for agent reasoning. Width-of-trace-events-array formats, deeply-nested span/process/thread trees, and fields keyed by single-letter abbreviations (ph, ts, pid, tid) all compound the difficulty.

Canonical patterns

Three distinct altitudes (profile output, per-page web content, sitemap enumeration) each with independent vendor canonicalisation.

Precedents

  • Bun --cpu-prof-md (2026-04, Jarred Sumner) — Bun was the first widely- distributed runtime to ship a Markdown profile output flag. Anthony Shew credits Sumner's tweet as the motivation for Turborepo's own Markdown profile output.
  • llms.txt — the convention for publishing LLM- friendly plain-text / Markdown index files at the root of a web property. Pre-dates the profile-format movement; same structural reasoning.

Limits

  • Binary data (images, compressed buffers, numeric arrays) doesn't fit.
  • Extremely dense tabular data may be better served by CSV with explicit schema; Markdown tables have ambiguous behaviour on row-count edges.
  • Machine-to-machine protocols don't benefit — if nothing in the loop is an agent, Markdown's natural- language affordances are dead weight.
  • Format-choice discipline shouldn't become format- choice blockage — JSON is the right answer for most automation; Markdown-for-agents is an additive companion.

Seen in

  • Turborepo performance post (Vercel, 2026-04-21) — canonical instance for profile output. Added turborepo-profile-md crate that emits .md alongside Chrome Trace JSON; radically better agent optimisation suggestions at same model+harness+data. This concept's definitional source.
  • Vercel content-negotiation post (Vercel, 2026-04-21) — sibling-altitude instance for web-content delivery. Accept-header-driven Markdown serving; 99.37 % payload reduction on a blog post.
Last updated · 476 distilled / 1,218 read