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.