CLAUDE.md

1## AIGX — AI Genome Exchange
2 
3This repository stores its AI agent rules in `.aigx/` — a structured genome with a per-file boundary index. You do not need to guess conventions; they are in the genome.
4 
5### Before editing any file — look it up
6 
7Open `.aigx/files.aigx` and find the `<file path="...">` entry for the file you are about to edit:
8 
9```xml
10<file path="src/features/auth/login.ts" domain="auth">
11  <role>Handle login — validate credentials and issue a session</role>
12  <forbid pri="CRIT">NEVER read from another tenant's session store</forbid>
13  <gotcha>token expiry is checked at read-time, not issue-time</gotcha>
14  <check>ARCH-no-deep-imports ENG-tenant-scope</check>
15</file>
16```
17 
18- **`<role>`** — understand what this file is for before writing a line
19- **`<forbid pri="CRIT">`** — hard constraint, never violate it, no exceptions
20- **`<gotcha>`** — the single worst pitfall for this file; read it twice
21- **`<check>`** — space-separated rule ids; look each up in its concern file and verify they hold before finishing
22 
23The concern files are `.aigx/architecture.aigx` (ARCH-* rules), `.aigx/data.aigx` (DATA-*), `.aigx/engineering.aigx` (ENG-*), etc. Read the ones your check ids reference **before** writing code.
24 
25### Genome structure
26 
27```
28.aigx/
29  protocol.aigx      ← full reading sequence
30  product.aigx       ← product context + freshness clause (which old docs are stale)
31  architecture.aigx  ← ARCH-* architectural rules
32  engineering.aigx   ← ENG-* hard-correctness invariants
33  files.aigx         ← ★ per-file boundary index — look files up here
34  agent.aigx         ← self-maintenance rules (this section summarises them)
35  [concern].aigx     ← any other concern files present (data, auth, testing, …)
36```
37 
38### Keeping the genome current
39 
40**Rename/move a file** that has a `files.aigx` entry → update `path="..."` in the **same change-set**. A rename without a genome update is an incomplete change.
41 
42**Create a new file** agents will edit → add a `<file>` entry in `files.aigx` with at least `<role>` + one `<check>` id. Never leave a new boundary file without an entry.
43 
44**Rule ids are permanent** — `ARCH-no-deep-imports`, `ENG-2`, etc. Never rename or delete them. Update the text in-place only.
45 
46**Code change makes a rule incorrect** → update the rule text in the same change-set. The genome describes reality, not history.
47 
48**After renames, moves, deletes, or adds:** verify every `<file path>` in `files.aigx` still exists and every `<check>` id resolves to a real rule.
49 
50**Never add entries speculatively.** One rule per real constraint. One entry per file agents actually edit.
51 
52### Validate
53 
54```bash
55python tools/aigx-lint/aigx_lint.py --root .
56```
57