Claude Code Not Following Instructions: A 93-Article Audit

Claude code not following instructions is almost never a wording problem. We audit this site's own corpus against its own standards documents, and on 2026-09-02 the audit covered 93 articles and 14 written rules: the five rules backed by a failing build or a failing script had zero violations, and the nine rules that exist only as sentences had 92. Same model, same always-loaded context, same author. The variable that predicts compliance is not how clearly the rule is written — it is whether anything breaks when it is not followed. The Claude Code guide covers how instruction files are loaded in the first place.

Key takeaways

• Across 93 articles: 3 build-enforced rules → 0 violations. 2 script-enforced rules → 0 violations. 9 prose-only rules → 92 violations.
• All 92 violations are one rule, and that rule is written down in four separate places, one of which is a mandatory pre-publish checklist.
• Naming the failure worked, partially. The share of violating files fell from 48.1% to 15.1% after the first audit, and 65 of the next 66 articles were clean.
• It did not hold. Article #74 relapsed after a 57-article clean run — and it is the article about how to write instruction files that agents will follow.
• The enforced rules stayed at zero across all 66 of those articles. Gated compliance did not decay at all.

The short answer

An instruction in CLAUDE.md is context. A check in package.json is a constraint. The model reads the first and can be argued out of it by any competing pressure inside a long turn; it cannot be argued out of the second, because the second is not addressed to the model at all — it is addressed to the build.

This is a follow-up rather than a first look. Article #27, Claude ignores CLAUDE.md, asked why a written rule loses and answered it with the mechanism: Anthropic ships CLAUDE.md as context, not configuration. That article measured 27 files. This one asks the question it could not: once the failure has been named and measured, does compliance improve, and does it stay improved? It measures 93.

What 93 articles say about written rules

The instrument is unchanged. scripts/check-content-rules.mjs scans every file in content/ against 14 rules lifted verbatim from CLAUDE.md and content-rules.md, and tags each rule by how it is backed — build if the MDX pipeline fails on it, script if an npm check catches it, prose if it exists only as a sentence.

npm run check:rules
# → 93 articles checked against 14 written rules.
# →
# → Enforced by the build — 3 rules, 0 violations
# →   clean
# → Enforced by an npm check — 2 rules, 0 violations
# →   clean
# → Written down only — 9 rules, 92 violations
# →   ordered-list: 92 in 14 file(s)

The three build-backed rules are markdown ![]() images, {expression} MDX attributes, and undefined components — each fails compilation with an explanatory message. The two script-backed rules are a stray # H1 and a #### heading, both caught by npm run check:anchors. Between them they cover the five rules that have never once been broken in 93 articles.

The relapse after 57 clean articles

The interesting number is not 92. It is what happened between the two audits.

Sixty-six articles were written between those two rows and they produced three new violations, all in a single file. Measured as a rate that is a large improvement — from nearly half the corpus down to one file in seven — and it is fair to call it real: naming a failure and pointing an instrument at it changed behaviour.

It did not make the rule durable. The 66 articles break down as 57 consecutive clean ones, then a relapse, then eight more clean ones. The relapse is article #74, published 2026-08-24, and it broke the rule three times in a single paragraph.

#74 is the article about AGENTS.md — the open standard for writing instruction files that AI coding agents will follow. The rule it broke is an instruction file rule. It broke it in the paragraph enumerating the three things an agent needs from an instruction file, and it broke it by writing that enumeration as a numbered list.

We did not plant that. It is what the scan returned, and it is the sharpest available evidence that a 57-article streak is not proof a rule is being followed. It is proof the rule has not been tested lately. The enforced rules, across the same 66 articles, moved from zero to zero.

The rule it ignored, and the fix

The rule is content-rules.md §4.9. Ordered lists are unstyled in this project: app/globals.css styles .prose-article ul with a disc marker and 22px of left padding and has no ol rule at all, so a numbered list renders with its numbers and its indent gone. The sequence the author wrote becomes invisible while the text still looks fine — which is exactly why nothing catches it by eye.

Here is what #74 shipped, at lines 108 to 110:

An agent needs three specific answers within milliseconds of reading a prompt:
1. **Verification commands:** The exact shell command to run to verify whether its edit succeeded.
2. **Import boundaries:** Which modules are private, server-only, or forbidden to import.
3. **Execution rules:** Idiosyncrasies of the build toolchain.

And the fix the rule actually asks for — bolded step labels inside a bullet list, which keeps the ordering visible in a list type the stylesheet supports:

An agent needs three specific answers within milliseconds of reading a prompt:
- **First — verification commands:** The exact shell command to run to verify whether its edit succeeded.
- **Second — import boundaries:** Which modules are private, server-only, or forbidden to import.
- **Third — execution rules:** Idiosyncrasies of the build toolchain.

