SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-10-26

Why Coding Agents Dey Ignore Your Instructions

Your instruction file talk say stop, but the agent continue. Find out whether context, vague rules, conflicting code, or compaction na the real cause before rewriting am.

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 fit never enter the context window. The rule fit too vague to check any action against. Something else for the context fit contradict am, usually na the code wey agent just read. Or the rule still dey loaded but e dey far behind for the current turn, so 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 worked example, because dem don document im loading and compaction behaviour well as of October 2026. Other tools fit differ for details, but dem dey behave the same way for the main outline.

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 wey dey around the model, the thing wey dey read files from disk and assemble that block. Almost every complaint for this post really be 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. Every CLAUDE.md and CLAUDE.local.md from filesystem root reach your working directory dey load complete when e launch. Dem dey join for that order, so the file wey dey nearest to where you launch go read last. Inside one directory, .local file go 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 agent read file for that directory. The same thing apply to path scoped rules for .claude/rules/ wey get paths: frontmatter field: dem enter context when agent read matching file, no be for every turn. Since v2.1.309, files wey load this way get per-file size limit too (40,000 characters for 200K context window). Agent go receive only the beginning of longer file, so rules near the end of big nested file fit never enter context.

Na this difference dey explain plenty of the failures people report. You put rule for packages/api/CLAUDE.md, ask question about API, and agent answer without ever opening file under packages/api/. The rule no be say agent 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 affect repositories wey standardise on AGENTS.md. Since v2.1.277, Claude Code dey read AGENTS.md as your project instructions by default, but only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md dey your working directory or any directory above am (your personal ~/.claude/CLAUDE.md no count). Add any one of dem, even CLAUDE.local.md for personal notes, and Claude Code go read your CLAUDE.md files instead, then leave AGENTS.md out completely. To load both, set Project instructions to claude-md-and-agents-md for /config. For versions before v2.1.277, or when you want keep CLAUDE.md, the bridge na CLAUDE.md wey first line be @AGENTS.md. This one imports the file when e launch, with any Claude-specific notes underneath. Symlink dey work too when you no get anything extra to add. Deciding wetin suppose enter that file from the beginning na separate question, and how to split agent instructions from human documentation cover am.

Konfirm say file load before you rewrite am

No touch the wording until you get proof say the agent fit see the file. Two checks dey, and the cheap 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 load when session start. If file no dey that list, e no load when session start, so anything you write inside am no fit matter until something load am. Nested file for subdirectory no go show there, because e dey load on demand; when e load, a Loaded line with the path go appear for terminal. /memory dey list the file locations and open dem for editing, including files wey never exist yet.

For stronger answer, log the loads. The InstructionsLoaded hook event dey fire every time CLAUDE.md or rules file enter the context, and its matcher go 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. This event no dey use the exit status, so the hook fit only observe; e no fit block anything. If your nested file never show for that log during session wey you expect am, stop rewording. The problem na placement. One exception: an AGENTS.md wey Claude Code read directly no dey fire this event, so check its path for /memory instead. An AGENTS.md imported from CLAUDE.md dey fire am normally.

Wetin long session dey do to your rules

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

Distance. Before compaction run, rule wey you state for turn 1 still dey inside window for turn 90. But e dey compete with text from 90 turns wey dey more recent and more specific to wetin you dey do now. After compaction don run, rule wey you only type for chat fit no dey inside window again. Claude Code own documentation warn say instructions from early part of conversation fit disappear. Na this be the second effect below. You no fit configure distance comot, but you fit measure am. Run the same task for fresh session. If the rule work there but fail deep inside long session, distance or compaction na the cause.

Compaction. When window full, harness summarise the conversation so far and continue from that summary. Wetin survive na wetin summariser judge say important. E no always 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-inject from disk after compaction. Auto memory dey re-inject 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 inside 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 summary happen to keep am. Rule for packages/api/CLAUDE.md come next, because e load once, summary remove am, and e return only when dem read another file for that directory. Rule for project root file na the most durable one, because system dey read am again from disk every time.

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

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 use diagnose am within ten minutes

Run these ones in this order. If you jump go the last step, you fit end up with long file wey full of rules wey dem shout, but e still no work.

  1. Confirm say e load. Run /context and read the Memory files list, or if na nested file, find im Loaded line for terminal. If the file no dey there, correct 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 here but fail for long session, na distance or compaction fit dey cause am. If e fail here too, na the rule itself be the problem.
  3. Remove the competition. Ask for the same change inside directory wey im existing code already dey follow the rule. If compliance return, the code around am don outvote your sentence.
  4. Search for conflict. If two files give different guidance for the same behaviour, na documented failure be that: the model fit pick one anyhow, and e no go tell you say e do am.
  5. Make am easy to check and test again. Rewrite the rule with concrete path and condition. If compliance increase well-well, na the way you phrase am 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" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

If two files get different instructions, na your bug be that. Delete one. No try rank dem with stronger wording, because no ranking engine dey wey you fit appeal to. For Claude Code v2.1.283 or later, /doctor prompt-audit dey run broader version of this search across your instruction files, rules and skills, and e dey report contradictions with proposed edits without changing anything until you ask am.

The fixes, in order of leverage

Each step wey dey below get more leverage than the one above am, and e cost more to set up. Start from the top when e cheap to reword a rule. Move down as soon as the rule matter enough that 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 dey control. Use nested CLAUDE.md, a path-scoped rule for .claude/rules/, or 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 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 remove 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 complete. 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 this one 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 go block 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 the directory wey 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 permission modes decide wetin go run without asking you first. If instruction genuinely need dey for system prompt level instead of user message, --append-system-prompt go put am there. But na launch flag be this, and every new session need pass am again, so e 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 whether e load am before you conclude say e ignore am. Run /context and check the Memory files list; if file no dey that list, e no load when launch happen. Instruction files dey enter as user message after system prompt, and dem dey act as context instead of enforced configuration, so strict compliance no dey guaranteed. Most real cases na one of four things: the file dey inside subdirectory wey agent never read, two files disagree and model pick one anyhow, the rule too vague to use check action, or surrounding code dey show the opposite of wetin the rule talk.

Editing the instruction file for the middle of session go change anything?

No, e no go change the copy wey already dey inside conversation. Files above your working directory dey load complete when launch happen, so the text model get na the text from launch time. To make am use edit, start new session, or ask agent make e read the file with 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 arrive at that point too.

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

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 file wey dey closest simply dey read last. No precedence engine dey resolve contradiction, and Claude Code documentation talk say contradictory rules fit resolve anyhow. Write nested files as additions wey name the path dem control, 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 dey lost until matching file read again. Anything wey you only type for chat go survive only if summariser happen keep am. If rule must remain active throughout whole session, put am for project root file without paths: frontmatter.

When rule suppose become hook instead of prose?

When check dey deterministic and the cost of missing am pass 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 exit with status 2 go block tool call directly 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 formatter or linter fit decide suppose belong to that tool, and you suppose delete am completely from instruction file.

Dis article help you?