Why Coding Agents Dey Ignore Your Instructions

Wetin make coding agents ignore your instructions

Coding agents dey ignore your instructions for four reasons, and none of dem be say you too polite. The rule no ever enter context window. The rule too vague to check any action against am. Something else for the context contradict am, usually the code wey the agent just read. Or the rule still dey loaded but e dey far behind the current turn, and the agent dey work with wetin dey near.

Each cause get im own fix, so the first work na to tell dem apart. Capital letters and the word IMPORTANT no be diagnosis. The mechanics below use Claude Code as the working example, because dem don document im loading and compaction behaviour well as of August 2026. Other tools fit differ for details, but dem dey behave the same way for general outline.

Make we first define two terms. The context window na the block of text wey the model dey see for one turn: system prompt, your instruction files, the conversation, and every file wey the agent don read. The harness na the program wey dey around the model, the thing wey dey read files from disk and assemble that block. Almost every complaint for this post na really complaint about the harness, not the model.

Your instruction file na message, e no be setting

Instruction file no be configuration. Nothing for runtime dey read CLAUDE.md and enforce am. Harness go read the file from disk and paste the text inside conversation. For Claude Code, dem dey deliver that content as user message wey come after system prompt. This mean say model dey see your rules the same way e dey see anything else wey you type.

This get one uncomfortable result. Your rules dey compete with every other text for the window, all for the same level. Rule na claim. The file wey agent just open na evidence. When both no agree, evidence often dey win. Nothing go raise error because, from model point of view, nothing go wrong.

Official documentation talk this one clearly: instruction files dey treated as context, not enforced configuration. To block action no matter wetin model decide, you need hook, no be sentence. Remember this line. Most of the fixes for the end of this post na this same line applied to particular case.

Which instruction files dey load, and when

Claude Code dey walk up the directory tree from the directory wey you start am. Every CLAUDE.md and CLAUDE.local.md from filesystem root reach your working directory dey load complete when e launch. Dem dey join together for that order, so the file wey dey closest to where you launch am na the last one wey e read. Inside one directory, .local file dey append after the main one.

Files for subdirectories below your working directory dey behave differently. Dem no dey load when e launch. Dem dey load when the agent reads a file for that directory. Same thing apply to path scoped rules for .claude/rules/ wey get paths: frontmatter field: dem enter the context when e read a matching file, no be for every turn.

That one difference explain plenty of the failures wey people report. You put rule for packages/api/CLAUDE.md, you ask question about the API, and the agent answer without ever opening file under packages/api/. The rule no be say e ignore am. E never dey present. If your repository dey split guidance across instruction files for each package inside a monorepo, na this first thing you suppose check every time.

One more loading trap dey, and na the commonest version of "the agent ignored my instructions": Claude Code dey read CLAUDE.md, no be AGENTS.md. Repository wey standardise on AGENTS.md and no get CLAUDE.md no give Claude Code anything to load. The supported bridge na a CLAUDE.md wey first line be @AGENTS.md. This one import the file when e launch, together with any Claude-specific notes underneath. Symlink dey work too when you no get anything extra to add. To decide wetin suppose dey inside that file na separate question, and how to separate agent instructions from human documentation cover am.

Confirm say file load before you rewrite am

No touch the wording until you get proof say agent fit see the file. Two checks dey, and make you start with the cheap one.

Run /context inside the session. E go print the current window broken down by category, and the Memory files list go show every instruction file wey actually load. If file no dey for that list, e no dey inside the conversation, so anything wey you write inside am no fit matter. /memory go list the file locations and open dem for editing, including files wey never exist yet.

For stronger confirmation, log the loads. The InstructionsLoaded hook event dey fire every time CLAUDE.md or rules file enter the context, and its matcher dey tell you why the load happen: session_start, nested_traversal, path_glob_match, include, or compact. Put this inside .claude/settings.json:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "matcher": "nested_traversal",
        "hooks": [
          {
            "type": "command",
            "command": "cat >> /tmp/instructions-loaded.log"
          }
        ]
      }
    ]
  }
}

