# Context Cliff & Scale Limits

The bottleneck is **model attention**, not disk space. Even with 1M+ token windows, "lost in the middle" degrades quality.

## When agents struggle

- Monoliths where one task requires 15+ directories  
- Single files beyond ~800 lines mixing unrelated concerns  
- Copy, assets, and logic interleaved in the same tree  

## Modularize early

- Split micro-frontends or standalone APIs when domains are independent  
- Extract shared packages only when two apps truly share code  
- Keep each workspace lean enough that one feature fits in one folder read  

## Split thresholds (rules of thumb)

| Signal | Action |
|--------|--------|
| Central data file > ~400 lines | Split by domain with barrel export |
| Knowledge base > ~20 entries | Split by topic file |
| Second product on same stack | Separate repo or Astro workspace |
| Agent needs full tree for every task | Missing domain boundaries — refactor |

## Keep changes minimal

- Smallest correct diff wins  
- Match existing naming, types, and import style  
- No drive-by refactors outside the task domain  

## Verification

Every project should document its verify command in `AGENTS.md` (e.g. `npm run build`, `pytest`, `go test ./...`). Run it before calling work done.