Repository Knowledge as the System of Record

Imagine hiring a brilliant new junior developer. On their first day, you drop a massive, 1,000-page instruction manual on their desk containing every architectural decision, execution plan, and coding guideline your company has ever produced. You then demand they memorize it before writing a single line of code. What would happen? They would be overwhelmed, confused, and likely misapply the rules. When building AI harnesses, we often make this exact mistake with our autonomous agents.

In this chapter, we will learn how to shift our mindset. Instead of stuffing every piece of context into the agent’s system prompt, we will transform your project repository into the single source of truth. By doing so, your agent can navigate the codebase like a map, fetching what it needs, exactly when it needs it.

The Pitfall of the ‘Thick Manual’

When developers first start building long-running agents, the instinct is to provide maximum context. They write enormous system prompts detailing every API endpoint, database schema, and design pattern. However, this approach introduces severe side effects:

Attention Degradation: Even with massive context windows (like 100k+ tokens), LLMs suffer from ‘lost in the middle’ syndrome. They may forget or hallucinate instructions buried deep within a giant prompt.
Cost and Latency: Sending a massive prompt with every single API call to the LLM drastically increases token costs and slows down the agent’s response time.
Stale Context: If the agent modifies the system, a static system prompt quickly becomes outdated. The AI is suddenly operating on a ghost map.

The Principle of Progressive Disclosure

To solve this, we rely on a UX design concept called Progressive Disclosure. In software interfaces, progressive disclosure sequences information and actions across several screens to reduce user overwhelm. For AI agents, it means we give the AI a high-level map and the tools to look up granular details only when the task requires them.

Instead of saying, ‘Here is the entire database schema,’ we say, ‘You are working on a project. The database schemas are located in the /docs/schemas directory. Read the relevant files before writing database queries.’ The repository itself becomes the dynamic, living brain of the operation.

Structuring the Repository for Agentic Discovery

To make progressive disclosure work, your repository must be highly organized, predictable, and modular. It should contain dedicated files that outline your design documents, execution plans, and core architectural beliefs. Let’s look at how a harness-optimized repository might be structured:

my-agent-project/
├── .harness/
│   ├── core_beliefs.md       # Non-negotiable rules (e.g., "Always use async/await")
│   ├── execution_plan.md     # Current sprint, what is done, what is next
│   └── agent_journal.md      # A scratchpad for the agent to leave notes for its future self
├── docs/
│   ├── architecture_index.md # The "Map": points to specific architectural docs
│   ├── auth_flow.md          # Granular detail on authentication
│   └── database_schema.md    # Granular detail on the database
├── src/
│   └── ...                   # Application code
└── README.md                 # The Entry Point

Let us break down these core components:

Core Architectural Beliefs: A small, highly condensed file that enforces your ‘developer taste’. It dictates the non-negotiable rules of the codebase.
Execution Plans: This file tracks the state of the project. When a new agent session starts, it reads this file to understand ‘where are we?’ and ‘what is the immediate next step?’
Design Documents: Modular files (like auth_flow.md) that contain deep technical context. The agent only reads these if its current task explicitly involves that system.

Navigating the Codebase Like a Map

For the agent to treat the repository as a System of Record, it needs navigational tools and entry points. You must provide the agent with file-reading and directory-listing capabilities (e.g., via specialized tools in your harness). The system prompt then becomes a lightweight router.

Here is an example of what an effective, lightweight agent prompt looks like under this architecture:

// Example: Lightweight System Prompt
You are an autonomous software engineer.
Your primary source of truth is the local repository.

Instructions:
1. Start by reading the README.md and .harness/execution_plan.md to understand your current goal.
2. Before modifying any system, look up its documentation in the /docs folder.
3. Do not guess schemas or APIs. Use your `search_repo` and `read_file` tools to investigate the current state of the codebase.
4. When you finish a task, update the .harness/execution_plan.md to reflect your progress.

Comparing Approaches

Let’s summarize the differences between the legacy approach and the AI Harness engineering approach:

Aspect	System Prompt Heavy (Legacy)	Repository as System of Record (Harness)
Context Location	Stuffed into the LLM system prompt	Stored in modular files in the codebase
Context Size	Massive, approaching token limits	Tiny initial prompt, context fetched on demand
Risk of Hallucination	High (lost in the middle)	Low (reads specific files immediately before acting)
State Management	Relies on LLM conversation memory	Saved directly to disk (e.g., execution_plan.md)
Scalability	Breaks down as the project grows	Scales infinitely with the repository

By moving your logic, state, and rules out of the LLM’s ephemeral memory and into the cold, hard file system, you create an environment where agents can operate reliably over days, weeks, or even months without losing their way.