The hook dey receive its payload as JSON for standard input, so cat go append the complete record. Watch am with tail -f /tmp/instructions-loaded.log as you work. The exit status of this event dey ignored, so the hook fit only observe; e no fit block. If your nested file no show for that log during session wey you expect say e suppose load, stop to reword am. The problem na placement.

Wetin long session dey do to your rules

Two separate effects dey happen here, and each one need different response.

Distance. Rule wey you state for turn 1 still dey inside the window for turn 90, but e now dey compete with 90 turns of text wey be newer and more specific to wetin you dey do now. You no fit configure this one comot, but you fit measure am. Run the same task for fresh session. If the rule dey work there but fail deep inside long session, distance na your answer.

Compaction. When the window full, the harness summarise the conversation so far and continue from that summary. Na wetin the summariser judge as important go survive, and e no always be the same as wetin you consider important. Claude Code document the result for each mechanism, and the differences dey large. Project root CLAUDE.md and unscoped rules dey re-injected from disk after compaction. Auto memory dey re-injected from disk. Rules wey get paths: frontmatter dey lost until e read matching file again. Nested CLAUDE.md files for subdirectories dey lost until you read file for that subdirectory again.

Rank your instructions with that table, and the fragility order go clear. Rule wey you only type for chat na the most fragile thing for the session: e go persist only if the summary happen to keep am. Rule for packages/api/CLAUDE.md come next, because e load once, summary remove am, and e go return only when dem read am again for that directory. Rule for project root file na the most durable, because dem dey read am again from disk every time.

So if instruction must hold for the whole session, put am inside project root file without paths: frontmatter. Everything else na tradeoff wey you suppose choose deliberately. Managing wetin dey remain for context window cover /compact with a focus argument and /clear between unrelated tasks, and both one change how often the summariser fit decide wetin your rules be.

Why the surrounding code dey beat the rule

Na this failure people dey describe pass, but dem dey diagnose am least. Your file talk say database access suppose pass through the repository layer. The agent write handler wey call ORM (object relational mapper) directly. No be say dem ignore you because of style. Evidence outvote you.

Rule dey describe preference. Code dey show one. When the agent open three files for the module wey e wan edit and all three call ORM directly, context get one abstract sentence for one side and three concrete, recent examples wey match the task for the other side. To copy the local pattern normally na correct behaviour. E wrong here only because you know something wey context no know: those files na legacy.

So write that one inside the rule. Rules wey name their own counter-evidence dey survive contact with real repository. Rules wey state bare preference no dey.

New database access suppose pass through app/repositories/. Files under app/legacy/ still dey call ORM directly. Na old code be that, no be the pattern. No copy am.

The second sentence na the part wey do the work. E tell the agent wetin e go find and how e suppose understand am, before e find am. The same fix apply to any rule wey your repository visibly contradicts: commit style wey your history no follow, test layout wey half your test suite dey ignore, or import convention wey dey apply only for new code. Anywhere code disagree with the file, name the disagreement inside the file.

Rule wey no clear cannot get checked, so agent no fit follow am

"Write clean code." "No over engineer." "Keep am simple." "Be careful with migrations." None of these fit get tested against one specific action, whether na agent or you dey do the checking. If you give agent rule wey e no fit check against its own output, e dey guess, and you dey grade the guess by feeling.

Na this test you suppose apply to every line for your file. Write shell command wey go exit non-zero when somebody break the rule. If you no fit write that command, the rule no be checkable. Compare these pairs:

• No be checkable: "Keep functions small." Checkable: "Any function wey pass 60 lines need comment above am to explain why."
• No be checkable: "Test your changes." Checkable: "Run npm test and paste the failure count before you call task done."
• No be checkable: "Keep files organised." Checkable: "HTTP handlers dey for src/api/handlers/. Nothing else fit enter that directory."
• No be checkable: "Format code properly." Checkable: "Use 2 space indentation for .ts files."

