agent-legibility
Agent legibility — the design discipline of optimizing systems so that an LLM agent can directly read them at runtime: UI, logs, metrics, traces, dependencies, code, docs. The central frame of 2026-04-27-harness-engineering-codex-agent-first: a fully agent-generated codebase has to be designed for the agent’s eye, not the human’s. Anything the agent can’t see in context at runtime doesn’t exist for it — and that constraint reshapes design tradeoffs across the stack.
The page is the OpenAI-side primary source for an instinct that 2026-04-27-agent-principles-architecture-engineering surfaced earlier under ACI; this page is the more general system-level framing while agent-computer-interface stays focused on tool design specifically.
The core operating premise
从智能体的角度来看，它在运行时无法在情境中访问的任何内容都是不存在的。
(From the agent’s perspective, anything it can’t access in context at runtime doesn’t exist.)
Knowledge in Slack, Google Docs, or someone’s head is invisible. Architectural decisions discussed in a meeting and never written down don’t bind future agent runs. Code patterns visible only at review time don’t propagate to fresh sessions. The fix: push everything that needs to influence agent behavior into versioned, repo-local artifacts (codebase-as-system-of-record).
Three classes of legibility investment
From 2026-04-27-harness-engineering-codex-agent-first, plus the prior framing on agent-computer-interface:
| Class | Concrete moves | What it unlocks |
|---|---|---|
| Application legibility | Per-worktree app instance; Chrome DevTools Protocol bridge for DOM snapshots / UI driving / runtime event observation; ephemeral observability stack per worktree (LogQL for logs, PromQL for metrics) | Codex can reproduce bugs, validate fixes by running the app, and reason about UI behavior directly — instead of reading screenshots a human had to capture. |
| Codebase legibility | Strict layering (architectural-invariants); AGENTS.md as table of contents (not encyclopedia); structured docs/; “boring” technologies preferred for predictability; sometimes re-implementing a small subset of a public library rather than depending on its opaque upstream behavior | Agents can build a complete mental model of the system from the repo alone, without needing a human guide. |
| Operational legibility | Logs / metrics / traces queryable by the agent; prompts like “ensure startup completes in under 800ms” are mechanically actionable | The agent can verify performance and reliability claims itself — verification is an agent-runnable function, not a human checkpoint. |
The “boring tech” tradeoff
A specific design move from 2026-04-27-harness-engineering-codex-agent-first: agents have an easier time modeling technologies that are composable, API-stable, and well-represented in their training data — i.e. “boring” ones. This shifts dependency choices:
- Prefer. Mature, widely-used libraries with stable APIs and clear semantics — the agent can predict behavior from the API alone.
- Avoid. Opaque, magic-heavy, or fast-moving libraries — the agent’s mental model and the upstream’s actual behavior drift apart over time.
- Sometimes re-implement. Cited example: rather than depend on
p-limit, the team built their own concurrent-map helper integrated with their OpenTelemetry instrumentation, with 100% test coverage and predictable runtime behavior. The cost of re-implementation was lower than the ongoing cost of the agent reasoning over an opaque dependency.
The principle: an in-house implementation the agent can read is worth more than an external implementation it has to model from documentation. This is only a winning tradeoff when the system is built around agent legibility from the start — for human-only teams, the cost flips back the other way.
Relation to other concepts
- agent-computer-interface is the tool-shaped slice of this idea — design tools (descriptions, errors, examples) for the agent’s decision-making, not for API tidiness. This page is the broader system-level framing including non-tool surfaces (UI, logs, code structure, dependency choice).
- codebase-as-system-of-record is the corollary on the content side — if the agent can’t see Slack, push everything that matters into the repo.
- architectural-invariants is one mechanism for making the codebase legible: predictable structure the agent can rely on.
- harness is the umbrella — legibility is the feedback signal part of the harness applied to everything the agent reads, not just to verification.
- context-engineering is the resource-level constraint: legibility doesn’t help if the legible content can’t fit in context. The two co-design.
Spectrum, not binary
Most existing systems are partially agent-legible. The investments in 2026-04-27-harness-engineering-codex-agent-first (worktree-per-change, ephemeral observability, custom linters with fix instructions, etc.) are at one end of a spectrum. The pragmatic move when introducing an agent into an existing codebase is to identify the largest legibility gap (most often: where verification depends on a human running the app) and close it first.