Harness Engineering: Leveraging Codex in an Agent-First World
The Shift to Zero Manually-Written Code
OpenAI has successfully developed and shipped an internal software product using zero lines of manually-written code. Over five months, a small team of engineers used Codex agents to generate application logic, tests, CI configuration, documentation, and observability tooling, resulting in a codebase of approximately one million lines. The team estimates that this agent-first approach reduced development time to roughly 1/10th of what manual coding would have required.
In this model, humans no longer act as the primary authors of code but instead serve as steerers. The engineering role has shifted toward designing systems, specifying intent, and building the feedback loops necessary for agents to perform reliable work.
Redefining the Engineering Role: From Coding to Scaffolding
When humans stop writing code, the primary engineering challenge becomes enabling agents to do useful work by providing the necessary tools, abstractions, and internal structure.
Systems-First Development
Early progress in the experiment was slow because the environment was underspecified. To overcome this, engineers adopted a depth-first approach: breaking large goals into small building blocks, prompting the agent to construct them, and using those blocks to unlock more complex tasks. When failures occurred, the solution was not to "try harder" with prompts, but to identify what capability or tool was missing and make it available to the agent.
Agent-Driven Workflows
Humans interact with the system primarily through prompts. The typical workflow involves:
- An engineer describes a task.
- The agent executes and opens a pull request (PR).
- The agent reviews its own changes locally and requests additional agent reviews.
- The agent iterates based on human or agent feedback until all reviewers are satisfied.
Over time, the team shifted nearly all review efforts to agent-to-agent interactions, with humans reviewing PRs only when necessary.
Increasing Application Legibility for Agents
To prevent human QA from becoming a bottleneck, OpenAI focused on making the application and its telemetry directly legible to Codex agents.
- UI Legibility: By wiring the Chrome DevTools Protocol into the agent runtime and making the app bootable per git worktree, agents can launch instances, reproduce bugs, validate fixes, and reason about UI behavior using DOM snapshots and screenshots.
- Observability Legibility: Agents have access to a local, ephemeral observability stack. They can query logs via LogQL and metrics via PromQL, allowing them to tackle performance-based prompts such as "ensure service startup completes in under 800ms."
Repository Knowledge as the System of Record
Effective agent performance depends on precise context management. OpenAI discovered that monolithic instruction manuals are counterproductive because they crowd out task-specific context and rot quickly.
The Map vs. The Manual
Instead of a giant instruction file, the team uses a short AGENTS.md file (approximately 100 lines) that acts as a table of contents. This map points the agent toward a structured docs/ directory, which serves as the system of record. This approach enables progressive disclosure, where agents start with a small entry point and are taught where to look for deeper information.
Mechanical Enforcement of Knowledge
To prevent documentation drift, the team employs:
- Dedicated linters and CI jobs to validate that the knowledge base is up to date and cross-linked.
- Doc-gardening agents that scan for obsolete documentation and open fix-up PRs to align docs with actual code behavior.
Enforcing Architecture and Taste
To maintain coherence in a million-line, agent-generated codebase, OpenAI enforces strict architectural invariants rather than micromanaging individual implementations.
Rigid Architectural Layers
Each business domain is divided into a fixed set of layers with strictly validated dependency directions: Types $\rightarrow$ Config $\rightarrow$ Repo $\rightarrow$ Service $\rightarrow$ Runtime $\rightarrow$ UI. Cross-cutting concerns (e.g., auth, telemetry) enter only through explicit "Providers." These constraints are enforced mechanically via custom, agent-generated linters.
Encoding "Taste"
Human engineering "taste"—such as naming conventions, structured logging, and file size limits—is encoded into custom lints. When a rule is violated, the linter injects remediation instructions directly into the agent's context. This allows human judgment to be captured once and applied universally across the codebase.
Autonomy and the Problem of Entropy
As the development loop became fully encoded, Codex reached a threshold of end-to-end autonomy. Given a single prompt, an agent can now reproduce a bug, record a video of the failure, implement a fix, validate it by driving the app, record a resolution video, and merge the PR.
Managing "AI Slop"
Full autonomy introduces the risk of the agent replicating suboptimal patterns found elsewhere in the repo. To combat this, OpenAI implemented a "garbage collection" process:
- Golden Principles: Opinionated mechanical rules (e.g., preferring shared utility packages over hand-rolled helpers) are defined in the repo.
- Recurring Cleanup: Background Codex tasks scan for deviations from these principles and open targeted refactoring PRs.
Community Perspectives and Critiques
While the OpenAI team presents this as a leap in productivity, the Hacker News community raised several critical counterpoints:
"What I still can't understand is why is massive amount of code generated is a flex? ... I'd argue you have to optimize for less lines generated as possible while secondary optimization should be readability for humans."
Critics questioned whether the million-line codebase is an example of efficiency or "bloat," suggesting that a human-led approach might have achieved the same result with significantly less code. Others expressed skepticism regarding the lack of transparency, noting that the specific product built was never named, and the repository remains private.
However, some developers reported similar experiences with agentic workflows, noting that the necessity of strict engineering best practices (like type safety and boundary parsing) becomes more critical when agents are the primary authors, as these constraints are the only way to ensure reliability at scale.