The Repository as a Knowledge System for People and Agents

The question and what you will learn

When an engineer or an agent opens an unfamiliar repository, they do not need the project's entire history at once. They need to know where to start, how to find the knowledge relevant to their particular change, which version of a document is in force, and who is responsible for its content. A repository can keep code, explanations, decisions and checks in a single versioned history. What it cannot do is turn every piece of text inside it into authoritative policy, a record of current production state, or permission to perform an action.

By now you can tell the context actually handed to a model apart from the full repository (context as a limited resource); you can look for the source that is authoritative for a specific question (source of truth); and you can hand work over together with links to its state and the limits of what is permitted (handoffs between agents and sessions). This unit looks at how to organise a repository so that the knowledge someone needs can be opened, understood, checked and updated, without forcing the same structure on every team. A companion unit, the instruction hierarchy, deals separately with how instructions reach an agent, how each product describes the way they interact, and which controls genuinely constrain an action.

Every repository, team, decision, author, record and result in the teaching scenarios below is invented. The public OpenAI Codex repository is used only as a concrete open example of documentation, not as a model to copy. Statements about products that change over time were checked against official pages on 26 September 2026; the fixed commit dates in the repository examples refer to those particular snapshots.

What a repository stores, and what it does not prove

A repository is a store of files, together with the history of their changes, managed by Git. Each commit identifies an exact snapshot of the files; branches let you compare and review proposed changes; the history keeps the author, committer, timestamp and description recorded in each commit. Those fields are useful as history, but on their own they are not independent proof of anyone's identity or of when something actually happened. A commit can pin a version of an instruction or a decision right next to the version of the code it applies to. GitHub describes a repository as a collection of files and the history of their revisions, and describes a permanent link to a commit as a way to open specific content instead of a moving branch [Git: commit data model; GitHub: repositories and permanent links].

That is a powerful property for long-lived knowledge. A team can see when it changed the way the service is started, which decision preceded a schema change, and which rules applied to the code at a given commit. If a requirement, an architectural decision, the code and the checks are all updated together in one change request, a reviewer can see them side by side. The repository becomes a versioned base of working knowledge: its content has a history, a location, an owner for each change, and a revision.

But "it's in Git" does not mean "it's the single correct source". A repository does not, by itself, measure which configuration is loaded in the running service. It does not confirm that a client approved the wording in a draft. It does not automatically record permission for every action, and it does not stop an author from adding a wrong requirement. A commit proves that a certain file existed in a particular snapshot of history. It does not prove that the policy owner approved the file, that its content matches the current state of the data, or that an agent has read it.

So ask four questions of every document:

Question	What you need to establish	Typical answer
Which question is this record authoritative for?	Its subject and its boundaries	The README explains how to get started; the record of an approved policy defines the rule; the code implements the current version of the behaviour.
Who is responsible for its content?	The owner of the decision, the domain or the process	The owner of a product rule approves its content; the engineering team describes the boundaries of the implementation.
Which version and environment does it belong to?	Branch, commit, release, product, environment or some other range	Instructions for the billing/ package on branch X; a procedure for service version Y; an approved policy as of date Z.
How will you notice it needs updating?	The event that triggers a review	A change to the build command, a public contract, a data schema, a requirement or a regulation.

This continues the distinction drawn in source of truth: the source is determined by the claim, the scope and the time. Jira, for instance, may be the source for a task's requirements; a Git commit the source for the code at that revision; a database the source for the current domain record; a deployment log the evidence of which artifact was actually launched. A repository can link to other systems without making their content its own copy.

A useful working rule: put into Git what the team needs to version, review and find again alongside the code. Do not automatically move into it personal data, current production snapshots, secrets, restricted material, or client decisions that are owned by another system. If a requirement is approved somewhere else, the repository can hold a link and a short explanation rather than the full text or an unofficial copy. A convenience copy is useful as long as it records where it came from, the revision, the date it was checked, and how to get it corrected.

Several different documents instead of one universal one

Documentation files have different readers and different jobs. Choose the structure according to the questions your team actually asks, not according to a fashionable template.

• README.md is the entry point for a human: what the project is, who needs it, how to run or use it, and where to go next. It should quickly open a route to the technical and subject-matter sources. A README is not obliged to hold every architectural detail or to be the only up-to-date set of rules.
• ARCHITECTURE.md, or an equivalent document under docs/architecture/, is a map of the system's boundaries, its main components, data flows, important constraints and links to decisions. The name is not a standard format: in a small project a section of the README is enough, while a large one is better served by several subject-specific records. The map should link to the code and contracts rather than create a parallel source of their current values.
• AGENTS.md holds instructions for products that support this file, such as Codex and other agentic tools with AGENTS.md compatibility. It is the right place for short working conventions, important boundaries, reading routes and commands that are hard to infer from the code. The text file itself is not a system access policy, and it does not force any agent to read it.
• CLAUDE.md holds instructions and project context for Claude Code. It is not a generic name for the rules of all agents and not a guarantee that Codex will read it. Likewise, AGENTS.md is not automatically interchangeable with CLAUDE.md in every Claude Code environment. Loading mechanisms depend on the specific product and its configuration; the second worked example later in this unit shows one current configuration.
• An Architecture Decision Record (ADR) captures the context of an important choice, the alternatives considered, the option chosen and its consequences. It preserves why the team chose an option, not just a terse "this is how we do it". An ADR template does not become an approved decision until it has a named author or owner and a status.
• A specification (spec) describes the expected behaviour, contract or scope of work for a specific product. Its state must be named: proposal, draft, approved requirement or superseded revision. The implementing code does not always match the currently approved specification, and a draft does not define a rule for users.
• An execution plan answers the question of the order in which the person or agent doing the work intends to make a specific change. It depends on the decision that justifies the content and on the state of the code. It is a temporary working tool, not an automatic source of product policy.
• Testing documents explain or run checks of behaviour: the testing strategy, the boundaries of a test suite, fixtures, commands or requirements for evidence. A machine pass status confirms only the suite that was run and the revision it ran on; a page of text does not replace the result of a run.
• A runbook guides the actions to take during a recurring operational task or an incident. It should be scoped to a service and to conditions, show the point of escalation, and contain neither secrets nor permission for a risky operation that the owner has not approved.
• Security documents cover the threat model, data-handling rules, how to report a vulnerability, and storage or access requirements, insofar as that information is allowed to live in the repository. The organisation's actual policy may live in a different canonical source; in that case Git should hold a safe link and the boundaries within which it applies.

