Harness engineering: How small pods move faster

TL;DR

OpenAI’s Harness Engineering post describes how to make coding agents more reliable by improving the repository around them.

Work that previously took a team of five to eight people several months can now be done by a pod of one to three people in a week or a few weeks. The same approach gives non-engineers a direct path to production changes.

• Keep AGENTS.md short and use it as an index into deeper documentation.
• Put architecture, product, design, and quality knowledge in versioned repository files.
• Define the work upfront. Use a checked-in execution plan for any large change or feature, especially work that spans repositories.
• List one simple project CLI in AGENTS.md and provide fast feedback from tests, lints, and CI.
• Use the strongest model to implement, self-review, smoke test, capture screenshots, and find missing tests before human review.
• Refactor regularly for modular, agent-legible code, then encode recurring rules in AGENTS.md or mechanical checks.

Harness engineering is not only for small pods. Its benefits compound as more people and agents work in the same codebase. This post focuses on one outcome: a small cross-functional pod can move unusually fast, including enabling designers and other non-engineers to ship production changes within the same architecture, tests, and review process.

Work that previously took a team of five to eight people several months can now be completed by a small pod of one to three experienced people in a week or a few weeks. The work can also be higher quality when the people steering agents bring strong product taste and technical judgment.

At work, a designer and I have spent the past few months building a reporting platform. Agents help us work across frontend, backend, databases, APIs, and multiple repositories. The designer can make production changes directly instead of handing every request to an engineer.

Previously, we might merge five pull requests in a week. Now we often merge about five per person per day. Some are small and some are not. The count is not the point. What matters is that a two-person pod can ship, get customer feedback, and iterate quickly.

That workflow depends on harness engineering: the repository needs to give agents context, constraints, tools, and feedback.

Context is only the beginning

OpenAI describes harness engineering as building the environment around coding agents so humans can steer while agents execute.

I previously wrote that context is more important than prompting. I still believe that. But context is only one part of a useful harness:

• Context tells the agent how the product and codebase work.
• Boundaries tell it which decisions are already made and what must remain true.
• Tools give it reliable ways to inspect, change, and operate the system.
• Feedback loops let it prove the work is correct.

If an agent repeatedly gets something wrong, asking it to try harder is rarely the durable fix. Ask what context, constraint, tool, or feedback signal was missing. Then add that capability to the repository so every future agent benefits.

The files in a harness

There is no required file structure for harness engineering. The example in OpenAI’s article uses a structure like this:

• AGENTS.md — the index. This stays short. It tells an agent where to look first, how to run the project, which commands to use, and which invariants cannot be broken. It routes to deeper documentation instead of becoming a giant instruction manual.

• ARCHITECTURE.md — the stable system map. It explains the major entry points, domains, services, data flows, and boundaries. It is a codemap, not an implementation guide, and should change much less often than the code beneath it.

• docs/design-docs/ and docs/product-specs/ — design history and product intent. Indexes make the documents discoverable. Core beliefs, decisions, and specifications give agents the context behind the current code.

• docs/PLANS.md and docs/exec-plans/ — planning and working memory. PLANS.md defines how to write execution plans. Active plans track progress and decisions, completed plans preserve history, and a tech-debt tracker keeps known follow-up work visible.

• docs/generated/db-schema.md — generated context. Important system state is made legible without asking an agent to reconstruct it from migrations or memory.

• docs/references/ — external references in agent-readable form. Framework, library, and design-system references stay close to the code that depends on them.

• docs/DESIGN.md, docs/FRONTEND.md, docs/PRODUCT_SENSE.md, docs/QUALITY_SCORE.md, docs/RELIABILITY.md, and docs/SECURITY.md — durable standards. These capture product judgment, implementation patterns, quality gaps, and operational boundaries.

I would add one more element:

• A project CLI — one command surface. Use a Makefile, a Justfile, or a small custom CLI to hide the details of how the project works. In AGENTS.md, list the small set of commands the agent should use to set up the project, build the database, run tests, run the full lint suite, and perform other common tasks. Keep lower-level commands out of the instructions so the agent does not waste context on tooling or stumble into the wrong command.

This is progressive disclosure. AGENTS.md gives the map. The agent follows the relevant links for the task, then reads the code. It gets enough context without loading the entire company handbook into every session.

How to build a harness in practice

You do not need all of these files on day one. Start with the places where your agents and humans already lose time.

1. Give the repository a front door

Create a short AGENTS.md with:

