# Three ways your coding agent silently never reads your instructions > Source: > Published: 2026-09-07 06:53:57+00:00 You write instructions for your coding agent. It ignores one of them. You rewrite it more forcefully, in bold, with "IMPORTANT" in front. It still ignores it. Before blaming the model, check whether it ever saw the text. Each of the three cases below is documented behaviour of a tool you already use, each one drops part of your instructions on the floor, and none of them prints a warning. `.md` files in `.cursor/rules` Project rules in Cursor must use the `.mdc` extension. [Cursor's own docs](https://cursor.com/docs/context/rules) put it plainly: a plain `.md` file there is ignored by the rules system, because it has nowhere to declare the `description`, `globs` and `alwaysApply` frontmatter that tells Cursor when to apply it. So a file sitting in exactly the right directory, with exactly the right content, does nothing. No error at startup, no "rule skipped" line, nothing in the UI. Ten-second check: ``` find .cursor/rules -name '*.md' 2>/dev/null ``` Any output is a rule that isn't loading. Rename to `.mdc` and add the frontmatter. A detail that makes this worse: people who set up `.md` rules a while ago report that they *used to* work. If that's right, a working setup stopped working at some point during an update, and nothing announced it — so "I checked this once" is not protection. Codex reads the AGENTS.md files that apply to your working directory: a global one, the repo root, and the nested ones on the path. It concatenates them, and the 32 KB truncation applies to **that combined payload**. This is the part that catches people, because every individual file looks fine: ``` AGENTS.md 12 KB ✓ fine packages/api/AGENTS.md 12 KB ✓ fine packages/web/AGENTS.md 12 KB ✓ fine ----- 36 KB ✗ 4 KB never reaches the model ``` Nobody wrote a "too big" file. The rule you carefully put at the bottom of the last one simply isn't there when the model reads. Check it: ``` find . -name AGENTS.md -not -path '*/node_modules/*' | xargs wc -c ``` Add your global `~/.codex/AGENTS.md` to the total, and remember only the files on the path to your working directory get concatenated — a file under `packages/web` doesn't count against you while you're working in `packages/api`. I hit a real one while testing this: a checkout with four AGENTS.md files totalling 65.6 KB, 33.6 KB of it truncated away, no single file anywhere near the limit. Skills load their body on demand, which is the point — but the model only knows a skill exists from its listing, and [the docs are specific](https://code.claude.com/docs/en/skills): the combined `description` and `when_to_use` text is truncated at **1,536 characters** in that listing. Write a thorough description with five trigger examples and the last two are gone. The skill still exists, still works when invoked by name, and quietly stops being chosen on its own — which reads exactly like "the model is being lazy". Put the key use case in the first sentence. Detail belongs in the body, which costs nothing until the skill runs. All three share a shape worth internalising: **the failure is invisible from the inside.** Your file is on disk. Your editor shows it. Code review shows it. The agent read a subset of it and had no way to tell you which part. Regular documentation rots the same way, but a human reader notices when a doc is stale — the paths look wrong, the commands don't exist any more. An agent doesn't notice. It follows the text with complete confidence, including the part that stopped being true in March. That second half is measurable. I scanned 118 popular open-source repositories with agent context files: **59% contained at least one hard dead reference** — a file path or a script the instructions still name and the repo no longer has. Careful teams, well-maintained projects; the rot is just silent. The manual checks above take a minute and catch a lot. Beyond that: `@AGENTS.md` import inside CLAUDE.md works; a symlink works when the content is genuinely identical; two hand-maintained copies drift within a week. For the automated version I wrote [driftlint](https://github.com/alifurkangokce/driftlint) (disclosure: mine, MIT, zero runtime dependencies, no account, nothing leaves your machine): ``` npx @alifurkangokce/driftlint ``` It checks all three limits above plus the drift half: dead file paths with did-you-mean fixes, removed npm scripts and make targets, markdown links whose target or heading moved, hooks and MCP servers pointing at scripts that don't exist, and CLAUDE.md ↔ AGENTS.md copies that have diverged. But the tool is secondary. The idea worth keeping is the first one: when an agent ignores an instruction, check whether it was ever handed the instruction. Half the time, it wasn't.