This file captures only what cannot be inferred from the codebase itself.
Both developers and AI agents are expected to add entries as they encounter surprises.
- Add an entry when you encounter something unexpected: a build quirk, a non-obvious constraint, a dependency gotcha, or any behavior that would surprise the next agent or developer.
- Add an entry when a developer flags an anti-pattern produced by AI — describe the anti-pattern and the preferred alternative.
- Do not add codebase overviews, directory listings, or anything discoverable by reading the source.
- Keep entries concise: one line per lesson, grouped under a heading if a theme emerges.
- Do not add content to this file that is already discoverable by reading the source or build scripts — that inflates context without adding signal, reducing AI agent task success rates (see arxiv 2602.11988).