These roles can be combined in a small project, provided it is clear which section is responsible for what. In a large monorepo where many teams work independently, documents are usually split by domain, package or type of decision. In both cases the reader needs to see a path from the starting README to the primary evidence. Duplicating one instruction in full across the README, ARCHITECTURE, AGENTS.md and CLAUDE.md is a shortcut to contradictions: the code or the start command changes, and the copies end up giving different answers.

The open Codex repository offers a concrete but limited example. At the pinned commit, the README opens by saying this is the Codex command-line interface (CLI), distinguishes the terminal program, the integrated development environment (IDE) integration, desktop and web, and points to separate documentation, contribution guidelines and build instructions. In the same revision, docs/agents_md.md does little more than direct the reader to the official AGENTS.md documentation. AGENTS.md, by contrast, contains specific working constraints for codex-rs, while docs/contributing.md separately explains that external code contributions are not accepted and where to file reproducible reports. The README does not duplicate every technical rule; the product explanation, the instructions for whoever does the work, and the contribution rules each have their own place. This is an example of mutually linked files at one specific revision of openai/codex, not a recommended tree for every repository [OpenAI/codex, README; AGENTS.md; docs/agents_md.md; docs/contributing.md].

How to distribute documents and responsibility

A directory helps you find a document, but its path does not make it valid. A docs/security.md file may be an old draft; an ADR may have been rejected; a README may link to a different revision. Nor is the example tree below a universal standard. What follows are classes of document that you can combine or separate depending on the size and type of the project.

Class of knowledge	Example location	Owner of the content	When to review or update
Orientation and getting started	README.md, docs/index.md	The repository owner or the responsible engineering team	When the purpose, the way to run it, the main routes, the public entry point or the documentation catalogue changes.
Product behaviour	docs/product/	The owner of the product or policy	When behaviour, acceptance criteria, terminology or user-facing constraints are agreed or changed.
Architecture and contracts	docs/architecture/, docs/specs/	The owner of the system, service or contract	When a component boundary, data flow, schema, external interaction or technical invariant changes.
Architectural decisions	docs/adr/ or a searchable alternative	The person or team responsible for that particular decision	When a decision is made, superseded or reopened; the status and the link to its replacement are updated too.
Plan for a specific piece of work	docs/exec-plans/ or a task outside Git	Whoever executes the plan, together with the owner of the decision the plan depends on	When the scope, sequence, a blocker, the relevant decision or the state of the task changes; mark it historical once complete.
Checks and their strategy	docs/testing/, check configuration, the test directory	The quality owner or the team that maintains the relevant suite	When behaviour, a contract, a test fixture, the environment or the run command changes. Store the results themselves together with the exact run.
Operational procedures	docs/runbooks/	The owner of the service or the change	When the action command, environment, a dependency, the escalation point or the access level changes; review after an incident.
Security and sensitive boundaries	docs/security/ or a protected policy store	The owner of security, data or compliance	When the threat model, data classification, trust boundary or retention policy changes. Do not move confidential material into a public Git repository.
Code and machine-readable contracts	src/, schemas, configuration, migrations	The owner of the relevant package or service	Together with any change in behaviour or structure. Documentation should explain the invariants; the code and schema remain the exact record of the implementation at a given commit.

A structure such as docs/product, docs/architecture, docs/adr, docs/specs, docs/exec-plans, docs/testing, docs/runbooks and docs/security is a set of possible shelves, not a requirement to build every one of them. A small web application may need nothing more than a README, a short description of the architecture, run instructions and a handful of decision records. If there are no documents of a given class, or no need for them, an empty folder adds nothing. In a monorepo the same classes can have their own places in sub-projects, with a central index linking to them.

The owner is not the same as the author of the last commit. An author can fix the wording and propose a new procedure. The owner is accountable for the content having been approved within their role, for the stated boundaries matching practice, and for a review being triggered when the facts change. If no owner can be named, that does not mean "the team" by default; either assign someone responsible or honestly mark the record as not yet confirmed.

For a rule or a plan, the following metadata is useful: title, status, scope, responsible owner, who approved it and when, the date of the last real check, the versions or environments the text applies to, a link to the primary source, and the event after which the content must be reviewed. There is no need to turn every README into a form. Add just the markers that will help the next reader tell a draft from a decision, or a current procedure from an old retelling. A "reviewed 23 September" note means something only if someone actually checked the content against its source on that day.

A plan does not replace a decision

