The project ships with a CLAUDE.md in the repo root. It's a set of instructions for Claude Code, but the ideas apply to any AI coding tool. The file covers output formatting, code style, architecture rules, and workflow constraints. Because it's in version control, every developer gets the same AI behavior. A CLAUDE.local.md handles personal overrides that don't get committed.
The default mode is describe-only. The AI proposes changes but doesn't write anything until it hears a specific go-ahead phrase. This creates a natural review step where you can push back on the approach before any code exists.
AI models default to agreeable. They'll validate bad ideas and flip positions the moment you push back. The CLAUDE.md enforces zero-tolerance sycophancy rules so the AI will disagree when you're wrong, hold correct positions under pressure, and admit when it's guessing instead of backfilling reasoning for the opposite conclusion. The second opinion is only valuable if it's honest.
The CLAUDE.md encodes the project's architecture decisions and code style. Controller namespacing, route structure, model ordering, validation patterns. The AI follows these at generation time rather than relying on a separate style guide that gets forgotten. The key is specificity. Vague rules like "write clean code" produce nothing. Concrete rules like "4 spaces, PSR-12, multi-line doc blocks only" are enforceable and verifiable in a diff.
The CLAUDE.md covers project-wide conventions, but file-type-specific rules live in .claude/rules/. Each rule file has a paths frontmatter that glob-matches source files. When the AI touches a matching file, only the relevant rules load into context. This keeps the main CLAUDE.md from growing into a wall of text while still giving the AI precise instructions for controllers, models, requests, tests, migrations, and so on. It also means adding a new convention is just dropping a markdown file into the rules directory with the right glob pattern.
The AI is constrained to do exactly what was asked. No extra features, no refactoring surrounding code, no unnecessary new files. Without this, a simple bug fix quietly turns into a rewrite. Keeping changes small keeps them reviewable.