Harness Engineering as a framework for Agentic Knowledge Systems / Agentic Repositories

TL;DR Harness Engineering gives you agent speed without agent chaos by combining map-first context, layered boundaries, and file-based execution memory.

Most “AI-ready repos” are still just repos: a pile of docs, a few conventions, and a hope that the next person (or agent) will “figure it out.”

That’s not a great substrate for agentic systems.

Harness Engineering is a framework for building Agentic Knowledge Systems (aka Agentic Repositories)—repositories designed so an AI agent (and humans) can reliably navigate, execute, and resume work without chaos.

The shift is simple:

Don’t treat the repo as storage. Treat the repo as a control plane for execution.

The Big Idea

Harness Engineering turns an AI-assisted repo from “a pile of docs” into a navigable operating system for execution.

Instead of one giant instruction blob, it gives the agent:

• A short map (AGENTS.md) A routing layer: mission, where to look next, and how to operate.
• Clear architectural boundaries (ARCHITECTURE.md) A shared model of how the repo is organized—so changes land in the right layer.
• A structured system of record (docs/) Durable knowledge that can be referenced without re-deriving it from chat history.
• Explicit plan/state tracking (docs/exec-plans/) File-based execution memory that persists decisions, progress, and validation.

The result: better focus, less hallucination, and much more repeatable output.

The Core Principle: Give Codex a Map, Not a Manual

When building an autonomous software engineering harness, one of the most critical foundational lessons is how to manage an AI agent's context. Initial attempts at agent-first engineering often rely on a single, massive instructions file (the "1,000-page manual" approach). This methodology predictably fails.

To maximize agent legibility and architectural consistency, the repository must be structured to provide a lightweight navigational map that encourages progressive disclosure.

Why the "One Big File" Approach Fails

Attempting to cram all rules, architectural guidelines, and project context into a single monolithic file breaks down in several predictable ways:

• Context is a Scarce Resource: A massive instruction file crowds out the actual task, the active codebase, and the relevant documentation within the LLM's context window. This causes the agent to either miss key constraints entirely or start optimizing for the wrong ones.
• Too Much Guidance Becomes Non-Guidance: When an agent is told that every single rule in a massive document is "important," nothing is prioritized. As a result, agents end up pattern-matching locally instead of navigating the codebase intentionally.
• Instant Context Rot: A monolithic manual quickly turns into a "graveyard of stale rules". Because human engineers inevitably stop maintaining such a massive document, agents can no longer determine which instructions are still true, and the file quietly becomes an attractive nuisance that generates hallucinations.
• Lack of Verifiability: A single giant blob of text cannot be easily subjected to mechanical checks for coverage, freshness, ownership, or cross-links. Without deterministic Continuous Integration (CI) validations, architectural drift is inevitable.

The Solution: The Map and Progressive Disclosure

Instead of treating the root AGENTS.md file as an encyclopedia, it must be treated strictly as a table of contents.

1. The 100-Line Map

The root AGENTS.md file should be extremely brief (roughly 100 lines). It is injected into the agent's context at the start of a session and serves purely to provide pointers to deeper sources of truth located elsewhere in the repository.

2. Progressive Disclosure

By keeping the initial entry point small and stable, the harness teaches the agent where to look next rather than overwhelming it upfront. The agent can dynamically pull in only the specific documentation it needs for its current localized task.

3. Distributed System of Record

The actual, detailed knowledge base of the repository should be distributed inside a structured docs/ directory, which acts as the true system of record. Active execution plans, completed objectives, and technical debt trackers must be heavily versioned and co-located within this directory. This allows agents to operate autonomously across multiple sessions without relying on fragile, external conversational memory.

4. Mechanical Validation

Because the knowledge base is distributed across smaller, specific files (like ARCHITECTURE.md, SECURITY.md, or specific files in the docs/ folder), the harness can deploy dedicated linters and CI jobs to mechanically validate that the agent's map is up to date, properly cross-linked, and structured correctly.

Summary: By shifting from a monolithic instruction manual to a dynamic, navigable map, you allow the agent to traverse the codebase deliberately. This minimizes context rot and ensures high-velocity code generation without sacrificing the architectural integrity of the system.