An execution plan answers: "by what steps do we intend to reach the result, given today's assumptions?" A decision answers: "which option was chosen, by whom, within what scope, and why?" A specification answers: "what behaviour has been approved?" All three texts can be useful, but they do not have the same standing. A plan changes often during the work; when an assumption in the plan conflicts with a decision that is currently approved, the person or agent doing the work must not treat the plan as a new decision just because it is detailed or was the last thing opened.

For an active plan, record the task key, the owner of the execution, the status, the date of the snapshot, the decisions it depends on, related files or contracts, open questions, the next step and the stopping condition. A status might be, for example, "draft", "approved", "in progress", "blocked", "done" or "superseded". These are examples of clear labels, not a global scheme everyone has to adopt.

Once a plan is finished, there is usually no need to rewrite it as though the expected steps had always been right. Keep its historical value: add a visible "done" or "superseded" state, the date, a link to the commit that implemented it, the completed task or the new decision, and remove it from the index of active work. If the plan has become harmful or contains a secret, follow the rules for cleaning history or restricting access; a label on its own does not remove copies that have already spread. Being in an archive/ folder is not enough either, if the page does not explain that the record is no longer an instruction.

Progressive disclosure: a short route to the depth you need

Progressive disclosure means the reader first sees a short route and only then opens the material needed for the current task. For a repository, that might look like this:

1. The root README says what the product is and where the entry point is.
2. A short knowledge index names the domains, the system owners, the active rules and the access boundaries.
3. A domain document shows the details and links to the confirmed decision or contract.
4. The primary source, the code or a check makes it possible to verify a specific claim.

Someone changing the styles on a page usually does not need to read the database recovery procedure. An agent touching the storage of personal data may need the exact security policy, the table contract and the mandatory checks. A short route does not hide information: it says where things are and when to open them. This continues the idea of context as a limited resource without repeating its lesson about tokens: what serves a repository's goals is a selection of the right sources, not loading every file for every change.

An index should be a map, not yet another full duplicate. It can contain the topic name, a link to the canonical record, the owner, the scope, the current status and the trigger for updating it. If a document lives in another system, give a stable link, the access level and the permitted route for reading it. Do not put into AGENTS.md an endless catalogue that already exists in the README, or the whole architecture that only matters when a particular service is being changed.

Loading rules depend on the product

A file existing in the repository and a file being passed into an agent's context are two different events. One product looks for instructions in every directory from the Git root down to the working directory; another loads only certain names, has its own nesting rules or needs an explicit import; a third may read none of these files at all. Before building shared rules for several agents, check their live documentation, the environment settings and the sources that were actually loaded.

As of 26 September 2026, the official Codex documentation describes an AGENTS.md chain: user-level instructions first, then each directory from the project root down to the current working directory (CWD). If the product cannot establish the project root, it checks only the CWD. In each directory it checks AGENTS.override.md, then AGENTS.md and any configured alternative names; it takes at most one non-empty file from each directory. The texts from root to CWD are concatenated, and a closer instruction can refine a broader one. By default the combined size is capped at 32 KiB. So the CWD, the launch path, the file names and whether they are actually present in the assembled context all matter [Codex, Custom instructions with AGENTS.md].

Claude Code has its own rules. CLAUDE.md is loaded for the corresponding level of the project, and files in subdirectories may be loaded when that subtree is accessed. The documentation allows @path/to/file to import another source into CLAUDE.md, with rules for resolving relative paths and a limit on import depth; it also describes .claude/rules/ for topic-specific or directory-scoped rules. In the default configuration, when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or its ancestors, Claude Code may read AGENTS.md; if Claude's own files are present, AGENTS.md may not be loaded without an explicit import or a different Project instructions mode. Direct reading of AGENTS.md is supported from version 2.1.277, but before 2.1.281 some sessions, including those via Bedrock or with telemetry disabled, could read only CLAUDE.md. The Project instructions setting can select one format or both. So check the exact version, the configuration and the actual context; this is the behaviour of Claude Code, not of every Anthropic product or every agent [Claude Code, How Claude remembers your project].

That is why shared files should hold the facts common to all products, while thin files hold the product-specific routing. For example, docs/development-setup.md can be the single place for the actual install and run commands. AGENTS.md says which kinds of work call for reading that file and can contain a Codex-specific boundary. CLAUDE.md describes the rules specific to Claude Code and, where appropriate, imports the same short command file. If there is no point loading it automatically for every task, CLAUDE.md can simply give the path, and the agent reads the setup document when working on running the project locally. There is no universal requirement to import one file into the other; the choice depends on how much information is genuinely needed at the start.

All the actual values in the setup location must still match the real sources: the package manifest, the dependency lock file, the continuous integration (CI) scripts and the current code. If the technology stack has changed, an old line in an instruction does not become a new fact because it was loaded automatically. Conversely, a correct README is of no help to a tool that never opened it.

Reference, instruction, skill, workflow, check and access right are different things