• The project CLI commands to set up, run, lint, test, and build the database
• A link to the architecture map
• The few rules that really are universal
• Links to deeper product, design, testing, security, and operations docs

Treat it as a table of contents. Long instructions become stale and crowd out the information an agent needs for the current task.

2. Make the architecture legible

Write the top-level system map in ARCHITECTURE.md. Show the major domains, entry points, data flow, and boundaries that experienced engineers carry in their heads. Link forward from the architecture map to focused domain docs, design docs, product specs, and canonical examples.

Keep the map short and stable. Detailed behavior belongs near the code or in the documents it links to.

3. Make execution plans first-class

Before implementation begins, define the outcome, scope, constraints, non-goals, and validation. A lightweight plan is enough for a small change. For larger work, I always create an execution plan with the context, decisions, steps, validation, and recovery path. Keep it updated while the work changes so another person or agent can resume from the repository alone.

The implementation might span frontend, backend, databases, APIs, and multiple repositories. I still keep one canonical execution plan in the primary repository. It coordinates the sequence, cross-repository contracts, progress, and validation as one body of work.

Plans are also where discoveries begin. I use a simple promotion path:

• Relevant only to this change: keep it in the execution plan.
• Useful across future work: add it to the relevant product, design, or architecture document.
• Always true: link it from AGENTS.md.
• Mechanically enforceable: encode it in a test or tool.

That loop turns each mistake and review comment into a better environment for the next change.

4. Make the rules executable

Documentation explains intent. Tests and tools enforce what must remain true. If a rule can be checked by a linter, test, schema validation, or CI job, enforce it there instead of asking the agent to remember it.

This applies to architecture and design standards too. Boundary tests, component previews, screenshots, accessibility checks, and canonical examples make those expectations concrete.

5. Use the strongest model through the full loop

For important work, I use the smartest model available at its highest reasoning setting to write the code. It is worth waiting. Optimizing for the fastest response is a false economy if a more capable model can understand the system, find edge cases, and avoid hours of rework.

Before a human looks at the change, I ask the agent to:

1. Review the complete diff against the plan, architecture, and requirements.
2. Smoke test the running change, not just the code.
3. Capture screenshots when the result is visible in the UI.
4. Find and add missing simple tests that would increase confidence.
5. Review the work again for regressions, unnecessary complexity, and missed requirements.

For substantial changes, I run this review loop more than once. Human review begins with a more complete result and evidence that it works.

6. Make changes reviewable and observable

Do not force every pull request to be tiny. Split work when the pieces can stand on their own, but some coherent changes are naturally substantial. What matters is a defined scope, a plan that explains the change, strong automated validation, and a safe recovery path.

Give agents access to the application, logs, errors, tests, and other signals they need to inspect the result instead of stopping at “the code compiles.”

Then get the change in front of customers. A fast coding loop matters most when it is attached to an equally fast learning loop.

7. Refactor before complexity compounds

When a small pod is moving quickly, schedule a refactoring pass every week or two. Ask the strongest model to make the code more modular, maintainable, and as simple as possible without changing behavior. A good test suite makes this much safer.

Design the codebase for agent legibility as well as human readability. Files that are thousands of lines long waste context and make it harder for an agent to find boundaries or change one part safely. Smaller, clearly named modules let the agent load the relevant code and reason about it with less confusion.

Feed recurring findings back into the harness. For example, if most TypeScript files should stay under 500 lines, record that rule in AGENTS.md, ask review agents to flag files that grow past it, and enforce it mechanically when practical. Use the same cleanup pass to remove stale instructions, consolidate duplicate patterns, and archive completed plans.

Without this maintenance, agents reproduce the repository’s accidental complexity. With it, each round of work makes the next round easier.

Why small pods move faster

A small pod still needs architecture, implementation, QA, operations, product management, and documentation. It may no longer need a different person for every capability.

A good harness captures the best parts of that institutional knowledge in the repository. It gives each agent a shared map, clear boundaries, specialized workflows, and immediate feedback. The humans can spend more time choosing the right problems, reviewing judgment calls, talking with customers, and improving the system around the work.

This makes seniority, taste, and judgment more important, not less. A designer with strong product taste can implement a change directly, validate it, and bring it to an engineer for review instead of only asking for the change to be made. That shorter path from idea to working software is a major unlock.

That is how a pod of one to three people can move faster than a much larger team without lowering the quality bar. The models help, but the compounding advantage comes from the harness.