Harness engineering: leveraging Codex in an agent-first world

Key Actionable Insights

1

Treat your AGENTS.md as a table of contents, not an encyclopedia. Keep it to roughly 100 lines that serve as a map with pointers to deeper documentation in a structured docs/ directory. A monolithic instruction file crowds out task context, rots quickly, and causes agents to pattern-match locally rather than navigate intentionally.

The team found that too much upfront guidance becomes 'non-guidance'—when everything is marked important, nothing is. Progressive disclosure lets agents start with a stable entry point and find relevant context on demand.

2

Invest in making your application directly legible to agents by exposing UI state, logs, metrics, and traces through programmatic interfaces. Wire Chrome DevTools Protocol into agent runtimes for DOM snapshots and screenshots, and provide local observability stacks with queryable APIs (LogQL, PromQL, TraceQL).

The team's bottleneck shifted from code throughput to human QA capacity. By making the application itself inspectable by agents, they enabled autonomous bug reproduction, fix validation, and performance verification without human intervention.

3

Enforce architectural invariants mechanically through custom linters and structural tests rather than relying on documentation alone. Write custom lint error messages that inject remediation instructions directly into agent context, turning every violation into a learning opportunity for the agent.

In a human-first workflow, strict linting rules might feel pedantic. With agents, they become multipliers—once encoded, they apply everywhere at once, preventing drift across a million-line codebase generated at high throughput.

4

Implement automated 'garbage collection' for your codebase by encoding golden principles and running recurring cleanup agents that scan for deviations, update quality grades, and open targeted refactoring pull requests. This catches bad patterns daily rather than letting them compound.

The team initially spent 20% of their week (every Friday) manually cleaning up 'AI slop.' By automating this into background Codex tasks with codified principles, they scaled cleanup proportionally to code generation throughput.

5

When agents struggle with a task, resist the urge to 'try harder' or write the code manually. Instead, diagnose what capability is missing—tools, guardrails, abstractions, or documentation—and have the agent itself build that missing capability into the repository.

This depth-first approach compounds over time: each missing capability that gets encoded becomes infrastructure for all future agent tasks, steadily increasing the scope of what agents can accomplish autonomously.

6

Push all relevant team knowledge into the repository as versioned, co-located artifacts. Slack discussions, Google Docs, and tacit human knowledge are invisible to agents—if it isn't discoverable in the repo, it effectively doesn't exist for the agent and leads to misaligned output.

This mirrors the new-hire onboarding problem: anything not written down is lost context. The team treats the repo as the single system of record for product principles, engineering norms, architecture decisions, and even team culture preferences.