• Reference material explains. It might say that the service stores a time zone, or why the team uses migrations. Text alone does not force an agent or a server to follow a rule.
• An instruction sets the expected way of working for a particular agentic product: what to read, which commands to use, which boundaries not to cross without a decision. Different tools use different files and different ways of wiring them in. An instruction remains context for the agent; following it is no substitute for access control.
• A rule, or rule file, may have a special meaning for a particular agent. The Claude Code documentation, for example, supports .claude/rules/ and a specific mechanism for matching a rule to a path. In another product, rules.md may be an ordinary file until someone configures it or opens it.
• A skill is a packaged, reusable piece of material or procedure for a particular type of work, sometimes with resources or a script. In Claude Code, skills live in the corresponding SKILL.md directories and are loaded by that product's mechanism; Codex has its own skills documentation. Do not claim that all agents look for one format or invoke skills the same way [Claude Code, Extend Claude with skills; OpenAI, Build skills].
• A workflow is a repeatable sequence of actions. It may be nothing more than an instruction in Markdown, or an executable automated process such as a GitHub Actions configuration file. If a step is not started automatically by a system, do not call it a safeguard that works without a human.
• An executable check is a test, link check, formatter, linter, schema or static analyser with a defined input and result. It can catch a formal error, but a link check does not know whether a decision is semantically out of date, and a test that does not exist checks nothing it does not cover.
• An access-rights policy is a control implemented by the file system, the repository management system, a sandbox, an account or an external service. "Read-only" access or a ban on merging has to exist in the corresponding mechanism. The sentence "never merge" in a file is a useful instruction, but it is not a technical prohibition for a user, an application or an agent with excessive access.

Text and technical restrictions complement each other. An instruction explains why a rule exists and how to act when there is an exception; a test or a setting prevents a particular class of violation. If an action is risky, the right permissions should restrict that action itself, regardless of whether the model remembered the paragraph. This matters most for secrets, personal data, production databases, releases, payment operations and loading code from unverified branches.

Freshness: check date, owner, and changes made next to the code

A file can be correct when it is written and wrong after a change to the code, a process, permissions or a contract. A document created earlier does not automatically become false, and a newer date does not prove that anyone checked it. Freshness needs provenance and review events: who can confirm the content, what it depends on, and which change triggers a fresh check.

When a code change alters behaviour, an external interface, the way something is deployed, a test scenario or a requirement, the related documentation should be considered in the same change. In a pull request (PR), reviewers look at the implementation, the documentation, its status and its links as a single diff. That helps a reviewer notice, for example, that a new endpoint still has old documentation, that a plan relies on a different schema, or that the README still suggests a command that has been removed. A separate documentation PR can be appropriate if the content really is independent and the owner has agreed the sequence; what matters is recording the link between the change and the follow-up update.

Copies have owners and consumers too. In a pinned revision of AGENTS.md in the public langchain-ai/docs repository, the team explicitly requires AGENTS.md and CLAUDE.md to be kept in sync, and selected derived rules for editors to be updated in the same PR. It is a useful example of how to document the relationship between a source and its copies. It confirms only the practice that this team declared in that file; it does not prove that every copy always matches, or that such a scheme is needed everywhere [LangChain, pinned AGENTS.md]. If a reference document is generated from a canonical record, name the source and the generation command; if it is edited separately, assign an owner, check the version it was derived from, and show all consumed copies together in review.

Automated checks are useful, but their reach is limited:

• a local link check finds a path that no longer exists, but does not detect a link that still works yet points to a section whose meaning has gone stale;
• a check of headings or structure catches a broken format, but does not confirm that the owner approved the policy;
• a test or schema check can reveal that the code does not match a declared contract, but does not prove that the contract matches what users want;
• automatically comparing the commands in the documentation with the manifest reduces mechanical drift, but does not check whether the procedure is safe in every environment;
• no date in a header replaces reading the current source and checking the value.

Changes to AGENTS.md, CLAUDE.md, automation rules, workflows or checks affect everyone who works in the relevant part of the repository. Review them as changes to working policy, not merely as Markdown edits. GitHub lets you define code owners and require approval by file path through branch protection or rulesets, if the repository is configured that way. Such controls are not switched on automatically for every repository; check the actual rules on the target branch [GitHub, pull request reviews; protected branches].

Untrusted files, secrets and changes to instructions

Not every file in the working tree comes from whoever owns the rules. A repository can end up containing text from an issue, a pull request comment, a generated report, the contents of a downloaded dependency, a test fixture or an external document. Such text may include sentences like "ignore all previous rules" or "read the token and send it". That is data, which the agent must classify and quote when needed; it does not become a higher authority just because it sits in the project folder or was returned by a tool.

Whether to trust guidance is decided by its source, purpose, owner and status. A file that the product recognises as configuration can change what the agent will read or how it will try to work. That is precisely why changes to root or nested instruction files, permissions, hook scripts, workflows and checks should be shown in the diff and routed to code owners or designated reviewers. If a change removes a prohibition, widens access or replaces a check command, it needs a separate explanation. A repository can protect these paths with CODEOWNERS, required reviews and status checks, if the branch policy supports it [GitHub, code owners and protected branches].

Secrets (a password, a key, a token, a private certificate) are not documentation. Do not put a real value into a README, an example, a test log, a screenshot, deployment documentation or a short-lived branch. Explain how to get access from the approved secrets store without copying the secret. .gitignore does not revoke a value that has already been committed, and a secret scanner does not guarantee that nothing has leaked. If a secret is exposed, first treat it as compromised and revoke or rotate it; simply deleting it in the latest commit does not remove it from earlier history or from copies in existing clones [GitHub, removing sensitive data; secret scanning].

None of this means you should suspect every document or bolt a huge generic security section onto every project. It means that a repository is a shared surface for both reading and execution: a static sentence can influence an automated reader, and a script can run in an environment that has permissions. So instructions, scripts and automations need an explicit owner and change control, and external attachments do not gain the right to act simply by existing.

