Repo-Readable Systems
Use AGENTS.md, docs, observability, executable SSOT, MCP, skills, hooks, and plugins as one work environment.
Key takeaways
- The first ingredient of a harness is the work environment, not the model; the repository and connected tools are the center.
- OpenAI's view: AGENTS.md is a short table of contents (where to start, what to trust, how to verify), with detail in structured docs/.
- Toss's view: docs decay unless connected to execution, so rules must become commands, skills, hooks, and workflows.
- Separate global, domain, and local layers so context is not mixed into one giant file or disconnected.
- Repo-readable systems now include runtime primitives (MCP, skills, sandbox, hooks, Secure MCP Tunnel, plugins) that teams must govern like docs.
The first ingredient of a harness is not the model. It is the work environment. OpenAI and Toss both point strongly in this direction.
Why the Repository Is the Center
Agents work best inside the information and tools connected to the repository. The goal is not to dump more text into the prompt. The goal is to make the right information easy to find and connected to execution and verification.
OpenAI View: AGENTS Is a TOC, Not an Encyclopedia
The useful pattern is clear:
AGENTS.mdshould be a short entry point.- Details should live in
docs/and design documents. - The structure should be searchable and navigable by agents.
- Browser, logs, and metrics should be connected to the work loop.
A good AGENTS.md does not contain every answer. It says where to start, what to trust, and how to verify.
Toss View: Docs Are Not Enough
Toss emphasizes that documents decay unless they are connected to execution. A harness must become workflow, plugin, command, template, or script.
- Rules that live only in docs drift away from practice.
- Team routines should exist as commands, skills, hooks, and workflows.
- The system should reduce what people have to remember.
- Team productivity rises when good habits become the default path.
Global / Domain / Local Layers
| Layer | Contains | Example |
|---|---|---|
| Global | Company-wide standards | Security policy, code style, required verification |
| Domain | Product or team rules | Payment invariants, mobile QA, customer data handling |
| Local | Current task context | Issue link, experiment goal, branch strategy |
Harnesses fail when these layers are mixed into one giant file or disconnected from each other.
Minimal Repo Structure
Load-Bearing Documents
| Artifact | Role | Failure when missing |
|---|---|---|
AGENTS.md | Entry point and priority map | High search cost and unstable starting points |
| Architecture docs | Structure and ownership boundaries | Agent guesses implicit architecture |
| Invariants | Rules that must not be broken | Plausible but dangerous changes increase |
| Release gates | Done criteria and approval conditions | Self-evaluation becomes too optimistic |
| Runbook / updates | Operations and change history | Stale rules accumulate |
Harness Primitives as Infrastructure
OpenAI Agents SDK and Codex updates show that repo-readable systems are no longer just documentation patterns. They are becoming a standardized agent runtime surface.
| Primitive | Role in the harness |
|---|---|
| MCP | Connect internal systems, SaaS, data sources, browsers, and tools through a consistent surface |
| Skills | Load large knowledge bundles only when needed |
AGENTS.md | Short project entry point and priority guide |
shell / apply_patch | Execute commands and file edits in a reviewable way |
| Sandbox / Manifest | Make inputs, outputs, dependencies, and execution boundaries explicit |
| Hooks | Automate prompt checks, validation, logging, and memory creation |
| Secure MCP Tunnel | Connect private or on-prem MCP without public internet exposure |
| Plugins | Distribute provider setup, API key connection, troubleshooting, and domain workflows |
The practical meaning is that teams must design more than where docs live. They must decide which tools become MCP, which skills load lazily, which work belongs in a sandbox, which hooks enforce validation, and which plugins standardize team setup.
Principles to Borrow
Conclusion
A good harness is less about talking cleverly to the model and more about placing the repository and tools cleverly around the model.