This is an instructions file. It lives in your repository root. Your AI coding assistant reads it before touching your code.

You can call it CLAUDE.md or AGENTS.md or INSTRUCTIONS.md or whatever your tooling expects. The name doesn’t matter. What matters is that you’re encoding expectations that would otherwise live in your head.

What follows is a starting point. Steal it, modify it, delete the parts that don’t apply. Add what’s missing.

There’s a dirty secret about AI-assisted coding: it’s often too helpful.

Ask an AI to implement a feature and it will, quickly and confidently. It’ll reach across your codebase, modify whatever it needs, create new utilities that duplicate existing ones, and deliver working code that makes you slightly uncomfortable.

The code works. But it doesn’t belong.

After months of working with AI coding assistants, I’ve started to recognize the pattern. The AI isn’t bad at coding. It’s bad at not coding. It lacks the instinct that experienced developers have: the pause before typing, the “wait, where should this actually live?” moment, the awareness that every line you write exists in a larger context.