Two limited perspectives on owning knowledge

In The E-Myth Revisited, Michael E. Gerber distinguishes between the technical work a person does well and the systematic running of the business that does that work. The available excerpt of the first chapter states exactly this difference: knowing how to do a professional operation does not automatically mean knowing how to run a business that does it. The bibliographic description of the edition highlights another central thread of the book: working in your business and working on it are not the same thing. We use this for documentation as a limited analogy. If starting the service, interpreting the data or some important procedure exists only in the founder's memory, the first person who has to do the work without them will have to guess at the standard. The owner of a process should help make important operational knowledge transferable and keep it up to date as things change.

A separate, later EMyth article describes the company's approach to systems: write down the steps, explain the reasons, hand the procedure to another person, notice where the result diverges, update the standard and check again; responsibility for the system stays with its owner, but the participants help find the gaps [EMyth, How to Design Systems for Your Small Business]. This is later material from the company, not a quotation from the book. Our own point, that a technical owner should likewise update a setup document or runbook after the implementation changes, is a transfer of that principle to the repository.

In the second edition of Team Topologies, Matthew Skelton and Manuel Pais give considerable attention to clear purpose, the flow of value and the cognitive load on teams. As an analogy for knowledge, this is a reminder that documentation has boundaries too: users of a package should be able to understand its public interface; the owning team should be identified; an outside consumer does not need every internal implementation step. A change that reallocates responsibilities between teams may require updating not only the code but also the documentation route and the owner [Skelton and Pais, Team Topologies, 2nd edition].

Both ideas help you ask: "Who will maintain this knowledge, and how will someone else doing the work understand the standard?" They do not dictate repository directories, how an agent loads files, or limits on instruction size. A team's organisational cognitive load is not the same thing as a model's context window limit; a repository is not a team; there is no need to mimic the four Team Topologies team types with folders. The analogy helps with decisions about boundaries and responsibility, but it does not prove that a particular scheme suits every system. The limits of what was accessed in the books and of the conclusions drawn are stated in the sources.

Three complete examples

All three scenarios, and every repository, owner, status, file, command, data point, result and commit in this section, are invented. They show a verification process; they do not report real work that was carried out.

Example 1: a small booking-system repository

Situation. A small team maintains a table-booking service for several training restaurants. An agent has been asked to change how bookings are rescheduled, and it needs to find where the rules are defined, which checks matter, and what to do in the event of an operational failure. The repository contains a lot of files, and some of the names only make sense to a developer who has since left.

Problem. Reading every file and memorising the whole product would be pointless. A single README page is not enough either: it should not be product policy, ADR, execution plan and emergency procedure all at once. If it were convenient to put everything into AGENTS.md, that file might be loaded even for unrelated tasks, and a very long file would bury the key rule among secondary details.

Options.

1. One big README. Cheap to start with, but over time the README mixes audiences and does not show which section is an agreed rule and which is a plan.
2. Build a complete universal tree up front. This makes classification easier in a large system, but in a small team it produces empty directories, formal documents and needless searching.
3. A minimal entry point plus separate subject records. Add a shelf only for knowledge that has its own owner, life cycle or risk.

Decision and action. The team chooses the third approach. One possible text tree looks like this:

booking-service/
  README.md
  ARCHITECTURE.md
  AGENTS.md
  CLAUDE.md
  docs/
    index.md
    product/
      rescheduling-policy.md
    adr/
      0007-time-zone-for-bookings.md
    exec-plans/
      active/
        BOOK-418-reschedule.md
      history/
    testing/
      booking-change-checks.md
    runbooks/
      booking-write-failure.md
    security/
      booking-data-handling.md
  src/
    bookings/
  tests/
    bookings/

This is the shape proposed for this particular example, not a mandatory template. In it, each location has its own route and someone responsible for it:

• README.md briefly explains the service and leads to docs/index.md; the repository owner updates it when the purpose, the way to run it or an important link changes.
• ARCHITECTURE.md contains the service boundaries and the flows between a booking request and storage. The technical owner reviews it when the service boundary, the storage channel or a contract changes.
• AGENTS.md concisely names the confirmed check command and says that changing business rules requires reading the relevant policy and ADR; the owner of the engineering rules reviews it when the actual agent workflow changes. This file contains no server access and no password.
• CLAUDE.md contains only Claude Code settings and routing; if the team wants to import shared short documentation, it does so through a mechanism Claude Code supports and checks it in the specific version. The file alone does not automatically affect every product.
• docs/product/rescheduling-policy.md holds the approved deadlines, time limits and user-visible rules; the owner of the product decision reviews it after an approved change to the rules.
• docs/adr/0007-time-zone-for-bookings.md records how the team decided on the time zone for bookings and which consequences it considered; the owner of that decision, or their successor, marks a new ADR if the choice is superseded.
• docs/exec-plans/active/BOOK-418-reschedule.md is a temporary plan for a specific task, not a source of policy; whoever is executing it marks it done or superseded and removes it from the active index when the work is finished.
• docs/testing/booking-change-checks.md describes the classes of check that are needed, including the boundaries of the test fixtures; the owner of the test suite updates it along with any change in behaviour. The actual status of a run lives in the result, tied to a revision.
• docs/runbooks/booking-write-failure.md contains a safe procedure for diagnosing a failed write, checking a retry and the escalation route; the service owner reviews it after a change to the operational application programming interface (API) or after an incident.
• docs/security/booking-data-handling.md links to the permitted data classification and access method; the data owner checks it if a field, a transfer or the storage mode changes.

