The repository instruments that carry an agent's context

four repository instruments carry the context

Because a full repository cannot fit within the context window, your engineering guidelines must be distributed across the four repository instruments, each designed to load at a specific point in the development cycle. Choosing the wrong format is the most frequent architectural mistake in repository design. For every guideline you write, evaluate its context cost and when that cost is incurred.

the rules file governs always-true constraints

A root rules file such as CLAUDE.md, AGENTS.md, or a tool-specific default like GEMINI.md, loaded at session launch: canonical build commands, directory layouts, and non-negotiable repository standards. In our trace, this root file was active before the user issued a command.

Because this file consumes context tokens on every single turn, excessive length carries a persistent penalty. Include only what must remain universally true across every session, delegating specific workflows to the other three instruments. Apply this practical filter: if an instruction does not apply universally across every possible task, move it into a skill or knowledge doc, leaving at most a brief pointer in the rules file.

a skill’s description is its interface

This repository’s procedures, including sync-docs, security-final-check, and the rest, are each a page long. They cannot all sit in the context window on every turn, yet the agent has to find the right one for a task it is only now reading. What has to be in the window so that it can? The runtime keeps only a name and a description per skill in the active context, and retrieves the body only after a match. Twenty skills cost twenty short descriptions in the window until one of them is needed.

A repository contains a skill named docs whose description consists entirely of the phrase “Documentation helper.” The body of the file defines the exact procedure for updating the project’s knowledge documents before recording a git commit. When a developer types “The refactor’s done, commit it,” the agent must decide which procedures to bring into context.

Because the agent never reads the body before choosing, the choice is made on the description alone: an operational procedure is completely unreachable if its description lacks the words of the task. The skill’s description is its entire interface.

Skills are found by their descriptions. Name them with active verbs and put explicit trigger conditions in the description. An agent discovers what it can do by matching the request against those descriptions.

Consider the description for this repository’s sync-docs skill, which executed near the end of our sample trace:

---
name: sync-docs
description: Update the knowledge/ documentation to match the code AFTER making any change in this repo — new features, refactors, convention changes, new files, or dependency changes. Use before committing. This repo keeps always-current documentation instead of a changelog; a commit that changes behavior without updating docs is incomplete.
---

Read that as: the name uses an active verb, and the description states what the workflow does and when to reach for it, in the exact vocabulary a task about committing code contains: the kinds of change that trigger it, the moment it runs, and the reason a commit without it is unfinished. The body underneath loads only after this description has matched.

You have met this dynamic across three architectural layers. An orchestrator routes work to sub-agents by evaluating each sub-agent’s description. A model selects external tools by matching user requests against tool descriptions in a Model Context Protocol schema. Here, an agent selects procedural skills by evaluating the skill’s description against the active prompt. Across all three layers, the description serves as the functional routing interface; if that description omits the operational terms of the task, routing fails silently even when the procedure itself is written without error.

knowledge docs provide retrieve-on-demand context

Present-tense technical documentation covering system architecture, database schemas, and shared conventions, retrieved only when relevant. These documents define how the software operates today; historical changes belong in the git commit log. In our trace, the initial skill loaded two specific references: index.md and the interactive modules specification. From these, the agent extracted core invariants and structural patterns without scanning the broader repository. It opened precisely the two documents relevant to the subsystem being modified.

plan artifacts preserve decisions across context resets

A structured implementation specification drafted prior to writing code: breaking changes into discrete phases, identifying architectural risks, and securing human approval before editing starts.

This discipline is the contract-first principle, carried from visual assets over to source code. You define the functional contract in structured text before generating the implementation, providing an objective standard for subsequent verification. This surfaces critical trade-offs early, when revising an architectural decision requires changing only a sentence of text. The plan captures immutable decisions (such as external API contracts, database schemas, and interface names) that are difficult to refactor later.

Plan artifacts also fulfill a second critical role in complex development tasks. When an implementation spans multiple sessions and exceeds a single context window, the written plan provides persistent memory. Episodic recall is factual grounding aimed at a storage system the agent maintains itself. The plan artifact embodies this mechanism directly: the agent writes its technical decisions to disk and reloads them later, preserving human-approved architecture across context resets.

your turn: plan the empty-question change

For the 500-character limit, the plan the agent writes, and a person approves, before any file changes:

Plan: refuse questions over 500 characters

