LLMs Don't Read Your Instructions. Here's What Actually Works.

How to actually get AI coding agents to follow the rules you set.

Every developer who’s worked with AI coding agents has had the same experience. You write careful instructions — a CLAUDE.md file, a .cursorrules, a system prompt — and the agent follows them… most of the time. Sometimes it nails every convention. Other times it rewrites files you told it not to touch, runs commands you explicitly forbids, or ignores the architecture patterns you spelled out. You polish your prompts. You add more detail. The compliance improves, then degrades again on the next task.

I’ve hit this repeatedly with Claude Code. Not in long, bloated sessions where you’d expect the model to lose the plot — in fresh context windows, with concise, well-structured instructions. The problem isn’t the model’s capability. It’s that instruction-following in LLMs is fundamentally different from how we think about it.

The Instruction-Following Myth

When you write a CLAUDE.md file, you’re not programming an agent. You’re writing a suggestion that gets weighted against thousands of other signals — the codebase context, the conversation history, the model’s training data, and the inherent pressure to produce “helpful” output. Your instructions are one voice in a chorus, and not always the loudest.

This is why adding more detail often backfires. Longer instructions mean more surface area for misinterpretation. More rules mean more potential conflicts between them. The model has to balance your explicit instructions against its implicit goal of being helpful, and “helpful” often means “do something that looks reasonable” rather than “do exactly what was asked.”

What Actually Works

After months of iteration, I’ve found that the most effective approach isn’t better instructions — it’s better constraints. Here’s what I mean:

1. Reduce the Problem Space

Instead of telling the agent what to do, tell it what the solution looks like. Don’t write “use TypeScript, follow our naming conventions, don’t modify files outside src/”. Write:

The solution is a single function in src/utils/parser.ts that:
- Takes a string input and returns a ParsedResult
- Uses the existing parseToken() helper from src/utils/tokens.ts
- Has no side effects

This constrains the output without leaving room for interpretation. The agent knows exactly where the code goes, what it looks like, and what it depends on.

2. Use Structural Constraints, Not Behavioral Rules

Behavioral rules (“don’t do X”) are weak because the model has to understand why X is bad, and then actively avoid it. Structural constraints (“the file must contain only Y”) are strong because they define the positive space.

Instead of: “Don’t add comments to the code” Try: “The function body contains only implementation code, no comments or documentation”

Instead of: “Don’t use any external libraries” Try: “The implementation uses only Node.js built-in modules”

3. Anchor to Existing Patterns

The most powerful constraint is pointing to something that already exists. “Follow the pattern in src/api/users.ts” is more effective than describing the pattern in words. The model can read the existing code and infer the rules, which is what it’s actually good at.

4. Make the Task Small Enough to Verify

Large tasks have too many degrees of freedom. Break them into pieces where each piece has a clear, verifiable outcome. “Refactor the authentication system” is a recipe for chaos. “Extract the token validation logic from auth.ts into a separate validateToken.ts file” is something you can check in 30 seconds.

The Meta-Principle

The underlying principle is this: LLMs are better at matching patterns than following rules. Give them a pattern to match, not a rule to follow. Constraints that define the shape of the solution are more reliable than instructions that describe the behavior of the solver.

This doesn’t mean instructions are useless. They provide context that helps the model make better decisions. But they work best when they’re descriptive (“the system uses a layered architecture where each layer only depends on the one below it”) rather than prescriptive (“you must follow the dependency rule”).

The next time your AI agent ignores your carefully written instructions, don’t add more words. Add more structure.