# AI System Evolution Roadmap

Do **not** build everything at once. Rules have maintenance cost.

## Phase 1 — Now (shipped)

- Rules: constitution, architecture, domain, coding, api, database, ui, …
- ADR, patterns, examples, playbooks
- Review / DoD / checklists / forbidden / commands / workflow / file-map
- `ai-contract.md`
- Cursor runtime: `.cursor/*` → symlink → `.ai/` (no content copy)

**Invest next engineering time in:** polishing `patterns/`, `examples/`, `playbooks/` while building real features — not more rule files.

## Phase 2 — When the codebase grows

Add only when pain appears:

| Item | Why wait |
|---|---|
| `anti-patterns/` | Useful after real mistakes accumulate |
| `metrics.md` | Numbers matter once CI exists |
| `quality-gates.md` | Wire when lint/test gates are real |
| `memory/` (known-bugs, tech-debt, todo) | Fill from actual incidents |

## Phase 3 — Multi-agent / heavy automation

| Item | Why wait |
|---|---|
| `graph/domain.yaml` | Knowledge graph for relation reasoning |
| `mcp/*.json` | Structured context servers |
| `skills/<feature>/` | Packaged feature kits (login, payment, …) |

Markdown remains human-readable; JSON/YAML for machines — introduce when agents > 1 or retrieval latency hurts.

## Rule of thumb

If adding a rule file does not prevent a repeated AI failure this week, **do not add it**.