The agent starts with the README, reads the short index, and then opens only the rescheduling rules, the time-zone decision and the relevant checks. If its change touches booking data, it also reads the data-handling requirements. Before drawing up a plan, it checks the current status in Jira and the code that the documents refer to. When a change affects a permitted boundary or an external operation, it checks what the tool is able to do and what requires a separate human decision.

Observable result. A reviewer can walk from the README to the policy and the ADR, and find separate owners for the requirement, the decision and the test procedure. They can see that BOOK-418 is a plan in progress, not approval of a change to a business rule; that the current behaviour around time zones refers to the ADR; and that the runbook contains no secret value. If, the next time the test command changes, the code and AGENTS.md are updated but the setup page is not, the discrepancy is visible in a single PR.

Why this works, and its limits. The entry point shortens the search, and the specialised records keep their own statuses and owners. The text tree makes the locations visible without a diagram and does not force the reader to memorise them by name. A small team, however, does not have to create all nine documents: if a runbook is not needed, or a data rule stays in an approved external source, a link is better than a copy. The index can also go out of date over time, and the repository itself does not prove that the chosen service and database are currently available in production.

Example 2: AGENTS.md and CLAUDE.md disagree about setup

Situation. An invented TypeScript repository has instructions for two tools. AGENTS.md says to start the project with pnpm dev and to use Node.js 22. CLAUDE.md says npm start and Node.js 20. Both documents look current, and the task asks for a small settings screen. An engineer reads the README, which says only "see the development instructions".

Problem. If both files are read as equally valid instructions, the agent may install dependencies with the second package manager, change the lock file, or waste time on a failed start. Choosing by file name, by commit date, or by whichever command the agent already knows does not confirm what the repository owner intends. In this example it is also important not to assume that both products loaded both files: one agent may see only AGENTS.md, and the other only CLAUDE.md.

Options.

1. Run both commands at random. This can create two dependency configurations, change the lock file and hide the root cause of the contradiction.
2. Treat one format as universally authoritative. For example, decide that AGENTS.md always wins, or that the newer file automatically replaces the other. The file discovery mechanism differs between tools, and the newer copy might have been a draft.
3. Check both instructions against the executable sources, establish the owner, and remove the double canonical value. The repository should have one shared setup instruction and separate short routes for each product, if their behaviour genuinely differs.

Decision and action. At first the agent runs neither npm start nor pnpm dev. It reads package.json, the lock files, .nvmrc or the Node version file, the continuous integration (CI) configuration, and the development instructions the README points to. In this invented example, that primary evidence consistently points to pnpm version 9.15.0 and Node.js 22: there is a pnpm-lock.yaml, the packageManager field specifies [email protected], the version file and the CI environment are both set to Node.js 22, and package.json contains a matching dev script. There is no current package-lock.json in the repository that would support a separate npm route.

These files show a reproducible build configuration, but on their own they do not give the agent permission to download arbitrary packages or change the environment. If the command, version or configuration contradicted one another, the agent would stop the setup action, record the contradiction and go to the owner of the development process. Here, the setup owner confirms that Node.js 22 and pnpm are the correct values; CLAUDE.md contained an outdated copy from an earlier state of the project.

The team adds a single canonical docs/development-setup.md with the prerequisites, the first-run sequence and the date and context of the check. The root AGENTS.md contains a short route to it and the confirmed command for that tool. CLAUDE.md keeps only what is specific to Claude Code and imports the shared setup through the @... mechanism described in the Claude Code documentation, provided the team has checked that behaviour in the target version. In a different configuration, the same document might be a link rather than an import; do not rely on syntax that a particular product does not support. In the PR the team removes the conflicting npm start and Node.js 20, adds a link to the shared file, and routes that path to the setup owner.

Loading behaviour must be checked separately. The current Codex documentation describes how the product assembles AGENTS.md instructions from the general level down to the working subdirectory. The Claude Code documentation says that when both names are present in the relevant hierarchy, the default is to load CLAUDE.md, and AGENTS.md has to be imported explicitly. That difference does not resolve the conflict on its merits; it only shows which text a given agent may have received. The owner checks that both routes lead to the same shared rule in the products and versions the team supports.

Observable result. After the merge, a single setup document names the Node.js and pnpm versions that match the lock file and CI. The root instructions are short, and the two contradictory commands are no longer presented as equally valid. In a check on a clean branch, the tool version and the install command reproduce the conditions defined by the configuration files; the result of that check can be tied to a commit. For the purposes of the example, no claim is made that Codex or Claude Code actually ran: this is a decision scenario, not a test report.

Why this works, and its limits. The executable configuration and CI helped establish the fact of what actually builds, but the owner explained which rule is meant to be maintained. Having a single setup document reduces the chance of drift, while separate product files leave room for genuine differences. Still, a lock file does not describe every permitted way of working, and a green CI run does not approve an access policy or product requirements. Another repository may legitimately support both npm and pnpm; in that case document the separate environments and the reasons for them rather than imposing one option. Text instructions and imports must be checked in the specific version of the relevant product.

Example 3: an old plan proposes changing a decision about historical data

Situation. In an invented sports-statistics service, last quarter's plan is still sitting in the active folder: "remove the persistent club identifier and store the club name directly in each match". A new task changes how names are displayed in the season history. An approved ADR, signed off by the owner of the domain data, says to keep a stable club_id and to display the name according to the club and the season, so that historical records remain interpretable after a club is renamed. The plan and the ADR contradict each other. In the team chat log, someone speculates that the ADR is "probably not needed any more", but the owner never confirmed any such decision.

