Agent Legibility
Agent legibility is the property that a repo, product, tool, or organization is easy for an AI agent to inspect, reason about, operate, and verify.
Core idea
Humans can compensate for messy systems with memory, Slack archaeology, and social context. Agents cannot. They need the system's state, boundaries, commands, docs, logs, and success criteria to be explicit.
OpenAI's 2026 harness-engineering writeup makes this direction concrete: the team improved Codex output by making repository knowledge, UI state, logs, metrics, review patterns, and feedback loops readable and actionable to the agent. That is agent legibility: the environment is designed so the agent can orient itself and verify its work. Source: OpenAI, https://openai.com/index/harness-engineering/, 2026-02-11
Legibility surfaces
| Surface | Agent-legible version | Illegible version |
|---|---|---|
| Repository root | AGENTS.md, scripts, task commands, ownership map, current docs |
Tribal knowledge in chat, no entry point |
| Directory structure | Predictable ownership and local SKILL.md / README files |
Mixed concerns, hidden conventions |
| Commands | npm run doctor, npm test, qmd search, typed CLIs |
One-off shell incantations |
| Logs | Structured, timestamped, grep-able, trace IDs, artifact links | Pretty text blobs with missing context |
| Errors | Cause, suggested fix, docs link, failing invariant | Generic "something went wrong" |
| UI state | Inspectable DOM, stable selectors, URLs, screenshots, progress state | Visual-only state and hidden async transitions |
| Tool outputs | Small structured observations, pagination, provenance | Huge dumps that poison context |
| Memory | Wiki pages, timelines, activity logs, decision records | Chat history as the database |
| Quality gates | Doctors, evals, tests, linters, screenshots | "Looks good" from the model |
Next.js 16.3 Instant Insights is the clearest framework-level example of legibility moving into product UI. The overlay does not only say an uncached navigation is wrong; it identifies the failing line, presents Stream/Cache/Block as named choices, links per-rule docs, and exposes "Copy as prompt" controls that package the selected fix for a coding agent. That turns an error from a human-only message into a small executable repair contract. Source: X/@rauchg, 2026-06-25; Source: Next.js 16.3 AI Improvements, 2026-06-26
The most compact version is file-native: an agent should be readable from its directory tree. agent.ts, tools/, skills/, subagents/, connections/, schedules/, evals/, and package.json are not just implementation details; they are the agent's legibility surface. If another agent cannot inspect those files and infer what the system can do, when it acts, who it delegates to, and how it proves itself, the harness is hiding too much state. Source: X/@omarsar0, 2026-06-27; Source: Vercel Eve
Rauch's "healthy software habits" row is the standards-level version of the same idea. Agents pressure software toward open APIs, documentation-as-skills, tests-as-evals, Unix-like CLIs, explicit commerce protocols, and content negotiation because those surfaces are parseable, callable, and checkable. Good agent legibility often looks like old web/Unix discipline rediscovered under a new caller. Source: X/@rauchg, 2026-06-19
The Vercel CLI copywriting-guidelines PR is a concrete CLI version of this rule. Agent-callable commands need output that names the failed invariant, next action, relevant target, and docs/source link without burying the useful part in clever prose. CLI copy is not only brand tone; it is a recovery API for humans and agents. Source: X/@rauchg, 2026-07-04; Source: GitHub vercel/vercel PR 16774, 2026-07-04
The operational reason to keep skills file-based is that coding agents can patch them directly. A database-backed or UI-only skill registry may be readable to users, but a file-native skill lets the next agent inspect, diff, edit, validate, and commit the instruction update with the same workflow it uses for code. Source: X/@zachlloydtweets reply, 2026-06-17
Rauch's agent-debugging thread adds the failure mode and the human control surface. The root tweet names the two debugging pressures: AI models are intentionally nondeterministic, and agents are multi-step distributed systems. The follow-up says human judgment moves upstream to deciding what to build, which architecture to keep, when to regenerate, when to reuse existing pieces, and how much technical debt to carry. Legibility is the mechanism that keeps those choices inspectable instead of buried in nondeterministic runs. Source: X/@rauchg, 2026-06-27; Source: X/@rauchg, 2026-06-27
Jason Liu's compact /tasks/<task>/{plan, worklog, goal}.md reply is the same principle in file form:
agent work should leave a small task directory with the plan, the mutable worklog, and the goal state.
Those files make the run inspectable by a human and resumable by another agent without asking chat
history to be the database. Source: X/@jxnlco, 2026-06-26
Leo Di Donato's reply makes the reviewer-facing version explicit: after a patch passes, the next audit question is whether another agent can inspect the trace logs and explain every action it took. That makes trace readability a product requirement. Logs must be concise, ordered, and source-linked enough for a second model or reviewer to replay the run without trusting the first agent's summary. Source: X/@leodido, 2026-06-26
Agent legibility vs human polish
Human polish makes a system feel good to use. Agent legibility makes a system possible to operate. They overlap, but they are not the same.
| Human-facing design | Agent-facing design |
|---|---|
| Clear labels | Stable semantic labels and selectors |
| Helpful empty states | Machine-readable state and next actions |
| Good information hierarchy | Predictable document and command hierarchy |
| Beautiful dashboards | Queryable logs, traces, artifacts, and status endpoints |
| Concise copy | Unambiguous procedural instructions |
The best systems do both. A dashboard can be calm and beautiful while exposing a structured run state. A repo can be pleasant for humans while giving agents a deterministic entry path.
IRL comparison
| Pattern | Legibility contribution |
|---|---|
| Agent-Docs Mesh | Per-repo AGENTS.md, nearest SKILL.md, docs-doctor, and registry enrollment make projects readable to agents. |
| The Brain-Agent Loop | qmd search/query plus wiki pages make durable context searchable before web or memory guesses. |
| Doctor Pattern | Turns implicit standards into executable checks the agent can run. |
| Agent Trajectory Evaluation | Makes run behavior inspectable instead of relying on final messages. |
| Context Engineering | Selects and shapes information so the model's attention budget is spent on the right context. |
Anthropic's context-engineering guidance supports the same direction from another angle: agent performance depends on writing, selecting, compressing, and isolating context rather than dumping everything into the window. Source: Anthropic, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents, 2026-06-18
Runaway Recovery Boundaries
A model saying "I should stop" is not a stop condition. The reviewed Cursor artifact shows the failure mode clearly: the agent recognizes that it is rambling, apologizes, labels the output as final, then keeps generating more meta-repair text. Once recovery language becomes more output, the harness has to supply the boundary. Source: X/@kevskgs and local media review, 2026-07-04
The legible version is external and inspectable: per-turn output budgets, max-line caps for final answers, tool-output truncation, a "summarize and stop" transition, and a hard handoff to ask the user for a missing task instead of continuing the monologue. Self-diagnosis is a signal for the harness to cut over, not permission for another page of self-diagnosis.
Tests for legibility
Ask a fresh agent:
- Can you find the current source of truth in under two minutes?
- Can you list the right commands to validate a change?
- Can you identify what is stale, failing, or overdue?
- Can you resume a previous run from durable state?
- Can you explain why a prior run failed from logs/traces?
- Can you make a change without asking the user for tribal knowledge?
If the answer is no, the system is not agent-legible yet.
Kevin rule
For Kevin's stack, agent legibility is not optional polish. It is the productivity layer:
- write root routing docs,
- keep page routers current,
- encode taste as skills/doctors,
- expose commands and state in scripts,
- keep logs and timelines append-only,
- make UI state inspectable,
- preserve short slugs and stable links,
- run doctors after structural changes.
The less the next agent has to infer, the more it can actually build.
Timeline
- 2026-07-06 | Added Vercel CLI copywriting guidelines as a legibility rule: command output is a recovery API, so errors/help text need invariant, next action, target, and source clarity for both humans and agents. Source: X/@rauchg, 2026-07-04
- 2026-07-04 | Added the
/tasks/<task>/{plan, worklog, goal}.mdpattern as the compact file-native trace for agent runs: plan, live worklog, and goal state should be inspectable outside the chat transcript. Source: X/@jxnlco, 2026-06-26 - 2026-07-04 | Added Leo Di Donato's trace-audit reply as the reviewer-facing version: traces should be readable enough that another agent can audit the run's actions without trusting the original summary. Source: X/@leodido, 2026-06-26
- 2026-07-04 | Added the Cursor runaway-response artifact as a recovery-boundary failure: self-narrated stopping does not stop generation, so the harness needs external budgets, truncation, and summarize/ask gates. Source: X/@kevskgs, 2026-04-02
- 2026-07-04 | Added file-based skills as an editability surface: coding agents can update skills when they live in inspectable files. Source: X/@zachlloydtweets reply, 2026-06-17
- 2026-07-04 | Added Rauch's agent-era software-habits note: open APIs, docs/skills, tests/evals, CLIs, payment protocols, and broad content negotiation are agent-legibility surfaces. Source: X/@rauchg, 2026-06-19
- 2026-07-03 | Added Next.js 16.3 actionable errors as a concrete agent-legibility pattern: named fixes, linked docs, structured terminal output, and Copy-as-prompt controls turn framework errors into repair contracts. Source: X/@rauchg, 2026-06-25; Next.js blog, 2026-06-26
- 2026-06-18 | Created as the missing concept behind agent-docs mesh, context engineering, harness engineering, and observability. Source: whole-wiki graph audit, 2026-06-18
- 2026-06-28 | Added the file-native agent directory as a legibility surface: tools, skills, subagents, connections, schedules, evals, and package metadata should be inspectable on disk. Source: X/@omarsar0, 2026-06-27
- 2026-07-01 | Added Rauch's human-judgment layer: agent systems still need visible decision surfaces for architecture, reuse, regeneration cost, and technical debt. Source: raw/x-bookmarks/enriched/2070923036988248248.json
- 2026-07-03 | Deep-reviewed the root Rauch thread and added nondeterminism plus distributed-system complexity as the explicit debugging reason agent systems need legible traces, decision surfaces, and replayable work. Source: raw/x-bookmarks/enriched/2070676383135834334.json