"Do not over engineer" na the rule wey people first give up on, because the repair no be to make the sentence shorter but to make am longer: spell out wetin the smallest change wey go work really mean give agent criteria wey e fit use check its own diff against.

Size na the same problem with another name. Claude Code guidance target instruction file wey dey under 200 lines, and e talk directly say longer files reduce adherence. File wey get 700 lines no be stronger instruction. Na 700 lines of claims wey get more chance to contradict each other, and every turn e dey use space for your context window, which dey show directly for your token usage. If you structure the file so reader fit scan each rule under heading, writing instruction file wey agent fit act on cover that.

How to diagnose am for ten minutes

Run these ones in order. If you jump go the last step, na so people dey end up with long file full of shouted rules wey still no dey work.

1. Confirm say e load. Run /context and read the Memory files list. If the file no dey there, fix the location and stop. Nothing else for this list apply yet.
2. Reproduce am for fresh session. Start new session and give the smallest task wey suppose trigger the rule. If e hold for here but fail for long session, e point to distance or compaction. If e fail for here too, na the rule itself be the problem.
3. Remove the competition. Ask for the same change inside directory wey existing code already follow the rule. If compliance come back, the surrounding code don outvote your sentence.
4. Search for conflict. Two files wey give different guidance for the same behaviour na documented failure: the model fit pick one anyhow, and e no go tell you say e do am.
5. Make am checkable and test am again. Rewrite the rule with concrete path and condition. If compliance increase sharply, phrasing na the cause.

Step 4 na one command. Grep every instruction source for the topic, no be only the file wey you dey edit:

grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

If two files get different instructions, na your bug. Delete one. No try rank dem with stronger wording, because no ranking engine dey wey you fit appeal to.

The fixes, in order of leverage

Each step below get more effect than the one above am, and e cost more to set up. Start from top when e cheap to reword a rule. Move down once the rule don matter reach level wey occasional misses no longer acceptable.

1. Make the rule concrete. Name a path, a command, or a condition. Add the counter-evidence wey agent go find for repository, as shown earlier. This one free, and e dey fix surprising number of cases.
2. Move am closer to wetin e govern. A nested CLAUDE.md, a path-scoped rule for .claude/rules/, or a comment for the top of the file itself. The rule go come with the same read as the code wey e apply to. Accept the tradeoff: anything wey load that way go drop out for the next compaction and return for the next matching read.
3. Move enforcement enter a hook. Prose dey ask. A hook dey decide. Hooks dey run as code for fixed lifecycle events and apply regardless of wetin the model conclude.
4. Give the rule to a deterministic tool and delete the prose. Formatting, import order, line length, banned imports, commit message shape. ruff format, prettier --write, eslint, or a pre-commit hook. The formatter dey correct every time and e cost zero tokens. The sentence dey correct most times and e cost tokens for every turn.

Step 3 in full. Suppose agent must never edit migration files. Put this for .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
          }
        ]
      }
    ]
  }
}

And put this for .claude/hooks/guard-migrations.sh:

#!/usr/bin/env bash
set -euo pipefail

path=$(jq -r '.tool_input.file_path // empty')

