Vai al contenuto
TakoAPI
Torna alle skill

AIGX

di Lolner95

Cursor
—Non ancora valutato
La tua valutazione

Sintesi

Open, MIT context format for AI coding agents: centralized .aigx/ rules + a per-file boundary index that targets the right rules, forbidden imports, and gotchas to each file. The only context format validated in a controlled benchmark. Tool-agnostic; nothing injected into your source.

Descrizione

<p align="center">
  <img src="assets/logo.svg" alt="AIGX — AI Genome Exchange" width="560" />
</p>

<p align="center">
  <strong>The open, benchmark-validated context format for AI coding agents.</strong><br/>
  A <code>.aigx/</code> genome describes how your repo works — rules, per-file boundaries, gotchas —
  so any AI agent inherits your conventions and behaves like a senior engineer who already knows the code.
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/tools-MIT-22c55e.svg" alt="MIT"/></a>
  <a href="standard/LICENSE"><img src="https://img.shields.io/badge/spec-CC--BY--4.0-3b82f6.svg" alt="CC-BY-4.0"/></a>
  <a href="https://www.npmjs.com/package/@aigx/cli"><img src="https://img.shields.io/npm/v/@aigx/cli?label=npm%20%40aigx%2Fcli&color=22c55e" alt="npm @aigx/cli"/></a>
  <a href="https://pypi.org/project/aigx/"><img src="https://img.shields.io/pypi/v/aigx?label=PyPI&color=3b82f6" alt="PyPI"/></a>
  <a href="https://crates.io/crates/aigx"><img src="https://img.shields.io/crates/v/aigx?label=crates.io&color=f59e0b" alt="crates.io"/></a>
  <a href="standard/AIGX-1.1.md"><img src="https://img.shields.io/badge/spec-v1.1-8b5cf6.svg" alt="Spec v1.1"/></a>
  <a href="BENCHMARK.md"><img src="https://img.shields.io/badge/benchmark-n%3D60%20·%202%20models-f59e0b.svg" alt="Benchmark"/></a>
</p>

<p align="center">
  <a href="#-quick-start">Quick start</a> ·
  <a href="#-install-the-toolchain">Install</a> ·
  <a href="#-the-proof">The proof</a> ·
  <a href="#-using-aigx-with-your-stack">Use it with your stack</a> ·
  <a href="standard/AIGX-1.1.md">Spec</a> ·
  <a href="docs/aigx-in-60-seconds.md">60-second intro</a>
</p>

---

**AIGX (AI Genome Exchange)** stores a codebase's AI-agent rules in a centralized `.aigx/` directory with a
per-file **boundary index** — and injects **nothing** into your source code. To our knowledge it is **the
only context format ever validated in a controlled benchmark**, where it was the **only format to rank
first on *both* a weaker and a stronger model** (Claude Haiku 4.5 *and* Sonnet 4.6, n=60) while surviving
**~24 deliberate attempts to beat it.**

> **Straight about the statistics (up front):** at n=60 the *top* formats are a **statistical tie** on the
> composite mean — AIGX is not a blowout. Its defensible edge is being the **most consistent across models,
> the most robust under challenge, the simplest to author, and the only option measured at all.**
> [Full scope, limitations & critique responses →](docs/limitations.md)

<sub>Spec **v1.1** (CC-BY-4.0) · Tools **MIT** · Tool-agnostic · Published on npm · PyPI · crates.io · Last updated 2026-06-20</sub>

---

## 🚀 Quick start

One command scaffolds a genome **and** wires up your AI agent(s):

```bash
npm create aigx
# or: npx create-aigx   (same thing)
```

It's interactive — pick Cursor / Claude Code / Copilot / Windsurf / Aider / `AGENTS.md`, choose CI, done:

```text
your-repo/
├── .aigx/
│   ├── protocol.aigx        ← the read protocol every agent loads first
│   ├── product.aigx         ← product context + freshness clause
│   ├── architecture.aigx    ← per-concern rules  (ARCH-* ids)
│   ├── engineering.aigx     ← hard-correctness invariants (ENG-* ids)
│   ├── files.aigx           ← ★ the per-file boundary index — fill this in
│   └── agent.aigx           ← self-maintenance rules for agents
├── .cursor/rules/aigx.mdc · CLAUDE.md · AGENTS.md · .windsurfrules · .aider.conf.yml
└── .github/{copilot-instructions.md, workflows/aigx-validate.yml}
```

