Correction, October 19, 2026. An earlier version of this article reported a deployment period, pull-request counts and percentage improvements that we could not reproduce from our repository, and described checks our tooling did not perform. We took it down the same day. This version reports only what the code does, and every repository figure below is recomputed from git by a script in our (private) repository,
scripts/context/anc-essay-facts.mjs, at the commit cited.
We build Proof in a TypeScript monorepo of about forty packages and apps, and AI coding agents write much of the code. The agents read our instruction files. They still break things those files tell them not to break, mostly in parts of the repo they have not seen in the current session.
Agent-Native Context (ANC) is the convention we started on 2026-10-16 to make some of those instructions checkable. This post describes the format, the checks, how the contract reaches the agent, what we found in the first days, and what it does not do.
Why prose instructions are not enough
Three things push us toward structure.
Instruction files are context, not enforcement. Claude Code’s own documentation says of CLAUDE.md files that “Claude treats them as context, not enforced configuration.” The same is true of AGENTS.md and Cursor rules. A rule written as a sentence is a request.
Long context dilutes it. Liu et al. (2024) found that language models use information at the start and end of a long input better than information in the middle. An instruction file that grows with every incident competes with everything else in the window.
Prose drifts from the code. A sentence saying “this package depends only on X” is not compared with package.json by anything. It goes stale silently, and the next agent reads the stale version.
Nested instruction files already address part of this: AGENTS.md lets the nearest file win, Claude Code loads a subdirectory’s CLAUDE.md when it touches files there, and Cursor scopes rules by glob. ANC keeps that nearest-file idea and changes what the file holds.
The contract
Each module gets a CONTEXT.agent.yaml in its directory. It is validated against a JSON Schema. A minimal one:
module:
name: money
package: "@example/money"
purpose: Integer-cent money arithmetic shared by every app
domain: payments
path: packages/money/
dependencies:
reads_from: []
writes_to: []
invariants:
- id: money-01
rule: Amounts are integer cents; no floating-point money math
type: data
test: node --test packages/money/test/cents.test.mjs
authority:
autonomous:
- Add helpers that keep amounts in integer cents, with tests
founder_approval:
- Change rounding rules or the unit amounts are stored in
blast_radius:
level: high
downstream: [web]The parts that matter: each invariant has a test, a shell command run from the repository root that exits 0 when the invariant holds (or null when no program can check it). dependencies lists the modules this one uses. authority separates what an agent may do alone from what needs a person.
What the tooling checks
anc check fails when:
- a contract does not match the schema, or its
authoritylists are empty; - a contract still contains the placeholder text that
anc initwrites; - a dependency the contract says is imported is missing from
package.json, or a workspace package in the module’sdependenciesis missing from the contract (both directions); - the workspace packages form a cycle;
- an invariant’s test points at a file or an npm script that does not exist, or cannot fail (
true,exit 0, or a command ending in|| true).
anc verify runs the test commands for the modules you name, for every module touched since a git ref, or for all of them. anc selftest builds throwaway workspaces, plants one violation for each rule above, and fails unless every rule catches its plant.
Getting the contract in front of the agent
anc query <file> prints the nearest contract in a compact form. For Claude Code we ship a PreToolUse hook on edit tools. Before the agent edits a file, it returns that module’s contract as additionalContext. That field is how a PreToolUse hook gets text to the model; plain output from such a hook is not shown to it, which our first version of the hook got wrong. The hook sends a module’s contract at most once every 30 minutes in a session, so it can come back after the conversation is compacted, and it never blocks an edit. For other agents, a rule tells them to run anc query before editing and anc verify before finishing.
Beyond package boundaries: code topology and wire tracing
A package-level contract tells an agent what invariants govern the module, but not what is happening inside the specific file it is editing. To solve blind local navigation, we expanded ANC with source-level AST wire tracing (anc trace). We discuss the runtime classification, JSX component trees, API routing, and tenant-scoping audits in our follow-up article: Code Topology & AST Wire Tracing.
What we found in the first days
At commit bfd986d (October 19), the repository had 40 contracts holding 197 invariants. 161 of those invariants have a test command and 36 have none.
The split we learned the most from: 53 of the tests name something specific (a test file, a script, or a named check), and 108 run a whole package’s tests, typecheck, lint or build. A whole-package run tells you the package still passes. It does not tell you the invariant holds. Most of our “invariant tests” are the first kind of evidence dressed as the second, and the format made that visible.
The first dependency pass (53e278f) added 1 dependency that a package imported but did not declare and removed 3 that were declared but unused, across 3 packages.
Making manifests honest has a side effect. In bb343ef we declared an import that was real but had been missing from a package.json. The declaration closed a cycle between three packages, and the repository-wide typecheck and test runs failed until de04f83 broke the cycle two days later. Our contract check compared contracts with manifests and never looked at the package graph. We added the cycle check because of it.
When we added the test-oracle check, it found 3 invariants whose test pointed at a file or npm script that did not exist. Those tests could never have run, and nothing had noticed.
What ANC does not do
anc checkstill verifies manifests, not a complete static call-graph. The dependency parity check comparesCONTEXT.agent.yamlwithpackage.json. Whileanc traceparses individual files and their relative imports for runtime wires, it is not an end-to-end typechecker or bundler; tools like knip remain responsible for identifying unreferenced dependencies or unused exports.- It does not enforce
authority. That section is context for the agent. We block edits to protected paths with a separate path-based hook and permission rules. - It cannot judge a test. A test that exists and passes can still miss the invariant, as the whole-package numbers show.
- The schema allows self-reported health grades. We no longer show them to agents and do not rely on them.
- We have not measured its effect. We have no before-and-after data on how often agents break invariants with and without ANC. It has been used in one repository, for days.
Related work
The nearest-file idea comes from nested AGENTS.md and CLAUDE.md files. In our repository each CONTEXT.agent.yaml sits beside a CONTEXT.md written in the style of Jake Van Clief and David McDermott’s Interpretable Context Methodology (2026), which treats folder structure and per-folder context files as the architecture for agent work. The Markdown file explains; the YAML file is checked. The vocabulary of invariants and checks borrows from Bertrand Meyer’s Design by Contract (1992); our checks are executable tests, not proofs.
Try it
The specification, the JSON Schema and the reference CLI are on GitHub at Proof-Company/agent-native-context under the MIT license. The specification is also at /specs/anc-specification.md and the schema at /schemas/context-agent.schema.json. It is not on npm; clone it and run node bin/anc.mjs. The repository includes a two-package example workspace.
References
- Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F., & Liang, P. (2024). Lost in the middle: How language models use long contexts. Transactions of the Association for Computational Linguistics, 12, 157–173.
- Meyer, B. (1992). Applying “design by contract”. Computer, 25(10), 40–51.
- Van Clief, J., & McDermott, D. (2026). Interpretable Context Methodology: Folder Structure as Agentic Architecture. arXiv:2603.16021.
- Claude Code documentation: memory (code.claude.com/docs/en/memory) and hooks (code.claude.com/docs/en/hooks). AGENTS.md: agents.md.
Ready to see AI in action?
Proof AI handles dispatch, documentation, vision, and operations — so you can focus on the work.