There’s a file in every serious AI-assisted project that determines whether the AI is useful or just fast. Not the codebase. Not the tests. The instruction file — the thing that tells the AI how to work on this project specifically.
Most of them are bad. Not because the developer doesn’t care, but because instructions are deceptively hard to write well. “Write clean code” transfers nothing. “Keep files under 500 lines” is specific but fires on the wrong signal. After eleven phases of building a framework with AI, here’s what actually works.
Rules vs Patterns
A rule is “no inline comments.”
A design pattern is:
No inline comments — because well-named identifiers already say what the code does. The only comment worth writing explains the why behind a non-obvious constraint. If removing the comment wouldn’t confuse a future reader, don’t write it.
The rule stops at the prohibition. The pattern encodes the reasoning that produced it. That reasoning is what scales — because the AI encounters situations the rule didn’t anticipate, and only the reasoning tells it what to do there.
Rules transfer behavior. Patterns transfer judgment.
The Three-Part Structure
Every instruction that holds up across months and multiple sessions has three parts:
A concrete trigger condition. Not “keep things modular” but “split when a second concern appears.” The trigger is observable — you can look at a file and ask “does this have two concerns?” You can’t look at a file and ask “is this modular enough?” The concrete trigger is what makes the instruction consistent rather than interpretive.
The why. “Don’t re-read files you wrote this session” is a rule. Add the reason — “re-reading signals you don’t trust your own output, and that distrust is almost never justified” — and now the AI can handle edge cases: if the user edited the file, if a hook modified it, the reason tells it the rule doesn’t apply here.
Application scope. When does this fire? When does it not? Naming the boundary explicitly prevents mechanical application in situations where the pattern doesn’t fit. “This guidance kicks in whenever you’re about to report a state you didn’t personally witness this session” is a scope. Without it, the AI either overapplies or underapplies.
Three parts: trigger, reason, scope. Missing any one, the instruction degrades.
Writing One
The hardest part is resisting the impulse to be comprehensive. “Always handle errors gracefully” tries to cover everything and covers nothing. The instruction that changes behavior is the one that fires at a specific moment.
Start from an incident. Something went wrong, or something went right that you want repeated. Ask: what was the observable state just before the outcome? That’s your trigger.
Then ask: why does this matter? Not the surface answer (“it wasted time”) but the underlying one (“the test suite passed but production failed because the mock diverged from the real adapter”). The underlying reason is what lets the instruction generalize.
Then ask: when should this not apply? Every pattern has a boundary. Name it.
The instruction about commit bodies came from this process. The surface observation: commit messages across the project were inconsistent. The underlying reason: this is tutorial source material, and a tutorial built from bare commits has no story. The boundary: simple bug fixes don’t need the full structure.
Every commit body must be written as if it will be used as tutorial source material — because it will be. A commit that only says “add registry” is not acceptable. Each body must include: what was built, design decisions, phase exit criteria. A reader with no prior context must understand what exists and why from
git logalone.
That instruction is long. It needs to be. It transfers a complete mental model, not just a prohibition.
When to Write One
Not every observation deserves an instruction. The test: will this situation recur across sessions? If yes, the instruction earns its place. If it’s a one-time decision or a project-specific detail, it belongs in a memory file or a code comment.
The right cadence: you don’t write instructions in advance for problems you haven’t had. You write them the second time a problem happens. The first time is learning. The second time is a system failure.
An instruction file written before any work is a wishlist. An instruction file built from real incidents is a compressed history of what actually matters.
Why This Matters for Multi-Model Projects
When multiple AI models work on the same project — one for architecture, one for implementation, one for template generation — the instruction file is the shared contract between them. It’s what makes a handoff coherent instead of chaotic.
A new model joining the project reads the instruction file and picks up the project’s standards without onboarding. A model that’s been on the project for fifty sessions reads it and stays calibrated. The instructions are the memory that survives model switches, context resets, and session boundaries.
This is why the quality of each instruction matters more than the quantity. Twenty dense, well-structured patterns are worth more than a hundred vague rules. The density comes from knowing what you actually think — which only comes from having built something real and watched it go wrong in specific ways.