Skip to main content

03.18Practice

Progressive disclosure for AI agent context

How AR Labs layers project documents so AI agents and people load the most constraining context first: outcome, strategy, active work, then tasks.

Four slabs stacked widest on top: outcome, strategy, active work, tasks, with an arrow showing the loading order.Four slabs stacked as an inverted pyramid, widest on top: outcome, strategy, active work and tasks, with an arrow showing the order an agent loads them.PRACTICE03.17LOAD THE MOSTGENERAL FIRSTDRAWINGENG-03.17SUBJECTprogressive disclosureSHEET17 OF 26 · AR LABS1 · OUTCOME2 · STRATEGY3 · ACTIVE WORK4 · TASKSLOAD ORDERSTABLECHANGES OFTEN
On this page
  1. The problem it prevents
  2. The layers
  3. Rules that keep the layers accurate
  4. Where it came from

Progressive disclosure is how AR Labs gives an AI agent the context it needs, in the order it needs it. Every project documents itself in layers, ordered from the most general and stable to the most specific and changeable. An agent entering a project reads them in that order, so what it loads first constrains how it reads everything after, and it never has to load the whole project to start work. The same order works for a person picking the project up cold. It is one practical form of context engineering: choosing what goes into a model's context window at each step.

The problem it prevents

An agent's context window is finite, and what goes into it first has the most influence on what follows. Loading everything wastes the window; loading the wrong thing first steers the agent. Documentation also decays: a passage that says which tool or design is current goes stale silently and then misleads the next reader. Facts recorded outside a project's own documents are invisible to whoever opens the project next.

The layers

FIG. 01
flowchart TD
  L1["1. Entry file: what does success look like?"] --> L2["2. STRATEGY.md: how are we pursuing it now?"]
  L2 --> L3["3. Active work: task graph, build log or plan"]
  L3 --> L4["4. Individual tasks"]
Level File Answers Changes
1 AGENTS.md (with CLAUDE.md pointing at it) What does success look like for this project? Rarely
2 STRATEGY.md How are we pursuing it right now? On a change of approach
3 Depends on the project type What is actively being worked? Over days and weeks
4 The task tracker What are the individual units of work? Over hours and days

Level 3 takes the form the project needs: the dependency graph of tasks for a development project tracked in Beads, a BUILD.md milestone log for one that is not, a plan for a content project, a findings file for research.

Each level links explicitly to the next. The entry file points to the strategy; the strategy points to the active-work file. An agent never has to guess where to go.

One entry file for every agent. The authoritative instructions live in AGENTS.md, which several coding agents read by convention. CLAUDE.md is a relative symbolic link to it, so Claude Code reads the same document and there is only one copy to edit.

Strategy is mandatory, even for small projects. It is updated when the approach changes, when evidence builds up, or when a new constraint appears, and each change of approach gets a dated entry with its reason. Session-level progress never goes in the strategy; it goes in level 3 or in task notes.

my-project/
  AGENTS.md          # outcome, map of the docs, rules for this project
  CLAUDE.md -> AGENTS.md
  STRATEGY.md        # current approach, log of changes of direction
  DESIGN.md          # architecture record
  build/
    specs/           # per-task specs, archived when tasks close

Rules that keep the layers accurate

  • A fact belongs in the document that loads when the fact is relevant. Deployment targets, architecture caveats and technical decisions go in that project's own documents, where they arrive exactly when someone opens the project.
  • One authoritative document per concern. Split documents by how often they change and what changes them, not by topic. Downstream documents cite and do not restate, carrying a pointer and the two or three facts their own job needs.
  • Write durable pointers, not decaying snapshots. Keep detail that changes in one place and have everything else point to it. When a design changes direction, rewrite the affected passage wholesale; patching the top line leaves the document asserting the old design and the new one at once.
  • Version-scoped documents stay scoped. A version's build plan is frozen to that version. Future work belongs under the target version's completion gate in the strategy, not in a sibling version's plan.
  • A log is evidence, not analysis. A log keeps timestamped events at the source's own granularity, with observation and interpretation kept visibly apart. Compressing a log feels like tidying and destroys what it exists to preserve.
  • Match detail to the decision in front of you. Big picture first, then approach, then chunk-level detail when work commits to an area. Do not pre-list every file ahead of the work that needs it.

Where it came from

Progressive disclosure is an interface design principle: show the general first and reveal detail on demand. This page covers the layering inside one project; the repository as a second brain describes how the same pattern organises the whole repository our agents work in. We apply it to context loading for AI agents, where the order in which information arrives shapes how a model uses it. Matt Pocock's advice to keep an agent's standing instructions small, so they do not use up the part of the context window where the model still works well, points the same way.