OpenAI - Harness Engineering

OpenAI engineer Ryan Lopopolo writes in Harness engineering: leveraging Codex in an agent-first world on how to effectively use coding tools by managing context.

Ryan describes the importance of capturing all technical documentation in the repo in a way that agents can consume in an incremental fashion:

Context management is one of the biggest challenges in making agents effective at large and complex tasks. One of the earliest lessons we learned was simple: give Codex a map, not a 1,000-page instruction manual. We tried the “one big AGENTS.md” approach. It failed in predictable ways: […] So instead of treating AGENTS.md as the encyclopedia, we treat it as the table of contents. The repository’s knowledge base lives in a structured docs/ directory treated as the system of record. A short AGENTS.md (roughly 100 lines) is injected into context and serves primarily as a map, with pointers to deeper sources of truth elsewhere.

He also notes that good engineering practices are the core of maintainable code:

Documentation alone doesn’t keep a fully agent-generated codebase coherent. By enforcing invariants, not micromanaging implementations, we let agents ship fast without undermining the foundation. 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. In practice, we enforce these rules with custom linters and structural tests, plus a small set of “taste invariants.” […] In a human-first workflow, these rules might feel pedantic or constraining. With agents, they become multipliers: once encoded, they apply everywhere at once.

He concludes:

Our most difficult challenges now center on designing environments, feedback loops, and control systems that help agents accomplish our goal: build and maintain complex, reliable software at scale.

— via one of Rands Leadership Slack’s extremely active AI channels