Agent instructions that actually change behaviour A developer has published a practical guide to writing agent instruction files that measurably change behavior, centered on a five-line rule in a global CLAUDE.md that assigns subagent models by task difficulty (haiku for mechanical work, sonnet for normal build and fix, larger models only for complex architecture, security or billing logic). The approach places rules in layers by enforceability — CLAUDE.md as context, skills loaded on task match, hooks the harness runs without the model's consent, and CI — and favors rules written as small if-statements with a trigger, a concrete action and a stated reason, plus a replacement for every prohibition. My global instruction file for Claude Code has a five-line rule about which model a subagent should run on. It changes how every session spends money, and a short test shows that it does. Most instruction files I read are the opposite: long lists of sensible advice with no visible effect on what the agent actually does. The difference is not clever wording. It is whether each rule sits in a place where it can work, whether it has a trigger, and whether anyone tested it. This is how I decide all three. Claude Code reads CLAUDE.md or a repository's AGENTS.md at the start of every session. Skills are folders with a SKILL.md file that load only when a task matches their description. Hooks are scripts the harness runs at fixed points, such as before a tool call, and the model does not get a vote on whether they run. CI runs after all of that, on every push. The further down a rule sits, the harder it is to ignore. The documentation is frank about the first layer: CLAUDE.md is context, not enforced configuration. The model reads it and usually follows it. "Usually" is fine for style and preferences. It is not fine for "never push to main" or "never print the production database URL". Those belong lower down. Things that are true in every session and short enough to read in every session: the commands to build and test, where things live, conventions the code does not make obvious, and the few rules that apply to every task. Anthropic's docs suggest keeping each file under 200 lines; I aim for well under half that. Every line costs context in every session and competes with every other line for attention. If more than one kind of agent works in the repository, AGENTS.md is the shared name that several tools read, and Claude Code can read it in place of CLAUDE.md . I keep one file rather than two copies that drift apart. Personal preferences that should follow me across every project, like the model rule below, go in the global file in my home directory instead of in any repository. This is the model rule from my global file, exactly as it is: ~/.claude/CLAUDE.md Subagent models cost When work goes to subagents, always set the model on every Agent call by how hard the task is: - haiku : copy-only edits, mechanical changes, screenshots, data gathering, simple checks. - sonnet : normal build and fix work UI, small logic, tests . - bigger model inherit/opus : only complex work, such as tricky architecture, security or billing logic, hard merges and deep reviews. The main session plans, reviews, merges and runs the full tests. Each of these reads well and changes little. The same kinds of rule fail again and again. Adjectives without a check "write clean, maintainable code" give the model nothing to do differently, because it already believes that is what it does. Rules deep in a long file lose to the code in front of the model. Two rules that disagree, like "keep changes minimal" and "fix any issues you notice", get settled in whichever direction the task leans. And a rule with no trigger, like "be careful with auth", never fires, because nothing tells the agent that this moment is the auth moment. Written like a small if-statement. The rules that work read like small if-statements. When something specific happens, do one concrete thing, because of a reason the agent can use on cases the rule did not list. The model rule has all three: the trigger is work going to a subagent, the action is setting model on every Agent call, and the reason is cost, with examples for each tier. The reason matters more than it looks. Without it, an agent meeting an odd case has to guess; with it, it can work out what I wanted. Negative rules work better with a replacement. "Do not use any " leaves the agent stuck when a type gets hard. "Do not use any ; use unknown and narrow it" gives it somewhere to go. Some knowledge is long and only sometimes needed: how to draw a diagram in the house style, how to cut a release, how the seed script expects a post to look. In CLAUDE.md it would cost context in every unrelated session. A skill holds it instead. Only the name and description are in context up front, and the body loads when a task matches. .claude/skills/blog-diagram/SKILL.md --- name: blog-diagram description: Draws an SVG diagram for a blog post in the site's dark style. Use when a post needs a flowchart, an architecture picture or a comparison. --- Write a hand-made SVG to public/shots/