Files
- the server: the POST /api/ask handler checks the question's length
  before anything reaches the agent
- a new test file for that handler

Expected behavior
- a 501-character question: HTTP 400, body "Please keep your question
  under 500 characters.", and no call to the agent
- a 500-character question: answered exactly as today

The test
- posts 501 characters, asserts the 400 and the message
- posts 500 characters, asserts a normal answer
- run before the edit: it fails (the baseline); run after: it passes

Approval: a person reads this plan and approves it before any file changes.

The artifact specifies the exact boundary case: 500 characters must succeed, while 501 characters must trigger the refusal. Writing down that single-character boundary prevents a reviewer from overlooking off-by-one errors during manual code review. Specifying that the server executes no call to the agent is an architectural requirement that the test suite can directly assert.

tool conventions share the pattern while filenames and loading vary

Coding environments share two parts of the pattern, a root rules file loaded at session start and skills found by their descriptions, while their file conventions, scoping rules, and automatic loading behaviors differ (as checked against each tool’s documentation on 2026-10-11).

Claude Code reads CLAUDE.md and CLAUDE.local.md files located in or above your working directory at session launch, while files in subdirectories load on demand. With version 2.1.277 or later, it also reads AGENTS.md, by default only when no CLAUDE.md exists in the working directory or above it. Claude Code indexes project skill definitions from .claude/skills/, loading full skill procedures only when a task matches the skill’s description.

Google Antigravity reads workspace rules from .agents/rules/ and from AGENTS.md files at the workspace root and in subdirectories, operates across command-line, code editor, and browser sessions, and produces structured implementation plans as Markdown artifacts. It reads skills from .agents/skills/, loading full content on activation.

OpenAI Codex, Cursor, and OpenCode read repository instructions from AGENTS.md, though their scoping and secondary locations vary. Codex joins the files it finds from the repository root down to the working directory. Cursor also evaluates rules in .cursor/rules using configurable modes, so only rules marked Always load on every session. OpenCode searches upward for AGENTS.md and falls back to CLAUDE.md if none is found. Gemini CLI reads GEMINI.md by default and reads AGENTS.md only when you list it under context.fileName in settings.json.

Codex, Cursor, OpenCode, Gemini CLI and Antigravity all read skills as SKILL.md files in .agents/skills/, where the runtime reads names and descriptions first and loads the procedure body on demand. Cursor and OpenCode also read .claude/skills/ directly, the directory Claude Code uses. A skill placed in both directories therefore reaches every tool named here. A framework can ship its own procedures in this format, and an install step that copies its skills into both directories puts those procedures within reach of any coding agent in your project.

MCP servers expose external development utilities as structured JSON schemas across standardized transport boundaries.

Across every environment, the precision of your descriptive text directly dictates whether the agent selects the correct tool for the job.

what compounds is the repository’s context

The eleventh checkpoint feature on this site went faster than the first, and the model that wrote it had not changed by one number. Where did the improvement go? It went into the repository’s context: the rules file, the skill descriptions, the knowledge docs, and the plan artifacts that each finished feature leaves behind and the next one reads. The machine gets better at this repository while learning nothing, because every run starts from the same weights and the only thing that can differ between feature one and feature eleven is what the repository puts in the prompt.

Two foundational rules keep that deposit true over time, both deriving directly from the execution mechanics of the context window.

First, consider documentation health. Knowledge docs form the long-term memory of your codebase, and the verification standard for memory applies directly: a memory system must never store fabricated data, and an agent must explicitly signal when information is missing. An outdated documentation file represents a fabricated memory. It provides an authoritative, confident, yet inaccurate historical account. When a subsequent agent session reads that stale file into its context window, those tokens bias the output probabilities just as legitimate context would, leading the agent to implement code against an obsolete architecture. You can update this documentation with minimal friction at precisely one moment: within the exact commit that alters the underlying behavior.

Docs ship in the commit that changed the code. A feature whose docs still describe the old behavior is unfinished, whatever the tests say, because the repository now holds a false memory.

Suppose the web app’s knowledge doc says “POST /api/ask passes the visitor’s question to the agent”, and you commit the 500-character change with its test, but omit the doc change. The next session, asked to add a rate limit to the same handler, opens that doc, reads that every question reaches the agent, and plans its change against behavior the handler no longer has.

