Make the repository the system of record: give agents a map: Practical Field Guide

On this page

01Working definition
02Field situation
03Worked example
04Build it, with checkpoints
05Operating context
06Hands-on lab
07Failure clinic
08Production boundary
09Sources and claim limits

Learning objectives

Decide which product, architecture, quality, security, and execution knowledge belongs in the repository
Use AGENTS.md as a short map into deeper owned sources instead of a monolithic manual
Assign freshness, authority, and mechanical checks to durable documentation
Test whether a fresh agent can locate the right rule without loading irrelevant context

Before you start

• The locked Module 01 task contract and the Release Desk domain boundaries
• Permission to reorganize course documentation without changing application behavior

Working definition

Repository as system of record

A repository system of record is the versioned set of documents, schemas, plans, tests, and code that an agent can discover while working. The entry instruction file acts as a directory page: it identifies mandatory startup behavior, points to authoritative sources, and explains where decisions belong. It does not duplicate every rule or replace checks that can be executed mechanically.

A coding agent cannot reliably apply a decision that exists only in a meeting, private chat, or one engineer's memory. Copying all of that knowledge into a giant instruction file creates another failure. The task, relevant code, and current evidence compete with stale guidance for the same context window.

Progressive disclosure keeps the starting surface small. The agent learns where to look for architecture, product, security, design, and active plans. Ownership and freshness make contradictions visible. High-risk invariants later move from prose into structural tests so the repository can correct an agent with an actionable error.

Field situation

Release Desk knowledge recovery

The missing decisions and contradictory pages are deliberately seeded course conditions.

Owner: A repository steward making the codebase understandable to a new engineer and a fresh coding-agent session.
Decision: Which knowledge is durable and agent-relevant, where should its authority live, and what can be removed as duplicate or stale?
Starting state: Setup notes are in a private issue, state rules appear in two Markdown files, the active task lives in chat, and a 420-line instruction file repeats lint rules without naming their executable source.
Expected outcome: A fresh reader answers five repository questions through short, predictable paths and reports no conflicting normative source.

Constraints

• AGENTS.md should remain a concise navigation and startup surface rather than a complete handbook
• Every normative topic has one source of truth, owner, review date, and path from the entry map
• This module changes documentation structure only; architecture enforcement arrives in Module 06

Worked example

Replacing a 420-line instruction file with a 78-line map

Evidence status: Named synthetic scenario

Release Desk's original instruction file contained setup commands, product background, styling preferences, copied lint rules, old incident notes, and an abandoned deployment checklist. The agent often followed a stale port command and missed the current state schema buried near the end.

The steward kept startup, mandatory preflight, task scope, verification order, and links in the entry file. Product behavior moved to `docs/product/`, architecture to `docs/architecture/`, active work to `docs/plans/active/`, and generated references to a clearly labeled directory. Duplicated lint prose became a link to the executable rule source.

A cold navigation test found all five answers with six file opens instead of seventeen. The result did not prove better feature quality by itself; it established that required knowledge was discoverable and contradictions had an owner.

Limits

Line count is a local outcome, not a universal target. A different repository may need a smaller entry file or local instruction files in nested domains.

Method

Build it, with checkpoints

Field situation

Which knowledge is durable and agent-relevant, where should its authority live, and what can be removed as duplicate or stale?

01Inventory knowledge and authority
02Build the directory page
03Add ownership and freshness

Acceptance checks

The repository presents a small stable entry point and deeper sources that can evolve independently. The navigation receipt shows discoverability without claiming that documentation alone enforces behavior.

Why this visualA repository knowledge tree shows progressive disclosure, authority, and ownership more clearly than another list of instruction-file tips.

01
Inventory knowledge and authority
Find every source that affects setup, product behavior, architecture, security, design, planning, and verification. Mark normative status, owner, freshness, executable source, duplicates, and knowledge that should be deleted rather than moved.
CHECKPOINT · Each required topic has one proposed authority and every conflict has an explicit resolution owner.
02
Build the directory page
Write AGENTS.md with startup preflight, task-scope discipline, verification order, and links to deeper indexes. Keep explanations at the level needed to choose the next source. Move topic detail into owned, named locations.
CHECKPOINT · The entry file points to every normative domain without copying its full contents or executable rules.
03
Add ownership and freshness
For each durable page, record purpose, authority, owner, last verified date, and how to check it against system behavior. Label generated files and past decision records so readers do not mistake them for current policy.
CHECKPOINT · A reader can tell who resolves drift and which artifact wins when two statements disagree.
04
Run the cold navigation test
Start a fresh session and ask the five repository questions without path hints. Capture files opened, answers, uncertainty, and conflicts. Tune links or ownership, then repeat once with another fresh context.
CHECKPOINT · Both runs find the authoritative answers, perform the correct startup preflight, and report zero unresolved conflict.

Operating context

Beyond the demo

Choose authority before structure

Inventory decisions from code, tests, existing docs, issue threads, chat, and local setup knowledge. For each topic, select one authoritative artifact and one owner. A domain transition can live in a state schema, an architecture dependency in a structural test, and an unsettled choice in an active plan. Do not create a new Markdown page when an executable source already states the truth better.

