Why Coding Agents Dey Ignore Your Instructions

Coding agents dey 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 the context window. The rule too vague to check any action against am. Something else for the context contradict am, usually na the code wey agent just read. Or the rule still dey loaded but e dey far behind the current turn, and agent dey work with wetin dey near.

Every 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 dey use Claude Code as the worked example, because dem don document how e dey load and compact things in detail as of August 2026. Other tools fit differ for the details, but for broad outline dem dey behave the same way.

Make we first define two terms. The context window na the block of text wey model dey see for one turn: system prompt, your instruction files, the conversation, and every file wey agent don read. The harness na the program 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, no be 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 dey read the file from disk and paste the text inside the conversation. For Claude Code, dem dey deliver that content as user message 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 wey dey inside the window, with equal priority. Rule na claim. The file wey agent just open na evidence. When both no agree, evidence often dey win. Nothing raise error because, from model point of view, nothing go wrong.

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

Which instruction files load, and when

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

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

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

One more loading trap dey, and na the most common version of "agent ignore 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 CLAUDE.md wey first line be @AGENTS.md. E import the file when e start, with any Claude-specific notes underneath. Symlink dey work too when you no get anything extra to add. To decide wetin belong inside that file na separate question. We cover am for how to separate agent instructions from human documentation.

Confirm say file load before you rewrite am

No touch the wording until you get proof say agent fit see the file. You get two checks, and the cheaper one come first.

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 that list, e no dey inside the conversation, so anything you write inside am no fit matter. /memory go list the file locations and open dem for editing, including ones 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. Monitor 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 a session wey you expect say e go load, stop to reword am. The problem na placement.

Long session fit affect your rules

Two separate effects dey apply here, and dem need different responses.

Distance. Rule wey you state for turn 1 still dey inside the window for turn 90. But now e dey compete with 90 turns of text wey newer and more specific to wetin you dey do now. You no fit configure this away, but you fit measure am. Run the same task for fresh session. If the rule hold 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. Wetin survive na wetin the summariser judge say important, and e no be the same thing wey you consider important. Claude Code document the result for each mechanism, and the differences big. 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 dem read matching file again. Nested CLAUDE.md files for subdirectories dey lost until dem read file for that subdirectory again.

Rank your instructions according to 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 inside packages/api/CLAUDE.md come next, because e load once, summary remove am, and e return only when dem read that directory again. Rule for project root file na the most durable, because dem dey read am from disk again every time.

So if instruction must hold for the whole session, put am for project root file without paths: frontmatter. Everything else na tradeoff wey you suppose choose deliberately. Managing wetin remain inside context window cover /compact with a focus argument and /clear between unrelated tasks, and both fit change how often the summariser get chance to 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 repository layer. The agent write a handler wey dey call ORM (object relational mapper) directly. E no ignore you because of style. Evidence simply outvote you.

A rule dey describe preference. The code dey show one preference. 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 information inside the rule. Rules wey mention their own counter-evidence dey survive when dem meet real repository. Rules wey only state bare preference no dey.

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

The second sentence na the part wey do the work. E tell the agent wetin e dey about to 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 ignore, or import convention wey only dey apply for new code. Anywhere code disagree with the file, name the disagreement inside the file.

Rule wey no get clear check no fit dey followed

"Write clean code." "Do not over engineer." "Keep it simple." "Be careful with migrations." You no fit test any of these 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.

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

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

"Do not over engineer" na the rule wey people dey give up on first, because the fix no be shorter sentence. E be longer one: spell out wetin the smallest change wey go work actually mean so agent fit get criteria wey e go use check its own diff against.

Size na the same problem with another name. Claude Code guidance target instruction file wey no pass 200 lines, and e state clearly say longer files reduce adherence. A 700 line file no be stronger instruction. Na 700 lines of claims wey get more chance to contradict each other. Plus, e dey use space for your window on every turn, and you go see am directly for your token usage. Arrange the file so each rule dey under heading wey reader fit scan. Writing an instruction file wey agent fit act on cover this. Better still, remove parts wey dey describe instead of instruct: directory tour wey show where handlers and models dey na structure wey agent fit look up when e need am from a parsed map of the repository, instead of carrying the information inside the window for every turn.