That one doc line is the false memory. It is cheapest to fix in the commit that changed the behavior, and the fix is one line: “questions over 500 characters are refused with HTTP 400 and never reach the agent”.

Second, consider the planning phase. The plan artifact is the human gate. It establishes clear specifications, surfaces critical engineering trade-offs, and requires explicit review before code generation begins. Securing approval before editing starts is a workflow policy this repository chose to adopt, and what makes it hold depends on where you write it. In our repository, the rules file establishes this policy as an explicit standard. A prompted rule shifts the model’s conditional probabilities toward pausing for review, and a later prompt that nudges it to start editing can shift them back. Application code enforces the gate deterministically: a Claude Code PreToolUse hook blocks an action regardless of what the model decides, and a custom harness can inspect the plan artifact for an explicit approval line before dispatching any write. It is the contract-first discipline applied directly to source control.

We applied this exact methodology to build the course you are reading. Every chapter in this curriculum was implemented through a human-reviewed plan artifact, verified in a running browser environment, and committed alongside its updated documentation.

what you can do with this today

You can immediately apply these architectural concepts to evaluate any agent or repository workflow:

What did it run? When an agent claims an implementation is complete, demand empirical evidence from outside the model: exit codes, passing test logs, or HTTP response statuses. If it simply read the code diff, direct it back to step three of the loop.

Which instrument does this line belong in? When writing a new guideline, determine when it needs to be present in context. If it applies universally: place it in the rules file, keeping it concise. If it governs a specialized task: write an on-demand skill, named with an active verb and triggered by explicit descriptive keywords. If it describes current system behavior: maintain it in a present-tense knowledge document. If it guides an active implementation: record it in a plan artifact approved prior to editing.

Would this skill fire? Review your skill descriptions from the model’s perspective, matching them against realistic user prompts. If the keywords do not align, revise the description to reflect actual prompt terminology.

Are the docs true after this commit? If an implementation modifies system behavior without updating the corresponding documentation, the task remains incomplete, and future sessions will inherit that technical debt.

Here is the complete workflow summarized for reference:

your idea
  → PLAN      a plan artifact: phases, risks, the judgment calls listed for veto
              a human approves before any file changes (a chosen workflow policy)
  → EDIT      targeted changes to named files
              [rules file always in the window · skills fire on description match
               · knowledge docs opened for the subsystem being touched]
  → RUN       build, lint, serve — make the change real
  → VERIFY    facts from outside: exit codes, failing test names, a page in a browser
              fail → back to EDIT carrying the failure text
  → COMMIT    code and docs in one commit, always; the gate skills last
  → DEPOSIT   a sharpened skill · a doc section · a decision entry
              the next feature starts further ahead

---

what parts 1 and 2 have built

Across these eleven modules, you have developed the core capabilities required to build reliable agentic systems.

Part 1 took you from a model to an agent: what a model actually calculates, a model running on your own hardware, and the written instruction that commits it to a single objective, then rigorous evaluation across five core variables and your first multi-agent topologies.

Part 2 developed the engineering craft at full scale, implementing durable architectures. You built declarative multi-agent systems, context-resilient memory, dynamically discovered tools across trust boundaries, independent multimodal evaluators, multi-channel fact verification, and self-verifying coding workflows.

A single architectural principle unites these systems: every guarantee you require from an AI system is a written constraint you can audit and test. Reliability comes from explicit rules validated against execution logs, schema validators, and automated test suites, never from polite prompting or assumptions about model behavior.

None of this relies on unverified trust. Throughout Part 1 and Part 2, you observed these mechanisms operating directly: how priors fill missing context, how context windows silently drop tokens when saturated, and why automated critique requires an isolated context rather than a simple follow-up question.

The last module of this part introduces quantitative evaluation. Up to this point, you have evaluated agent behavior through direct inspection and manual verification. While effective for development, manual inspection cannot scale across production workloads. The Grader and the Ledger transitions from qualitative observation to statistical measurement: building representative evaluation datasets, deploying independent automated judges, computing rigorous confidence intervals, and integrating automated deployment gates that hold a regressing change back before code reaches production, decided by judges whose verdicts you trust only once human labels have calibrated them.

Continue to The Grader and the Ledger, explore the full syllabus, or read ahead into Token by Token with an engineer’s perspective; the mechanics underneath everything you have built take on practical significance once you have built production systems on top of them.