Lecture 03

Making the repository the single source of truth

For an agent, project knowledge outside the repository does not exist. The repo must become the map, spec, state, and handoff.

Notes from Learn Harness Engineering - Lecture 03

knowledge_visibilityrepo as spec

SlackConfluenceJiraEngineers' heads

Write into repo files: AGENTS.md / ARCHITECTURE.md / PROGRESS.md

Repository filesFresh session readsAgent can act

The agent only sees three inputs.

System prompts and task descriptions, repository file contents, and tool execution output. Slack history, Confluence pages, Jira context, and hallway decisions are invisible unless they are written into the repo.

Near code

API constraints belong next to API code, not buried in a global archive.

Entry file

AGENTS.md should answer what this is, how to run it, and how to verify it.

Minimal complete

Keep only decision-useful knowledge, but answer every fresh-session question.

Updated with code

Docs decay unless knowledge updates are tied to implementation changes.

Run the fresh session test.

Open a new session with only repository contents. If it cannot answer these five questions, your map has blank spots and the agent must guess.

What is this system?AGENTS.md / README

How is it organized?ARCHITECTURE.md

How do I run it?Makefile / scripts

How do I verify it?test / lint / check

Where are we now?PROGRESS.md / feature list

Core concepts

A repository becomes useful to agents when it lowers discovery cost and survives session boundaries.

Visibility gapProject knowledge outside the repo. The larger the gap, the higher the failure rate.

System of recordThe repo is authoritative for decisions, constraints, execution state, and verification standards.

Fresh session testThe five-question test for whether a new agent can start work without human context.

Discovery costContext budget burned to find one key fact. Hidden knowledge leaves less budget for work.

Knowledge decayStale docs are worse than missing docs because they confidently send the agent the wrong way.

Draw the map in the repo.

A 50-line module-local architecture file beats a 500-page external document the agent cannot see or trust.

project/
├── AGENTS.md       # overview, commands, hard constraints
├── src/
│   ├── api/
│   │   └── ARCHITECTURE.md
│   └── db/
│       └── CONSTRAINTS.md
├── PROGRESS.md     # done / active / blocked
└── Makefile        # setup, test, lint, check

Manage agent state with ACID thinking.

The database analogy gives a practical standard for cross-session reliability.

Atomicity

One logical operation becomes one commit; half-done work rolls back or stays uncommitted.

Consistency

Tests and lint define consistent state; inconsistent states do not get committed.

Isolation

Concurrent agents avoid racing through branches or separated progress files.

Durability

Knowledge that must survive sessions lives in git-tracked files.

Before

A 30-microservice e-commerce platform kept architecture decisions in Confluence, Slack, senior engineers' heads, and scattered comments. After agents arrived, 70% of tasks required human intervention.

Transformation steps

Create root AGENTS.md with overview, stack versions, and hard constraints.

Add service-local ARCHITECTURE.md files for responsibilities, interfaces, and dependencies.

Create centralized CONSTRAINTS.md with explicit MUST / MUST NOT language.

Add PROGRESS.md in each service so fresh sessions know current state.

TAKEAWAY