Harness Engineering: Leveraging Codex in an Agent-First World

Ryan Lopopolo. Published February 11, 2026 on the OpenAI blog. Acknowledgements to Victor Zhu and Zach Brock who contributed to the post, and the entire team that built the product.

The Experiment

Five months (late August 2025 – January 2026), starting from an empty git repository. Three engineers initially, growing to seven. The constraint: zero manually-written lines of code. Every line — application logic, tests, CI configuration, documentation, observability, internal tooling — written by Codex.

Results: on the order of a million lines of code, roughly 1,500 pull requests opened and merged. Average throughput of 3.5 PRs per engineer per day, and throughput increased as the team grew. The product has hundreds of internal users including daily power users, plus external alpha testers. Estimated 10x speedup over hand-writing code.

"The first commit to an empty repository landed in late August 2025. The initial scaffold — repository structure, CI configuration, formatting rules, package manager setup, and application framework — was generated by Codex CLI using GPT‑5, guided by a small set of existing templates. Even the initial AGENTS.md file that directs agents how to work in the repository was itself written by Codex."

"There was no pre-existing human-written code to anchor the system. From the beginning, the repository was shaped by the agent."

Core Philosophy

"Humans steer. Agents execute."

The human role: design environments, specify intent, and build feedback loops that allow Codex agents to do reliable work. The primary job is no longer to write code.

"Throughout the development process, humans never directly contributed any code. This became a core philosophy for the team: no manually-written code."

When something failed, the fix was never "try harder." Engineers asked: "what capability is missing, and how do we make it both legible and enforceable for the agent?"

The Agent Workflow

Engineers describe a task, run the agent, and allow it to open a PR. Codex then: - Reviews its own changes locally - Requests additional specific agent reviews (both local and in cloud) - Responds to any human or agent feedback - Iterates in a loop until all agent reviewers are satisfied

Lopopolo calls this "effectively a Ralph Wiggum Loop." Codex uses standard development tools directly (gh, local scripts, repository-embedded skills). Humans may review PRs but aren't required to — over time, the team pushed almost all review effort to agent-to-agent.

"We regularly see single Codex runs work on a single task for upwards of six hours (often while the humans are sleeping)."

End-to-End Feature Autonomy

The repository crossed a threshold where Codex can drive a full feature from a single prompt: 1. Validate current state of the codebase 2. Reproduce a reported bug 3. Record a video demonstrating the failure 4. Implement a fix 5. Validate the fix by driving the application 6. Record a second video demonstrating the resolution 7. Open a pull request 8. Respond to agent and human feedback 9. Detect and remediate build failures 10. Escalate to a human only when judgment is required 11. Merge the change

"This behavior depends heavily on the specific structure and tooling of this repository and should not be assumed to generalize without similar investment — at least, not yet."

Increasing Application Legibility

As code throughput increased, human QA became the bottleneck. The response: make the application itself legible to Codex.

App bootable per git worktree — Codex can launch and drive one instance per change.

Chrome DevTools Protocol wired into the agent runtime — skills for DOM snapshots, screenshots, and navigation. Codex can reproduce bugs, validate fixes, and reason about UI behavior directly.

Local observability stack per worktree — Logs, metrics, and traces exposed to Codex via ephemeral instances. Agents query logs with LogQL and metrics with PromQL. Prompts like "ensure service startup completes in under 800ms" or "no span in these four critical user journeys exceeds two seconds" become tractable.

Repository Knowledge as System of Record

"Give Codex a map, not a 1,000-page instruction manual."

The team tried the "one big AGENTS.md" approach. It failed: - Context is scarce — a giant file crowds out the task - Too much guidance becomes non-guidance — when everything is "important," nothing is - It rots instantly — agents can't tell what's still true - It's hard to verify — a single blob doesn't lend itself to mechanical checks

The solution: AGENTS.md as a ~100-line table of contents pointing to a structured docs/ directory:

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/      (index.md, core-beliefs.md, ...)
├── exec-plans/       (active/, completed/, tech-debt-tracker.md)
├── generated/        (db-schema.md)
├── product-specs/    (index.md, new-user-onboarding.md, ...)
├── references/       (design-system-reference-llms.txt, ...)
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

This is enforced mechanically — dedicated linters and CI jobs validate the knowledge base is up to date, cross-linked, and structured correctly. A recurring "doc-gardening" agent scans for stale documentation and opens fix-up PRs.

"From the agent's point of view, anything it can't access in-context while running effectively doesn't exist. Knowledge that lives in Google Docs, chat threads, or people's heads are not accessible to the system."

Enforcing Architecture and Taste

"By enforcing invariants, not micromanaging implementations, we let agents ship fast without undermining the foundation."

The application was built around a rigid architectural model. Each business domain is divided into a fixed set of layers with strictly validated dependency directions:

Types → Config → Repo → Service → Runtime → UI

Cross-cutting concerns (auth, connectors, telemetry, feature flags) enter through a single explicit interface: Providers. Anything else is disallowed and enforced mechanically via custom linters and structural tests — themselves written by Codex.

"This is the kind of architecture you usually postpone until you have hundreds of engineers. With coding agents, it's an early prerequisite: the constraints are what allows speed without decay or architectural drift."

Example invariants: structured logging, naming conventions, file size limits, platform-specific reliability requirements. Error messages from custom lints are written to inject remediation instructions directly into agent context.

"In a human-first workflow, these rules might feel pedantic or constraining. With agents, they become multipliers: once encoded, they apply everywhere at once."

The team is explicit about where constraints matter and where they don't — enforce boundaries centrally, allow autonomy locally. The resulting code doesn't always match human stylistic preferences, and that's okay. As long as it's correct, maintainable, and legible to future agent runs, it meets the bar.

Concrete example: Rather than pulling in a generic p-limit-style package, the team implemented their own map-with-concurrency helper — tightly integrated with OpenTelemetry instrumentation, 100% test coverage, behaves exactly as the runtime expects.

"We require Codex to parse data shapes at the boundary, but are not prescriptive on how that happens (the model seems to like Zod, but we didn't specify that specific library)."

Throughput Changes Merge Philosophy

The repository operates with minimal blocking merge gates. PRs are short-lived. Test flakes are addressed with follow-up runs rather than blocking progress. In a system where agent throughput far exceeds human attention, corrections are cheap and waiting is expensive.

"This would be irresponsible in a low-throughput environment. Here, it's often the right tradeoff."

Entropy and Garbage Collection

Agent autonomy introduces drift — Codex replicates patterns that already exist in the repository, even suboptimal ones.

Initially the team spent every Friday (20% of the week) cleaning up "AI slop." That didn't scale.

The solution: encode "golden principles" directly into the repository and build a recurring cleanup process. Examples: - Prefer shared utility packages over hand-rolled helpers to keep invariants centralized - Don't probe data "YOLO-style" — validate boundaries or rely on typed SDKs

On a regular cadence, background Codex tasks scan for deviations, update quality grades, and open targeted refactoring PRs. Most can be reviewed in under a minute and automerged.

"This functions like garbage collection. Technical debt is like a high-interest loan: it's almost always better to pay it down continuously in small increments than to let it compound and tackle it in painful bursts."

What They're Still Learning

The strategy worked through internal launch and adoption at OpenAI. What they don't yet know: - How architectural coherence evolves over years in a fully agent-generated system - Where human judgment adds the most leverage and how to encode it so it compounds - How the system will evolve as models become more capable

"What's become clear: building software still demands discipline, but the discipline shows up more in the scaffolding rather than the code."