Mark generated references and field notes differently from normative rules. A generated database schema may be useful context but should be regenerated rather than hand-edited. A past decision record explains why a choice was made; it does not silently override a newer active contract.

Test navigation with a cold reader

Give a fresh agent five questions: how to start the app, where review transitions are defined, which imports are forbidden, what plan is active, and what counts as verified. Record which files it opens and where it becomes uncertain. The goal is direct navigation, not maximum document recall.

If the agent reads ten unrelated pages before finding one rule, improve the map or place local guidance closer to the affected directory. If it finds conflicting sources, remove duplication and make one page point to the owner. Keep the entry file stable enough to cache as a mental map while deeper artifacts evolve independently.

Hands-on lab

Build and cold-test the repository knowledge map

Inventory the supplied Release Desk notes, resolve duplicate authority, build the short entry map, and run a cold navigation test without giving the reviewer a list of target file paths.

Prepare

• Create a branch that changes documentation and indexes only, with application behavior held constant
• List current knowledge sources including chat-derived fixture notes, then mark their authority and freshness

Deliverable

A concise AGENTS.md map, owned documentation index, resolved authority inventory, cold-navigation transcript, and a receipt reporting path length and conflicts.

Starter kit: Repository knowledge inventory

CSV

topic,current_location,normative,owner,freshness,mechanical_source,target_location,action
startup,fixture/private-issue.md,yes,platform,stale,,AGENTS.md,move
review-state,docs/status-notes.md,yes,product,conflict,src/domain/review.ts,docs/product/review-state.md,reconcile
architecture,README.md,yes,engineering,unknown,,docs/architecture/index.md,extract
active-task,chat-fixture.txt,yes,task-owner,current,,docs/plans/active/request-changes.md,move

Downloadable artifacts

Knowledge ownership inventory

repository-knowledge.csv · CSV

An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.

Run receipt template

he-02-receipt.json · JSON

A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.

Acceptance command

npm run harness:knowledge -- --entry AGENTS.md --inventory repository-knowledge.csv

Expected receipt

PASS he-02 repository-map
questions=5 answersFound=5 conflicts=0
entry=map normativeOwners=complete

Expected result

Carry forward

All later harness files must be reachable from the knowledge map. Module 06 will convert high-risk prose rules into executable checks rather than expanding the entry file.

Acceptance checks

01Startup, product, architecture, security, design, plans, and verification each have one owned source of truth
02AGENTS.md functions as a map and contains no copied long-form handbook or duplicate lint specification
03Generated, historical, active, and normative artifacts are visibly distinguished
04Two cold navigation runs find five authoritative answers with no unresolved contradiction

What breaks

Failure clinic

F1The entry file becomes longer after every incident and agents skip important guidance.

Inspect: Group lines by navigation, normative detail, historical note, generated reference, and executable rule duplication.
Likely cause: AGENTS.md was treated as the only storage location instead of a directory into owned sources.
Repair: Keep startup and routing in the entry file, move detail to topic owners, and delete stale duplication.
Prevent next time: Set an entry-file purpose check and require new guidance to name its durable owner.

F2A fresh agent finds two different review-state rules and chooses the nearer file.

Inspect: Search all prose, schemas, tests, and code comments for the conflicting transition terms.
Likely cause: The knowledge inventory recorded locations but never resolved normative authority.
Repair: Choose the executable state definition as truth, reconcile one explanatory page, and replace copies with links.
Prevent next time: Give every normative topic one owner and run a recurring conflict scan.

F3Documentation appears current while the application behaves differently.

Inspect: Compare last-verified dates, generated references, contract versions, and the current acceptance suite.
Likely cause: Freshness was declared by prose review rather than checked against system behavior.
Repair: Add a verification method or generate the reference from source, then mark unsupported claims stale.
Prevent next time: Require owners and executable freshness checks for high-consequence documentation.

Beyond the demo

Production boundary

01Repository knowledge needed for work is versioned and discoverable without private chat or personal memory
02Normative topics have one authority, one owner, a freshness signal, and a path from the entry map
03AGENTS.md remains a startup and navigation surface rather than a duplicated encyclopedia
04Generated references, active plans, completed decisions, and historical notes have distinct status
05High-risk invariants point to executable checks or a planned enforcement owner
06Cold navigation tests use fresh contexts and preserve uncertainty instead of coaching the reader

Evidence status

Sources and claim limits

Sources support the named claims; they do not guarantee the same result in another system.

[1]
Harness engineering: leveraging Codex in an agent-first world
OpenAI · Public case · 2026-08-26
repository knowledge · agent legibility · mechanical enforcement · entropy management
[2]
Harness Engineering learning guide
deusyu · Public case · 2026-08-26
repository as record · mechanical rules · agent readability · continuous cleanup
[3]
Effective harnesses for long-running agents
Anthropic · Published research · 2026-08-26
initializer pattern · feature ledger · session handoff · end-to-end verification
[4]
Learn Harness Engineering
Walking Labs · Public case · 2026-08-26
project-based sequence · five harness subsystems · loop engineering · graph engineering
[5]
Andrej Karpathy's AI Engineering Playbook
AI Builder Club · Public case · 2026-08-26
Software 3.0 framing · spec-diff-eval practice · parallel session framing · repository instructions