Wetin you fit check within 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, distance or compaction fit dey cause am. If e fail for here too, na the rule itself get problem.
3. Remove the competition. Ask for the same change inside directory wey existing code already follow the rule. If compliance return, 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 so.
5. Make am checkable and test again. Rewrite the rule with concrete path and condition. If compliance jump well-well, na the wording cause the problem.

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 before am, and e cost more to set up. Start from top when e cheap to change the wording of a rule. Move down as soon as the rule important reach level wey occasional miss 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 we show earlier. This one free, and e dey fix surprising number of cases.
2. Move it closer to wetin e govern. E fit be nested CLAUDE.md, path-scoped rule for .claude/rules/, or comment for the top of the file itself. The rule go come together with the code wey e apply to for the same read. Accept the tradeoff: anything wey load that way go comot for the next compaction and come back for the next matching read.
3. Move enforcement into a hook. Prose dey ask. Hook dey decide. Hooks dey run as code for fixed lifecycle events, and dem apply no matter wetin model conclude.
4. Give the rule to 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. 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 migration files must never be edited by agent. 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 new session and ask agent to edit 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 model as the blocking message. ${CLAUDE_PROJECT_DIR} go resolve to project root, so hook go work no matter which directory agent dey inside. Agent no need agree with the rule, remember the rule, or still get the rule for context. The edit no go happen.

For flat prohibition wey no get 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 instruction truly need dey for system prompt level instead of user message, --append-system-prompt go put am there, but you must pass am for every invocation. This one fit scripts pass interactive work.

Wetín you no fit instruct comot

Make am clear which part belong to you. Placement, wording, conflict between files, and file size na author problem, and na author 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 to you correctly, then break am two tool calls later. The acknowledgement no cost anything and e no predict anything. No take 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 fit come back under rule wey forbid dem, but at lower 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 need to be zero, the rule must comot from the prompt. Claiming say job don finish when part still remain undone na the same kind habit, and structural repair, no verbal repair, na the solution: the unlazy skill go replace the sentence with a Depth Tree and gate files wey agent must clear before e fit claim say e don finish.

Your own session go become example. If agent break the 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 when you see am. Violation wey you no correct dey teach the rest of the session.

Instruction file no be security boundary. E dey shape behaviour but e no enforce am. Anything wey fit cause serious loss if agent miss am, like credentials or destructive commands, belong for permissions or a hook. How to keep secrets away from agent dey apply the same principle to data: no ask agent not to read file; arrange make the file no dey readable.

The short version be this. Prove say file load, make the 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 you never ask agent to follow.

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 enter as user message after the system prompt, and dem dey treated as context, not enforced configuration. So, no strict compliance guarantee dey. Most real cases na one of four things: file dey for subdirectory wey agent never read, two files no agree 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 the instruction file in the middle of session fit change anything?

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

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

None of dem, reliably. Discovered files dey join together inside context instead of overriding each other. Dem dey ordered from filesystem root down to your working directory, so the closest file na simply the last one wey model read. No precedence engine dey resolve contradictions, and Claude Code documentation talk say contradictory rules fit dey 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 inject again from disk after compaction. Rules with paths: frontmatter and nested CLAUDE.md files for subdirectories go lost until matching file dey read again. Anything wey you only type for chat go survive only if summariser happen to 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 deterministic and the cost of missing am higher than the cost of writing small script. File path restrictions, commands wey must run before commit, and forbidden tool calls all qualify. A PreToolUse hook wey exits with status 2 go block the tool call completely and send your stderr text back to model as the reason. So e go hold whether the rule still dey anywhere inside context or not. Anything wey formatter or linter fit decide, make that tool own am, and delete am completely from instruction file.