case "$path" in
  */migrations/*)
    echo "Files under migrations/ are written by hand. Stop and ask first." >&2
    exit 2
    ;;
esac

exit 0

Run chmod +x .claude/hooks/guard-migrations.sh, then start a new session and ask agent to edit a file under migrations/. The edit go refuse, and your message go return as the reason. Exit status 2 for PreToolUse blocks the tool call before e run, and your stderr text go hand to the model as the blocking message. ${CLAUDE_PROJECT_DIR} go resolve to the project root, so the hook go work no matter the directory wey agent dey use. Agent no need agree with the rule, remember the rule, or still get the rule for context. The edit no go happen.

For a flat prohibition wey get no logic inside, permissions.deny for your settings dey do the same work without script to maintain, and the permission modes decide wetin go run without asking you first. If an instruction genuinely need dey for system prompt level instead of user message, --append-system-prompt go put am there, though you must pass am for every invocation, so e fit scripts pass interactive work.

Wetin you no fit instruct away

Make am clear which part belong to you. Placement, wording, conflict between files, and file size na author problems, and na author go fix dem. The rest na model behaviour, and better wording no go remove am.

Agreement no be compliance. Agent fit acknowledge rule, repeat am back correctly, then break am two tool calls later. The acknowledgement cost nothing and e no predict anything. No treat am as fix, and no count am as test.

Some habits dey persistent. Adding comments, adding defensive error handling, writing closing summary, and running the obvious next command. Dem dey come back when rule forbid dem, but at reduced rate instead of zero. You fit measure your own rate: run the same task ten times for fresh sessions and count the violations. Where that number suppose be zero, rule need to leave the prompt.

Your own session go become example. If agent break rule for turn 12 and you allow am, that violation don enter the context as demonstration, and e dey much more recent than the rule. Correct violation immediately you see am. Violation wey you no correct dey teach the rest of the session.

Instruction file no be security boundary. E shapes behaviour but e no enforce am. Anything where mistake costly, like credentials or destructive commands, belong for permissions or hook. Keep secrets out of agent reach applies the same principle to data: no ask agent make e no read file; arrange make file no readable.

The short version. Prove say file load, make rule easy to check, move am near the thing wey e govern, and when miss rate still matter, comot am from prose. Rule wey agent no fit ignore na rule wey nobody suppose ask agent.

FAQ

Why Claude Code dey ignore my CLAUDE.md?

Check say e load before you assume say e dey ignored. Run /context and check the Memory files list; if file no dey named there, e no dey inside the conversation. Instruction files dey delivered as user message after the system prompt, and dem dey treated as context instead of enforced configuration, so strict compliance no dey guaranteed. Most real cases na one of four things: file dey inside subdirectory wey agent never read, two files disagree and model choose one anyhow, rule too vague to check against an action, or surrounding code dey show the opposite of wetin rule talk.

Editing instruction file during session fit change anything?

E no fit change the copy wey already dey inside the conversation. Files above your working directory dey load completely when session start, so na the text wey model hold at launch time. To use edited version, start new session, or ask agent make e read file with its normal file tools. That one go put current version inside conversation as fresh message. After compaction, project root file dey read again from disk, so new version go enter at that point too.

Which file go win when root CLAUDE.md and nested one disagree?

None of dem, reliably. Discovered files dey concatenate inside context instead of overriding each other. Dem dey ordered from filesystem root down to your working directory, so closest file just dey read last. No precedence engine dey resolve contradictions, and Claude Code documentation talk say contradictory rules fit get resolved anyhow. Write nested files as additions wey name the path wey dem govern, and delete the contradiction instead of trying to outrank am.

My instructions go survive /compact?

E depend on how dem load. Project root CLAUDE.md, unscoped rules, and auto memory dey re-inject from disk after compaction. Rules with paths: frontmatter and nested CLAUDE.md files for subdirectories dey lost until matching file dey read again. Anything wey you only type for chat go survive only if summariser happen keep am. If rule must hold across the whole session, put am inside project root file without paths: frontmatter.

When rule suppose become hook instead of prose?

When the check dey deterministic and cost of missing am pass cost of writing small script. File path restrictions, required commands before commit, and forbidden tool calls all qualify. A PreToolUse hook wey exits with status 2 go block the tool call immediately and send your stderr text back to model as the reason. So e go hold whether rule still dey anywhere for context or not. Anything formatter or linter fit decide should belong to that tool, and you should delete am completely from instruction file.