Problem. The plan describes a path to execution; the ADR describes an approved domain decision. The plan's age, its active status or its proximity to the current code do not give it the right to override an approval. But the owner of the ADR might also have changed their mind since approving it; one old copy of a document cannot speak for a person about a new decision. If the agent picks one version without checking, it may irreversibly destroy the link between matches from different seasons and the club.

Options.

1. Follow the old plan. It is a quick step, but it contradicts the currently approved decision and may lose the club's identity in the history.
2. Treat the ADR as absolute truth for ever. An ADR explains a decision for a specific time and context. The owner can revisit it; an old record does not substitute for a new approval if the decision has changed.
3. Check the ADR's status and owner, do not carry out the destructive operation, and then update the plan and links to match the confirmed decision. If the owner is unavailable or the answer is unclear, carry out only safe investigation and ask for clarification before changing the schema.

Decision and action. The agent reads the ADR to the end and checks its approved status, date and reference to the owner; it opens the change history and the current task; it examines the schema code and migrations to understand the consequences. These steps prove only that the repository contains an approved decision and an outdated plan. They do not allow the agent to invent the idea that the owner has revoked the ADR. The agent describes the contradiction explicitly in a comment on the work item and addresses it to the owner of the domain decision. It does not run the migration that drops club_id until the owner makes a new decision.

The owner replies that the stable identifier is still required; seasonal names are a display attribute, not the club's identity. Had the owner decided the opposite, a new ADR, or a new approved version of the same decision clearly marked as superseding the previous one, would have been needed. In this teaching scenario, the owner upholds the current ADR. The author of the change marks the old plan as superseded, moves it to the historical plans or removes it from the active list, adds a link to the ADR, and explains which steps of the plan no longer apply. The new plan keeps only the sequence for implementing the approved rule: keep club_id, separate the seasonal display names, check matches from previous seasons, and do not break the historical link.

Before making the change, the team checks the index and any links to this plan, open PRs that might have relied on it, and the schema checks. Material still needed for the historical record is not deleted as though the old plan never existed; it is given the right status and a route to the current ADR. If any derived reference documents in the repository presented the name as the club's unique identity, they are updated in the same PR. Changing the documentation alongside the code lets the reviewer see that the reason for the change and the schema are consistent.

Observable result. The implementation diff contains no removal of the stable identifier; the status of the historical plan is visible; the new plan links to the confirmed ADR. The example's schema checks preserve the link between matches and club_id, and a demonstration rename scenario shows two seasonal names for the same identifier. The PR shows who confirmed the domain decision and which documents were updated. This is the expected result of an invented example, not a claim about a real production data store.

Why this works, and its limits. The agent separated planned work from approved policy, identified the owner of the contradiction, and did not turn a chat remark into a client decision. Examining the code showed the technical impact, and the fresh confirmation established intent. Even an approved ADR, however, does not prove the current state of the deployed database; before changing a live system you need a separate check of the actual revision and a permitted migration process. The historical plan may be useful evidence of why the team once considered a different approach, but from now on it should not sit in the index next to current work without a label.

The minimum of sufficient documentation

The goal is not to have a file for every topic. The sufficient minimum is a route by which a new participant can answer the question that matters for this change and find the person who can resolve an uncertainty. For a small repository, that may be a short README, one subject document and tests with obvious names. A system with regulatory requirements, several teams or operational risk needs clearer roles, decisions, owners and a review process. The structure should grow with the cost of a mistake and with how often the work is repeated.

A practical knowledge policy can answer five questions:

1. What is stored where? Name the primary source for requirements, architectural decisions, code, domain records, approved external material, checks and discussion. Links lead to the source; any non-canonical copy is marked as an extract, cache, generated material or reference.
2. Who approves and maintains each category? Name a role or a team, not just the person who once wrote the file. An owner can accept a contribution from another team, but unclear responsibility is a reason to ask, not to guess.
3. Which event triggers an update? A change to the CLI, configuration parameters, an external contract, a product rule or an access permission, or an incident, should prompt a check of the relevant document. Schedule periodic re-checks only where the rate of decay justifies it.
4. How do you fix an outdated or conflicting copy? Find the primary source, check the owner and status, raise the specific conflict, then update the canonical record and its links or derived copies. Do not make a sweeping multi-page edit of every copy without understanding who uses it.
5. What deserves special review? Agent instructions, permissions, workflows and checks affect how code runs and which actions are taken. Route such changes to the designated reviewers and state the difference in behaviour. Access is controlled by the platform and the repository settings, not by the documentation itself.

Write down knowledge that is expensive to rediscover, that has ambiguous exceptions, that must survive a change of team member, or that affects security, data or operational actions. Add a reference document when several consumers regularly look for the same thing, but keep one primary source with a defined owner. Do not build an exhaustive encyclopedia of every script, class or one-off intention. If a fact is easy to read from the code and has no hidden context, the code, a good name and a test may explain it better than a separate page.

An index needs upkeep too: automate checks for broken links if the index is large, assign someone responsible for its content, and remove or mark duplicates after a change. A check of a web address (URL, Uniform Resource Locator) does not detect semantic drift: a link may open and still lead to a rule that no longer matches the code. Cross-check critical documents against their owners, open requirements, the code version and the result of verification, rather than trusting a single automated signal.

