Where to start with repository knowledge and AI agents
11 articles arranged as three reading paths, plus a glossary. None of it requires the product, and most of it is about the problem rather than about Codee3.
You do not need the vocabulary to start. Pick the line below that sounds most like your week and it will tell you which article to open first.
- Articles
- 11
- Paths
- 3
- Terms
- 31
Four ways in
None of these is the beginner one. They are four different reasons to be reading, and each names the single article worth opening first.
I build with an agent every day and the repository is getting away from me
Work that took an afternoon has started taking two, and nothing obvious changed. This is the article about what quietly accumulated. The answer is not that you were careless.
Open this first
What happens at month three6 min read · part of Working with AI agents in a real codebase
I have an AGENTS.md or a CLAUDE.md and I am not sure it is earning its place
There is one rule for what belongs in an instruction file: include what the agent cannot work out by reading the repository, and leave out everything it can. The second half is the harder one.
Open this first
What belongs in an instruction file — and what does not6 min read · part of Working with AI agents in a real codebase
I am responsible for more than one repository
The interesting question is not whether a standard is sensible. It is what happens on the Tuesday somebody ignores it — a failed build, or a number on a dashboard nobody opens.
I want the argument before I look at any tooling
Start at the root of it: why having your text in the window is not the same as knowing your system, and why that gap is where the rest of the trouble comes from.
Repository knowledge
For readers who have not yet met the underlying problem
What institutional memory actually is, why a documentation folder decays by default, and why neither storage nor retrieval solves it. Start here if the phrase "authority problem" does not yet mean anything concrete.
Four distinctions rather than four steps — read them in whatever order you like. If you only read one, read Context is not knowledge; the other three lean on it.
Context is not knowledge
6 minFeeding an agent more text is not the same as giving it knowledge. Knowledge has identity, warrant, an owner and declared authority; context is bytes in a window.
Why repositories are hostile to AI agents
6 minHumans carry the missing context in their heads. Agents do not. The five structural failure modes of an ungoverned repository, and why agents amplify rather than cause them.
Retrieval is not truth
6 minVector search, grep and semantic indexes all answer where. Governance answers whether you may rely on it. Why retrieving the text is only half the problem.
Documentation is not governed authority
6 minWhy /docs rots. A projection with no declared source, no verified date and nothing accountable for it will drift by default.
Working with AI agents in a real codebase
For anyone shipping with an agent every day
Context rot, why generated instruction files can backfire, what an agent can and cannot infer from your repository, and what accumulates around month three. Written for people who are moving fast and intend to keep moving fast.
Top to bottom it is one argument: what degrades as input grows, why the obvious fix can backfire, what your repository never says out loud, what that costs by month three, and what is worth writing down instead.
Context rot, and why a bigger window does not fix authority
Measured degradation as input length grows, why similar-but-irrelevant material hurts more than noise, and why none of it is solved by adding tokens.
6 minWhy generated instruction files can make things worse
A controlled study found LLM-generated repository context files reduced task success and raised cost. The evidence is mixed, and the practical lesson is sharper than either result.
6 minProposal versus decision
An agent cannot tell "we might do X" from "we decided X" unless the repository says so. How standing gets lost, and what declaring it actually costs.
6 min- Start here if you only read one
What happens at month three
The point where AI-assisted work stops feeling fast. What accumulates, why it is invisible at first, and which parts are structural rather than a failure of discipline.
6 min What belongs in an instruction file — and what does not
One rule: include what the agent cannot discover by reading the repository, and leave out everything it can. Plus the discovery and truncation behaviour worth knowing.
6 min
Knowledge governance
For team leads, platform engineers and institutions
Enforcement versus reporting, phased adoption, standardising across repositories, and the difference between measuring repository structures and measuring the people who work on them.
Two articles answering different halves of one question: what a standard has to do to hold at all, and what you are entitled to measure while it does. Start with the first.
- 6 min
Enforcement versus reporting
The difference between a check that fails a build and a score that appears on a dashboard, and why the distinction decides whether a standard holds.
- 6 min
What to measure, and what not to
Governance tooling dies from developer resistance more often than from budget refusal. Measuring repository structures instead of people.
If you are reading this to decide whether it survives a tooling review, the mechanism itself is set out on the enforcement page, down to what the checks do not establish.
Glossary
31 definitions, grouped rather than alphabetised because the groups are the point. Nothing above assumes you have read this — it is here for the moment a word turns out not to mean what you assumed.
Authority
9 terms
- authority-graded repository knowledge
- repository knowledge in which every governed document declares what kind of claim it makes, so a reader can tell a binding decision from a summary or an observation without reconstructing it from context
- authority class
- a declared classification of a document's standing — CANONICAL, WITNESS, DERIVED or ABSTRACTED — recorded in the document itself rather than inferred from its filename or folder
- canonical
- locked local law; the highest authority class. Constrains every document below it, and wins on conflict
- witness
- a record of what is actually true now, with evidence and a date. Reports present reality; does not bind future decisions
- derived
- an index or routing document. Links upward to authority, must be reconstructible from its sources, and never redefines canon
- abstracted
- a domain overview or leaf document. Carries working detail beneath canon and may be revised freely, provided it does not contradict a canonical document
- standing
- the current state of a fact: in force, contested, or superseded. What a reader actually needs, and what an ungoverned repository never states
- provenance
- where a fact came from — the document, decision or observation it originates in. A fact with no provenance can only be believed, never audited
- verified date
- the date a document was last confirmed against reality. Makes staleness visible and inspectable; it is not proof that the content is correct
Structure
11 terms
- governed corpus
- the set of documents inside the governed directory that are subject to the authority model and the structural guards
- spine document
- one of the five recurring roles a governed layer needs: operating laws, present reality, locked decisions, sequenced work, and append-only history
- index-first
- the navigational discipline: read a folder's index, then drill into the one leaf you need, never bulk-read a domain
- no-versioning law
- the rule that no governed document may bear a version suffix such as v2, mk2 or FooV2. A version suffix declares a successor and forks truth
- supersession
- the formal replacement of a fact by a successor. The superseded fact is preserved and marked rather than deleted, with its successor named
- lineage
- the chain from a current fact back through its supersessions to its origin — the record a version-suffixed filename destroys
- projection
- a faithful, attributed, regenerable summary derived from authoritative sources. A projection is never itself authority
- structural invariant
- a property of the knowledge layer that must hold for it to remain governable — for example, that every document-bearing folder has an index
- structural drift
- the gradual deterioration of a knowledge structure through broken references, versioned names and missing indexes. Distinct from a document becoming factually wrong, which these checks do not detect
- reference drift
- the condition where a governed fact has been renamed but mentions of its retired name survive elsewhere in the corpus
- blast radius
- the set of all governed documents that reference a given fact. Queried before a rename so the whole fan-out is fixed in one pass
Agents
4 terms
- agent surface
- the instruction file a particular AI coding tool reads — AGENTS.md, CLAUDE.md, .cursor/rules and the rest
- redirect block
- a small removable block written into a tool's own instruction file, pointing it at the governed directory instead of an independent local copy
- context rot
- the measured tendency of language-model performance to degrade as input length grows, and for similar-but-irrelevant material to degrade it further than random noise
- context
- the bytes currently in a model’s window. Distinct from knowledge, which additionally carries identity, warrant, an owner and declared authority
Governance
7 terms
- guard
- a zero-dependency check that enforces a structural invariant and exits non-zero when it is violated, so CI can fail the build
- enforcement
- a check that runs on your commit and can block a merge. Distinct from reporting, which evaluates on a schedule elsewhere and produces a score
- reporting
- periodic evaluation of standards in a vendor backend, surfaced as a dashboard or scorecard. Visible, but not a gate
- institutional memory
- the organisational knowledge about a codebase — decisions, constraints, rejected alternatives — that exists beyond the source code itself
- repository-native
- existing as plain files inside the repository, version-controlled with the code, with no external service dependency
- project brain
- the literal name of the governed system Codee3 installs, used in filenames and command output — PROJECT-BRAIN.md, brain:check. Not the commercial category
- loose ends
- undispositioned tasks or intentions in the execution queue that have not been resolved
None of this requires buying anything
The specification behind all of this is published in full, and sections one to seven are implementable with a text editor and a naming convention. If you would rather read one long argument than 11 short ones, the essay is the whole case in one sitting.
Planned · not yet published
- Institutional memory after people and agents leave
- Knowledge drift, precisely defined
- How Codee3 works alongside your coding agent — not instead of it
- From observation to authority: how a fact earns the right to be relied on
Listed so the gaps are visible.