Short, scarce, direct wins.
Lengthening, diluting, or re-framing a signal reduces compliance. Write the shortest rule that is still unambiguous.
AIGX Foundation // Public Spec v1.1
AIGX is the
AIGX is the
context genome
for AI agents.
AIGX gives coding agents a short, local, structured memory of your codebase - rules, boundaries, gotchas, checks, and domain facts - without polluting source files.
$ npx create-aigx
The problem
AI agents do not only need bigger context windows. They need better context shape.
Today, project context is scattered across READMEs, Cursor rules, prompts, comments, stale docs, issue threads, and tribal knowledge. Agents miss boundaries, invent domain facts, cross architecture lines, and edit files without knowing the local constraints that matter.
context/scattered · status: unreliable
✗ README.md - aspirational, rarely current
✗ .cursor/rules - one IDE, glob-scoped
✗ prompts - ephemeral, per-session
✗ // comments - clutter every diff
✗ stale docs - contradict each other
✗ issue threads - unsearchable at edit time
✗ tribal knowledge - lives in one head
A thousand-line CLAUDE.md buries the one rule that
mattered for this file three scrolls away - and a selective reader never scrolls to it.
.aigx/ · status: addressed & tested
AIGX exists because context must be:
- ▸close to the edit - retrievable at the file being changed.
- ▸short enough to obey - five words beat five paragraphs.
- ▸structured enough to parse - stable, citable rule ids.
- ▸honest enough to test - every rule earns its place by measurement.
What AIGX is
A local context system for codebases.
A centralized .aigx/ directory with XML-tagged files:
a read protocol, per-concern rule files, per-domain cards, and a lean per-file boundary index.
Your source files stay completely clean.
.aigx/
├─ protocol.aigxrequired
├─ files.aigxkeystone
├─ product.aigx
├─ architecture.aigx
├─ data.aigx
└─ testing.aigx
src/features/suppliers/
└─ suppliers.aigx # domain card
# src/** → untouched. nothing injected.
protocol.aigx The read order. One screen. The first thing an agent reads.
files.aigx The keystone: maps each editable file to its boundary, gotcha, and completion checks.
<concern>.aigx Per-concern rule files: architecture, data, product, auth, cache, testing.
domain.aigx Per-domain cards colocated near feature folders.
files.aigx · one entry per editable file
<file path="src/features/meetings/bookMeeting.ts" domain="meetings">
<role>Book a meeting (validate slot + contact)</role>
<forbid pri="CRIT">NEVER import internal/* (deep import = ARCH-2)</forbid>
<gotcha>get contact_email from the suppliers PUBLIC api</gotcha>
<check>ARCH-2 ARCH-4 DATA-2 TEST-1</check>
</file>One lookup gives the agent the binding constraint for that file: what it must never do, the single worst pitfall, and the ids to verify before it finishes.
How agents use it
Five steps, selectively read.
AIGX works because agentic models read selectively. The important rule must be one grep away from the file being edited - not buried in a thousand-line document.
-
Read protocol
The agent opens protocol.aigx - the one-screen read order.
protocol.aigx -
Read rule files
It loads only the concern files the task actually touches.
architecture.aigx · data.aigx -
Resolve each file
For every file it will edit, it looks up that file's entry.
files.aigx → <file> -
Read the domain card
It reads the nearest per-domain card for feature context.
suppliers.aigx -
Implement & verify
It changes minimally, then verifies every <check> id holds.
check: ARCH-2 …
O(1) per edit. The boundary index is meant to be looked up, not ingested.
An agent's context cost is one resolution per edited file - independent of index size - so it scales
from a 35-file app to a 50,000-file monorepo.
Benchmark proof
Won by discipline, not by magic.
One real codebase. Rules held identical. Only the context format varies, with semantic parity machine-enforced. Scoring is deterministic and tamper-proof - hidden tests injected after the agent finishes, then removed. Powered to n=60 across two models.
95.4
mean final score
98.6%
hidden-test pass
60
runs per cell (n)
24
challengers beaten
| format | mean | pass@1 | hidden | arch-viol |
|---|---|---|---|---|
| aigx_terse | 95.4 | 0.92 | 98.6% | 8% |
| md | 95.1 | 0.80 | 96.4% | 0% |
| exifai_v2 | 94.6 | 0.80 | 96.1% | 3% |
| aigx_v9 | 93.6 | 0.77 | 94.3% | 10% |
| xml | 93.1 | 0.80 | 93.8% | 13% |
| format | mean | pass@1 | hidden | arch-viol |
|---|---|---|---|---|
| aigx_terse | 93.5 | 0.78 | 96.0% | 7% |
| aigx_v9 | 92.8 | 0.70 | 92.6% | 5% |
| exifai_v2 | 92.4 | 0.67 | 90.2% | 0% |
| xml | 92.3 | 0.75 | 93.3% | 8% |
| md | 92.2 | 0.70 | 93.6% | 10% |
Straight about the statistics. The result is not "AIGX destroys everything." At n=60 the top
formats are a statistical tie on the mean. AIGX wins because it is robust, simple to author,
cross-model friendly, and disciplined under hidden tests - the only format first on both
model tiers, and the only one ever measured in a controlled benchmark at all.
Full method & caveats →
The AIGX laws
The laws of agent context.
Each one is a finding from the benchmark, not an opinion - we varied one thing at a time and measured the effect on autonomous coding agents. They generalize beyond AIGX.
Locality beats position.
Where in the codebase a rule lives - addressed to the edit site - matters. Where in the document it sits does not.
Clean source beats injected source.
In-source comments add parse-noise and measurably hurt strong models. The genome stays in .aigx/; your diffs stay clean.
Boundaries belong near the edit.
The binding constraint for a file must be one lookup away in files.aigx, not buried three scrolls down a wall of prose.
Generate from one source.
Context must come from one canonical record and stay parity-checked, so it cannot silently rot as the code moves.
A benchmark beats a belief.
Every "SHOULD" in the spec is earned by a controlled measurement, not asserted. n=30 rankings are noise; power them up.
Comparison
Fair, technical, and not a strawman.
Every format here gets something right. AIGX is a synthesis of their lessons - not a replacement for the ones that work. Adopt the substrate, not the vendor.
| Format | Strength | Weakness | AIGX lesson |
|---|---|---|---|
| Markdown | Universal, human-friendly, great on strong models for prose reasoning. | Grows into a thousand-line wall; the rule for this file is buried and never read. | Keep the prose - but address the binding rule to the file in an index. |
| Cursor MDC | Glob-scoped rules, IDE-native, structured front-matter. | Vendor-locked to one editor; scoping is by glob, not per-file boundary. | Per-file precision should be tool-agnostic, not tied to one IDE. |
| YAML | Structured, easy to parse, familiar to config tooling. | Indentation-fragile for LLMs; no notion of an edit-site boundary. | Structure helps, but the unit that matters is the per-file entry. |
| XML | Explicit, unambiguous tags; rigid scaffold a weak model can follow. | Strong models rationalize around rigid tags; worst arch-discipline on Sonnet. | Use tags for parseability, but make them directives at the edit site. |
| EXIFAI V2 | Co-locates context physically next to the code it governs. | In-source injection adds parse-noise and cost a strong model points. | Locality is right; injecting into source is not. Address, do not inject. |
| EXIFAI DNA | Dense, encoded sidecar - the conceptual ancestor of the genome idea. | Over-compressed encodings washed out or hurt; complexity without payoff. | Simpler wins. Every embellishment must prove it helps. |
| AIGX terse | Per-file boundary index + concern files; nothing injected; one screen to read. | You must author and CI-lint the index so it tracks moving files. | The robust local optimum: first on both model tiers, survived every challenger. |
Open standard
AIGX should belong to builders.
The AIGX Foundation exists to publish the spec, benchmark context formats, collect examples, and help teams make AI agents more reliable - without locking the format to one model, one IDE, or one vendor. The format is MIT-licensed and tool-agnostic by design.
Docs
Everything to ship a genome.
The spec, a working generator, the benchmark harness, a complete TypeScript example, and the read protocol - all open and reproducible.
Quickstart
Copy the starter genome and point any agent at it in under 60 seconds.
open →Spec v1.1
The normative format definition: layout, grammar, rule ids, conformance.
open →Generator
The one-line agent addendum that makes any agent AIGX-aware.
open →Benchmark harness
Controlled ablation, deterministic scoring, n=60 across two models.
open →TypeScript example
A complete real-world genome with per-domain cards.
github ↗Agent read protocol
The one-screen protocol.aigx an agent reads first.
open →FAQ
Short answers for humans and AI systems alike.
open → FAQ
Questions, answered straight.
01What is AIGX?
AIGX (AI Genome Exchange) is an open, MIT-licensed context format for AI coding agents. It stores a codebase's rules in a centralized
.aigx/ directory and adds a per-file boundary index - for each source file, the exact rules, forbidden imports, and gotchas that apply there. To our knowledge it is the only context format validated to win a controlled benchmark.02Is AIGX a prompt format?
No. AIGX describes a codebase, not a single prompt. It is a persistent, structured memory an agent reads selectively at the edit site. You make any agent AIGX-aware with one instruction line added to its existing config; the agent then looks up only the context it needs per file.
03Is AIGX better than Markdown?
Honestly, the top formats are a close cluster at matched power - AIGX is not a blowout over good Markdown. Its defensible edge is being first on every primary metric on both a weaker and a stronger model, surviving ~24 deliberate challenger variants, and being the simplest to author. A reproducible tie-at-the-top that holds across model tiers beats a fragile, format-specific spike.
04Why not put context inside source files?
We measured it. In-source
// NEVER import X comments were neutral on the weak model and cost the strong model points (parse-noise), while cluttering every diff. The genome lives entirely in .aigx/ so your code and your diffs stay clean.05Why XML tags?
For parseability and stable, citable rule ids like
ARCH-2. A genome is read by an LLM, not a strict XML parser, so well-formedness is recommended but not schema-enforced. Tags make the binding constraint for a file machine-locatable in one lookup.06What is aigx_terse?
It is the winning design the benchmark converged on: a lean per-file boundary index (role + a rare forbid + one gotcha + check-ids) plus terse per-concern rule files, with nothing injected into source. Every embellishment tested on top of it - salience tiers, routing tables, prose re-renderings - washed out or hurt.
07Does AIGX work outside coding agents?
The format is language- and domain-agnostic plain text. Its validated use is codebase context for coding agents, but the underlying laws - short and scarce, locality over position, one canonical source, measure don't assert - apply whenever you write context for an AI system.
08Is this an open standard?
Yes. AIGX is MIT-licensed and tool-agnostic by design. The Foundation exists to publish the spec, benchmark context formats, and collect examples - without locking the format to one model, one IDE, or one vendor. Use it, fork it, build products on it.
09How do I add AIGX to an existing repo?
Copy the starter
.aigx/ into your repo root, fill in files.aigx with one entry per file an agent realistically edits, and add the one-line agent addendum to your AGENTS.md / CLAUDE.md / Cursor rule. Run the bundled linter in CI so a moved file fails the build until its entry is fixed.10How is AIGX different from llms.txt?
llms.txt is a docs index for answer engines - it points to your documentation. AIGX encodes codebase rules and boundaries for an agent that edits the code: per-file forbidden imports, gotchas, and verification checks. Different jobs; they compose well. This very site ships an llms.txt too.