A doc structure that stops Claude Code from grepping blindly in big codebases

On a large production app built with Svelte and Express/Knex, ported from Oracle to Postgres, with about 150 Cypress test specs and roughly 30 functional modules, using Claude Code daily led to a recurring problem: every session started with Claude grepping around, re-discovering the architecture, and repeating the same mistakes. The fix was a Markdown 'context pack' that Claude reads before touching any code. It consists of a CLAUDE.md file, auto-loaded every session, containing the rules of engagement rather than the documentation itself.

Alongside it sits a docs/claude/ folder holding AI-facing documentation only: an INDEX.md that acts as an entry point with a decision table mapping tasks to the right file, a one-page ARCHITECTURE.md giving the big picture, a MAP.md linking each feature to its files, routes, and database tables, a GLOSSARY.md translating domain acronyms into database fields, a CONVENTIONS.md covering reusable patterns like async jobs and internationalization, a PATTERNS.md with gold-standard components and a self-review checklist, a GOTCHAS.md limited to traps that cross multiple areas, a flows/ folder with roughly 30 files (one per functional area), a reports/ folder for one-off audits, and a baselines/ folder tracking known error counts. The key rule in CLAUDE.md: before any Grep, Glob, or Read investigation, Claude must read the relevant documentation first.