Your source code is untouched. Then fill in **three things** — `files.aigx` (the keystone), your rules in
`architecture.aigx`, and `product.aigx` — and validate with `aigx lint`. The
[60-second intro](docs/aigx-in-60-seconds.md) and [authoring guide](docs/authoring-guide.md) walk you
through it; a complete real-world genome is in [`examples/sourcing-app/`](examples/sourcing-app/).

---

## 📦 Install the toolchain

AIGX ships **three independent reference implementations** (Node, Python, Rust) — install from whatever
registry you already live in. They're held in lock-step by a [conformance suite](tests/conformance/).

| You want… | Install | Gives you |
|---|---|---|
| **Scaffold a genome** | `npm create aigx` | the interactive scaffolder ([create-aigx](https://www.npmjs.com/package/create-aigx)) |
| **The CLI** (Node) | `npm i -g @aigx/cli` | the `aigx` command ([@aigx/cli](https://www.npmjs.com/package/@aigx/cli)) |
| **The CLI / validator** (Python) | `pip install aigx` | `aigx` + `aigx-lint` ([PyPI](https://pypi.org/project/aigx/)) |
| **The CLI / validator** (Rust) | `cargo install aigx` | the `aigx` binary ([crates.io](https://crates.io/crates/aigx)) |
| **Editor support** | VS Code Marketplace → **AIGX Language Support** | highlighting, hover, diagnostics, go-to-def ([editors/vscode](editors/vscode/)) |
| **Libraries** (Node) | `npm i @aigx/parser @aigx/lint` | programmatic parse + validate |

```bash
# zero-install runs, too:
npx @aigx/cli lint
npx @aigx/cli resolve src/features/auth/login.ts
```

> **Naming note:** npm reserves the bare `aigx` name, so the npm CLI is **`@aigx/cli`** — but the installed
> **command is `aigx`** everywhere. On PyPI and crates.io the package is plain `aigx`.

---

## 🔬 The proof

We built a controlled benchmark: one real TypeScript codebase with planted traps (deep-import violations,
dependency cycles, cross-tenant leaks, cache-ordering bugs, hallucination — 10 hard pitfalls), held
**constant**, with **only the context format varying** and **semantic parity machine-enforced** (every
format carries the identical rules). The subject is an autonomous agent that greps, edits, and runs tests.
Scoring is deterministic and tamper-proof.

| Format | Sonnet 4.6 mean | pass@1 | hidden | Haiku 4.5 mean | pass@1 | hidden |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| **🧬 AIGX** | **95.4** | **0.92** | **98.6%** | **93.5** | **0.78** | **96.0%** |
| Markdown | 95.1 | 0.80 | 96.4% | 92.2 | 0.70 | 93.6% |
| XML | 93.1 | 0.80 | 93.8% | 92.3 | 0.75 | 93.3% |
| In-source headers | 94.6 | 0.80 | 96.1% | 92.4 | 0.67 | 90.2% |

AIGX ranks first on mean, pass@1, *and* hidden-test pass on **both** models — **but the honest story is
consistency, not margin.** Markdown is great on Sonnet yet near-last on Haiku; XML is the rough reverse.
**AIGX is the only format first on both tiers** — and it survived **~24 challenger variants across 6
research rounds**, every one of which failed to beat it.

🔬 Full method, models, sample sizes, raw data, and the challenger log → **[BENCHMARK.md](BENCHMARK.md)** ·
honest caveats → **[docs/limitations.md](docs/limitations.md)**

---

## 🛠 Using AIGX with your stack

### 1 · Scaffold (interactive)

```bash
npm create aigx           # pick your agent(s) + CI, then fill in files.aigx
npm create aigx -- --yes  # non-interactive: scaffold everything (great for CI)
```

### 2 · The `aigx` CLI

Same six commands whether you installed via npm, pip, or cargo:

```bash
aigx init                 # scaffold a .aigx/ genome (also interactive)
aigx lint                 # validate: required files, resolving checks, no stale paths, no dup ids
aigx resolve <path>       # bounded output — print one file's boundary (role · forbid · gotcha · checks)
aigx doctor               # environment + genome health check
aigx format [--check]     # parity-safe whitespace normalization
aigx check-conformance    # report your genome's conformance level (G1–G4 + recommended)
```

```text
$ aigx resolve src/features/meetings/bookMeeting.ts
Applicable genome: .aigx
Role:   Book a meeting (validate slot + contact)
Forbid: NEVER import @/features/suppliers/internal/*   [CRIT]
Gotcha: get contact_email from the suppliers PUBLIC api, never the internal mapper
Checks: ARCH-no-deep-imports, DATA-integer-cents, TEST-failing-first
```

### 3 · Validate in CI

The genome can't silently rot — wire the validator into CI so a moved/renamed file fails the build:

```yaml
# .github/workflows/aigx-validate.yml
- run: npx --yes @aigx/cli lint        # or: pipx run aigx --root .  ·  or: cargo run -p aigx -- lint
```

### 4 · Editor support — `.aigx` highlights everywhere

| Editor | How |
|---|---|
| **VS Code / Cursor / Windsurf** | Install **[AIGX Language Support](editors/vscode/)** — highlighting, file icons, snippets, **rule-id autocomplete**, **hover** on rule ids, **go-to-definition**, inline **diagnostics**, format, and **AIGX: Resolve current file's boundary** |
| **GitHub** | `.aigx` already renders (via [`.gitattributes`](.gitattributes)); a [Linguist PR kit](editors/linguist/) is ready for first-class support |
| **Sublime Text · TextMate · Zed** | Ready-made configs in [`editors/`](editors/) — all from one canonical [TextMate grammar](editors/textmate/) (`source.aigx`) |

### 5 · Programmatic (build on AIGX)

```bash
npm i @aigx/parser @aigx/lint
```

```js
import { parseGenome } from '@aigx/parser'
import { lint } from '@aigx/lint'

const model = parseGenome('.')          // → canonical JSON data model (matches the spec's schema)
const { ok, errors } = lint('.')        // → the same checks as the CLI / aigx-lint
```

Python (`pip install aigx`) exposes the validator as `aigx-lint` and as `import aigx_lint`. For MCP clients
and codebase-memory agents, resolve a boundary as JSON before graph/search context — see
[JIT Context Hydration](docs/jit-hydration.md).

### 6 · Wire any agent

`npm create aigx` configures these for you; or copy one file from [`integrations/`](integrations/):

| Cursor | Claude Code | GitHub Copilot | Windsurf | Aider | Generic |
|---|---|---|---|---|---|
| `.cursor/rules/aigx.mdc` | `CLAUDE.md` | `.github/copilot-instructions.md` | `.windsurfrules` | `.aider.conf.yml` | `AGENTS.md` |

For a custom agent, paste the one-paragraph addendum from [the spec §12.3](standard/AIGX-1.1.md#123-the-agent-addendum).

---

## 🧬 How it works

```mermaid
flowchart TD
    A["Agent gets a task<br/>e.g. 'add a field to bookMeeting'"] --> B["Reads .aigx/protocol.aigx<br/>(the read order)"]
    B --> C["Reads the concern files<br/>the task touches"]
    B --> D["For EACH file it will edit,<br/>looks up its entry in<br/>.aigx/files.aigx"]
    D --> E["Gets the binding constraint<br/>at the edit site:<br/>forbid · gotcha · check-ids"]
    C --> F["Implements the change"]
    E --> F
    F --> G["Verifies every &lt;check&gt; id<br/>before declaring done"]
    style A fill:#1e293b,stroke:#475569,color:#e2e8f0
    style D fill:#7c2d12,stroke:#ea580c,color:#fed7aa
    style E fill:#7c2d12,stroke:#ea580c,color:#fed7aa
    style G fill:#14532d,stroke:#22c55e,color:#bbf7d0
```

The magic is **per-file addressability**. Agentic models read selectively — they grep, open the file
they're editing, and rarely re-scan a whole rule doc. AIGX makes the binding constraint for *that file*
retrievable in one lookup (`files.aigx`), instead of buried in prose — *and* keeps it out of your source.
We tested all three placements (global prose, inline-in-source, addressed index); **the addressed index
won, inlining lost.** ([the principles →](docs/principles.md))

### Anatomy of a genome

```xml
<!-- .aigx/architecture.aigx — rules with stable, citable ids -->
<aigx-architecture>
  <rule id="ARCH-no-deep-imports">Import features only through their public barrel. Deep imports are forbidden.</rule>
</aigx-architecture>

<!-- .aigx/files.aigx — THE KEYSTONE: the binding constraint per edited file -->
<aigx-files>
  <file path="src/features/auth/login.ts" domain="auth">
    <role>Handle login — validate credentials, issue a session</role>
    <forbid pri="CRIT">NEVER import @/features/billing/internal/*</forbid>
    <gotcha>token expiry is checked at read-time, not issue-time</gotcha>
    <check>ARCH-no-deep-imports ENG-tenant-scope</check>
  </file>
</aigx-files>
```

| Biology | AIGX |
|---|---|
| **Genome** — the code that builds & runs an organism | `.aigx/` — the context that runs an agent in your codebase |
| **Genes** with stable names | `<rule id="ARCH-2">` — rules with stable, citable ids |
| **Gene expression per tissue** | `files.aigx` — which rules are "expressed" at each file |
| **Sequencing / exchange** | a portable, readable record any agent can inherit |

---

## 📖 The standard

AIGX is a real, citable standard — not just a convention:

- **[standard/AIGX-1.1.md](standard/AIGX-1.1.md)** — the normative spec (20 sections, RFC 2119 language)
- **[AIGX-1.1.abnf](standard/AIGX-1.1.abnf)** — formal grammar (RFC 5234) · **[AIGX-1.1.schema.json](standard/AIGX-1.1.schema.json)** — canonical JSON data model
- **[media-type-registration.md](standard/media-type-registration.md)** — IANA template for `application/aigx`
- **[conformance](standard/conformance.md) · [security](standard/security-considerations.md) · [interoperability](standard/interoperability.md) · [change-control](standard/change-control.md)**

Dual-licensed: **spec text CC-BY-4.0**, **reference tools MIT** — so anyone can reimplement AIGX in any
language, freely. (`SPEC.md` is the informal, example-led companion.)

---

## How AIGX compares

| | **AIGX** | AGENTS.md / CLAUDE.md | Cursor `.mdc` | `llms.txt` |
|---|:---:|:---:|:---:|:---:|
| Per-file boundary targeting | ✅ **explicit index** | path globs (coarse) | glob-scoped | ❌ |
| Forbidden-import / gotcha per file | ✅ | ⚠️ prose only | ⚠️ | ❌ |
| Zero source-code injection | ✅ | ✅ | ✅ | ✅ |
| Tool-agnostic | ✅ | ⚠️ varies | ❌ Cursor-only | ✅ |
| **Benchmark-validated** | ✅ | ❌ | ❌ | ❌ |

AIGX isn't out to replace `AGENTS.md` — it's the **genome layer**: a richer, *measured*, per-file-precise
substrate you author once and can export down to a flat `AGENTS.md`/`CLAUDE.md` when a tool needs it.

---

## FAQ

**What is AIGX in one sentence?** An open context format that stores a codebase's AI-agent rules in a
centralized `.aigx/` directory with a per-file boundary index — the only such format validated to win a
controlled benchmark.

**How is it different from AGENTS.md / CLAUDE.md?** Those are usually one flat prose file. AIGX adds a
**per-file boundary index** so an agent gets the binding constraint *at the edit site*, and it's
tool-agnostic and exports down to those formats.

**Does it put comments in my source code?** No — deliberately. We measured that in-source headers *hurt* a
strong model. The genome lives entirely in `.aigx/`; your diffs stay clean.

**Is it really better, or are the top formats close?** Honestly, at matched power the top formats are a
tight cluster. AIGX's edge is **robustness, cross-model generalization, and simplicity** — and being the
one design that survived every challenger.

**Can I use it commercially / build tools on it?** Yes — tools are MIT, the spec is CC-BY-4.0. No permission
needed.

---

## Ecosystem

| Package | Registry | Install |
|---|---|---|
| [`@aigx/cli`](https://www.npmjs.com/package/@aigx/cli) | npm | `npm i -g @aigx/cli` → `aigx` |
| [`create-aigx`](https://www.npmjs.com/package/create-aigx) | npm | `npm create aigx` |
| [`@aigx/parser`](https://www.npmjs.com/package/@aigx/parser) · [`@aigx/lint`](https://www.npmjs.com/package/@aigx/lint) | npm | `npm i @aigx/parser @aigx/lint` |
| [`aigx`](https://pypi.org/project/aigx/) | PyPI | `pip install aigx` |
| [`aigx`](https://crates.io/crates/aigx) | crates.io | `cargo install aigx` |
| **AIGX Language Support** | VS Code | Marketplace → *AIGX Language Support* |

Plus zero-dep tools in [`tools/`](tools/): `aigx-lint` (validator/resolver), `aigx-sync` (rename pre-commit
hook), `aigx-mcp` (stdio MCP bridge), `aigx-export` (safe `.aigx`/Markdown serializer).

<details>
<summary><strong>Repository layout</strong></summary>

```text
aigx/
├── standard/        ← the NORMATIVE standard (spec, ABNF, JSON schema, IANA, conformance…)
├── SPEC.md          ← informal, example-led spec (points to standard/)
├── packages/        ← npm workspace: @aigx/cli, @aigx/parser, @aigx/lint
├── bin/create-aigx.mjs · pyproject.toml · crates/aigx/   ← npm / PyPI / Cargo entry points
├── editors/         ← VS Code ext, TextMate grammar, Sublime, Zed, Linguist kit
├── tools/           ← aigx-lint, aigx-sync, aigx-mcp, aigx-export (zero-dep)
├── tests/conformance/  ← cross-validator suite (Python · Node · Rust agree)
├── integrations/    ← Cursor, Claude Code, Copilot, Windsurf, Aider, AGENTS.md, CI
├── examples/        ← sourcing-app (full), minimal
├── docs/            ← 60-seconds, authoring guide, principles, limitations, migration, jit-hydration
├── .aigx/           ← this repo's own genome (AIGX uses AIGX)
└── RELEASING.md     ← how each package is published
```
</details>

---

## Status

- ✅ **Spec v1.1** — stable; normative standard with ABNF, JSON schema & IANA media type
- ✅ **Published** — npm (`@aigx/cli`, `create-aigx`, `@aigx/parser`, `@aigx/lint`) · PyPI (`aigx`) · crates.io (`aigx`)
- ✅ **3 reference validators** (Node · Python · Rust) agreeing on a conformance suite
- ✅ **Editor support** — VS Code extension + one canonical grammar reused across Sublime/TextMate/Zed/Linguist + GitHub highlighting
- ✅ **Benchmark** — n=60 on two models, reproducible, honest
- 🔜 VS Code Marketplace + Open VSX listing · Language Server (LSP) · monorepo-scale benchmark · Python/Go examples

Want to help? [CONTRIBUTING.md](CONTRIBUTING.md) · [open an issue](https://github.com/Lolner95/AIGX/issues) · star the repo.

---

## Citation

```bibtex
@software{aigx2026,
  title   = {AIGX: AI Genome Exchange — A Benchmark-Validated Context Format for AI Coding Agents},
  author  = {Parisotto, Grégory},
  year    = {2026},
  url     = {https://github.com/Lolner95/AIGX},
  license = {MIT (tools), CC-BY-4.0 (spec)}
}
```

## License

Reference **tools**: [MIT](LICENSE). Specification **text**: [CC-BY-4.0](standard/LICENSE). Open spec +
permissive tools, so AIGX can be adopted and reimplemented by anyone, for anything.

<p align="center"><sub>Built from a research-grade benchmark. The genome of your codebase, for the age of AI agents. 🧬</sub></p>

## Experimental context and evidence

`aigx context`, `history`, `record`, `verify`, and `import-trace` provide scoped rules, decisions, code fingerprints, verification receipts, and model contribution history. See [the guide](docs/context-v0.md) for commands, optional Codex capture, budget semantics and coverage limits.

Measured experiments and limitations: [implementation and benchmark report](docs/research/2026-09-21-implementation-and-benchmarks.md).

Installazione

Installa la skill da https://github.com/Lolner95/AIGX

Questa skill non è pubblicata sul registro ClawHub. Incolla il prompt nel tuo agente di coding — Claude Code, Cursor, Codex — e installerà la skill direttamente dal repository sorgente.

Apri il repository

Link