# 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, …
- **Environment layer (FROZEN):** `environment.md` · `development.md` · `docker.md` · `deployment.md` · `commands.md`
- ADR, patterns, examples, playbooks
- Review / DoD / checklists / forbidden / workflow / file-map
- `ai-contract.md`
- Cursor runtime: `.cursor/*` → symlink → `.ai/` (no content copy)

**Invest next time in product implementation, not more meta-rules:**

```
产品冻结 → Domain → ERD → OpenAPI → 页面路由 → P1 编码
```

Do **not** expand the engineering-spec layer unless a repeated AI failure demands it.

## 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**.