That edit took under a minute and dropped the corpus from 92 violations in 14 files to 89 in 13.

npm run check:rules
# → Written down only — 9 rules, 89 violations
# →   ordered-list: 89 in 13 file(s)

The remaining 89 are deliberately still there. Thirteen of the fourteen violating files are articles #2 through #16, all published between 2026-07-27 and 2026-08-01 — the pre-audit baseline. Hand-fixing them would destroy the only longitudinal measurement this project has of the problem, and it would not prevent violation #93. The fix for that is structural, not editorial.

Why restating the rule did not work

Before concluding that the rule was unclear or buried, we counted where it is written. It appears four times:

• content-rules.md §4.9 — the rule itself, with the reason: <ol>, <blockquote> and <hr> are unstyled, prefer - bullets.
• content-rules.md §11 — a checkbox in the mandatory pre-publish review checklist: "No unstyled elements: no <ol>, no <blockquote>, no ####."
• content-rules.md §13 — the implementation-gaps table, listing the missing ol styling as open work.
• CLAUDE.md — the always-loaded project context, in the MDX authoring traps section.

Four statements, one of them a checkbox inside a gate described in the document as non-optional, one of them in the file that is loaded on every single request. Ninety-two violations.

Compare the two script-backed rules. Each is stated once. Neither has ever been broken.

This is the honest limit of the finding: we did not run a controlled experiment isolating wording from enforcement, and we cannot rule out that some rewording would work. What we can say is that four attempts at restatement, across two documents and one mandatory checklist, produced 92 violations, while two rules with a script behind them produced none — and that is the comparison available from a real corpus rather than a lab.

How to promote an instruction into a gate

The pattern that has worked here every time is to leave the sentence where it is and add something that fails.

• Cheapest — an npm check in the definition of done. A 40-line script that scans for the pattern and exits 1. This project has 60-odd of them and the two attached to rules have a perfect record. It only works if something runs it, which is the part people skip.
• Strongest — a build-time error. The three rules that fail compilation have never been broken by anyone, including a model with no memory of the rule. lib/mdx.ts maps markdown img to a thrown error with an explanatory message rather than silently rendering it.
• Most flexible — a hook. A PostToolUse hook that runs the check after every edit turns a periodic gate into an immediate one, and the agent sees the failure inside the same turn that caused it.
• Free but weak — permissions. A deny rule cannot express "do not write a numbered list", but it expresses "do not touch this path" perfectly. See Claude Code permissions for what that layer can and cannot encode.

The order matters. Reach for the strongest gate the rule can express, because the weaker ones depend on someone remembering to run them, and the audit above is a record of what remembering is worth.

One caveat worth stating plainly: a gate that is never wired to anything is a written rule with extra steps. This project's own check:rules exits 1 and has done for weeks, and it is not in CI. That is why the 89 are still there.

Best practices

• Write the rule once, then gate it. Restating is the intervention with four failures behind it in this corpus.
• Prefer a failure the agent sees inside the turn. A build error or a hook lands in the transcript; a checklist item does not.
• Attach the reason, not just the rule. §4.9 says why ordered lists are banned — the stylesheet has no ol rule. That is what lets an agent generalise instead of pattern-matching.
• Audit periodically, and expect a relapse. A 57-article clean run predicted nothing about article 58.
• Keep the instruction file short enough to be re-read. Length is not the mechanism, but a rule competing with 8 kB of other rules loses more often. See CLAUDE.md best practices.

Common mistakes

• Rewriting the instruction in stronger language. Bold, caps, and "IMPORTANT" are what you reach for when the real problem is that nothing fails. Four statements of this rule, one of them a mandatory checkbox, produced 92 violations.
• Reading a clean streak as compliance. Fifty-seven articles in a row followed the rule and the fifty-eighth broke it three times. Nothing about the configuration changed between them.
• Fixing the instances instead of the mechanism. We fixed one file — the one that proves the point — and deliberately left thirteen, because editing them changes the corpus and not the outcome.
• Assuming the model is the variable. The enforced rules held across 66 articles, several model versions and a version bump of the CLI. Same model, same context, opposite result, and the only difference is the gate.

Conclusion

If Claude Code is not following an instruction, stop editing the instruction and go find out what happens when it is broken. If the answer is "nothing", that is the bug, and the fix is a check that exits 1 rather than a sentence in bolder type. Write the rule once so the agent understands the intent, then attach it to the strongest gate it can express — and wire that gate to something that runs. Read Claude ignores CLAUDE.md next for why the file gets treated as context in the first place.

Frequently asked questions

Muhammad Kashif

Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.