repo4agent

Repo4Agent

The repository, redesigned for the agent that works in it.

The Problem

AI agents working in a codebase read the wrong files, miss cross-module side effects, and commit changes before they understand the full constraint space. They weren't designed for it — the codebase was designed for humans.

Repo4Agent is a controlled empirical study: what happens when you redesign a repository for the agent that will work in it, not the human who wrote it?

We ran 80 controlled experiment runs across 10 tasks using claude-haiku-4-5-20251001, iterating on the design until the results stabilized:

On the hardest tasks (hidden cross-module constraints): 0% → 100%.

Agent-native uses more tokens overall — yet the cost per correct implementation is virtually identical, while producing 55% more correct answers.

Why It Works

1. Premature commit is the primary failure mode

Traditional agents read 4–7 files, conclude "that's enough context," and begin editing — typically the wrong files. Agent-native repos open with a mandatory pre-read instruction in AGENT.md, forcing agents to read more files before modifying anything. This alone eliminates the most common failure pattern.

2. Side effects are the #1 unknown unknown

MANIFEST.yaml declares every operation's writes, reads, and downstream effects. Without it, an agent fixing a delete handler won't know it also needs to invalidate sessions. With it, the agent knows — because the manifest says so explicitly.

3. Knowing what the test expects beats knowing what the code does

TEST_CONTRACTS.yaml states the exact assertions for every capability — HTTP status, response shape, side effects, failure cases. Agents that know precisely what they're building for get it right on the first attempt, rather than discovering mismatches after tests fail.

4. Fix instructions must include implementation order

When a bug fix requires creating a method that doesn't yet exist, metadata that says "call deleteByUserId()" causes agents to call a non-existent method. Metadata that says "Step 1: add deleteByUserId() to db.ts — this method does not exist yet" eliminates the failure entirely.

The core insight: Agent-native repos aren't codebases — they're APIs. They have schemas, contracts, and explicit side-effect declarations. Agents don't need to understand code; they need to locate the correct modification point in the fewest tool calls, and know the exact shape of a correct solution before writing a single line.

What Is an Agent-Native Repository?

An agent-native repo adds a 5-file metadata layer without changing any source logic. The API stays the same. The structure changes.

.agent/
  MANIFEST.yaml          ← Every capability: handler, side_effects, known_issues
  INVARIANTS.md          ← Constraints + known bugs with step-by-step fix instructions
  IMPACT_MAP.yaml        ← "Changing X requires also changing Y"
  TEST_CONTRACTS.yaml    ← Exact test assertions: status, body shape, side effects
AGENT.md                 ← Entry point: mandatory pre-read, capability index, route map
src/
  user/
    user.create.handler.ts    ← One file per operation
    user.contract.ts
    user.test.ts
  auth/
    auth.login.handler.ts
    ...

What each file contributes