A repository is a useful versioned surface for agreements. It is not a replacement for every system in the company, and not a machine that turns text into truth. Its documentation becomes working knowledge when every important record answers three questions: which question it is meant for, which revision or scope it covers, and who will update it after a change. When the answer is unclear, find the source and the owner first. Do not paper over a contradiction with an updated timestamp, a convenient retelling or an agent's confident tone.

Sources and further reading

The references below support specific claims made in this unit. Online documentation that changes over time was checked on 23–26 September 2026; where a source was checked on a different date, that date is given next to it. Where a page shows no visible update date, that is stated. A repository with a moving branch is cited only through a permanent link to the commit that was checked. Dates, product versions and behaviour may change; before applying any of this in practice, open the current documentation for your version.

1. GitHub Docs, "About repositories" and "Getting permanent links to files". Current documentation; no update date shown on the pages consulted; accessed 23 September 2026. Used for the statements about a repository's files and history and about linking to a specific commit. Limit: a description of GitHub features does not set any particular organisation's policy. About repositories; Getting permanent links to files.
2. OpenAI, Codex, "Custom instructions with AGENTS.md". Official current documentation; no separate update date shown on the page; checked 26 September 2026. Used for Codex's current, product-specific order for discovering and combining AGENTS.md files, the role of the working directory, and the instruction size limit. Limit: discovery depends on configuration and surface, and other products may work differently. Codex documentation.
3. OpenAI, Ryan Lopopolo, "Harness engineering: leveraging Codex in an agent-first world", 11 February 2026. Used as a description of one OpenAI team's concrete experience with structuring a repository, knowledge routes, long-lived instructions and automated control. Limit: this is the author's account of a single internal process, not evidence of a universal recipe. OpenAI.
4. OpenAI Developers, Eric Provencher, "Rethinking skills and prompts for GPT-6 Astra", 11 September 2026. Used as a current example of progressively revealing context, a small always-on layer, and splitting skills by task. Limit: a product recommendation for the system described, not a requirement for every repository or model. OpenAI Developers.
5. Anthropic, Claude Code, "How Claude remembers your project", "Extend Claude with skills", "Settings files and precedence" and "Configure permissions". Official current documentation; no update date shown on the pages; checked 26 September 2026. Used to establish exactly how Claude Code handles CLAUDE.md, @path imports, .claude/rules/, skills and the separate permissions configuration, including the conditions under which it reads AGENTS.md. Limit: this is Claude Code behaviour, not a general rule for other Anthropic products or for agents in general. Project memory; Skills; Settings and permissions; Permission rules.
6. GitHub Docs, "About protected branches", "About code owners" and "Removing sensitive data from a repository". Current official documentation; no update date shown on the pages consulted; accessed 23 September 2026. Used for the conditional nature of branch protection and code owners, path-based review requirements, and the limits of simply deleting a secret from history. Limit: these features work only when configured; scanning does not prove the complete absence of secrets. Protected branches; Code owners; Sensitive data.
7. OpenAI, "Understanding prompt injections". No publication or update date shown on the page checked; accessed 23 September 2026. Used as an official explanation of why content from third-party sources can contain harmful instructions and should be kept separate from permission to act. Limit: a general article about a defensive approach, not a guarantee of detecting every case and not a complete standard for any particular agent. OpenAI Safety.
8. Matthew Skelton and Manuel Pais, Team Topologies, second edition, IT Revolution, 23 September 2025; ISBN 9781966280002. Accessed 23 September 2026: the authors' and publisher's pages, not the full text of the book. Only the descriptions of purpose, team boundaries and cognitive load are used, as a limited organisational analogy. No conclusions about any specific folder structure are drawn from the book. Official Team Topologies page; Publisher's page.
9. Michael E. Gerber, The E-Myth Revisited: Why Most Small Businesses Don't Work and What to Do About It, HarperCollins, 2009 reissue, 288 pages, ISBN 9780061741654. The full text of the book was not available; the bibliographic description and a short excerpt from the publisher's sample cover the first chapter. Used for the limited point about the difference between a professional operation and the systematic management of it; our documentation policy is not attributed to the author. Google Books, edition and bibliography; First chapter excerpt, EMyth. A later, current EMyth article, "Implementing Small Business Systems and Processes", is used separately as a post-book practical interpretation of the process; no publication date shown on the page; accessed 23 September 2026. It is not evidence of the book's wording. EMyth.
10. OpenAI, Codex, public GitHub repository, commit 30fc6864cc1318121eca1843c217fe00ce1212f1, dated 23 September 2026; pinned README.md, AGENTS.md, docs/agents_md.md and docs/contributing.md; accessed 23 September 2026. Used as a verified example of different file roles within the same commit. Limit: one repository and one revision; this is not a recommendation to copy its structure. README; AGENTS.md; docs/agents_md.md; contributing guide.
11. LangChain, langchain-ai/docs, pinned commit 10b15a17b96744fa318eabdd83a1f0750f2f5b1c, dated 23 September 2026; AGENTS.md; accessed 23 September 2026. Used as an example of a repository whose own instruction file requires AGENTS.md and CLAUDE.md to be kept in sync and certain derived rules to be updated in the same PR. This is evidence of what the repository's team wrote, not an independent assessment of how well its process works. Pinned AGENTS.md.
12. Git, "Git data model" and "git-commit". Used to explain that a commit points to a snapshot tree and contains author, committer and timestamp fields. This metadata is part of the Git record, not independent proof of identity or time. Git data model; git-commit.