Originally published on clogmeter.vercel.app.

Put always-on facts in AGENTS.md / CLAUDE.md, put procedures in skills, and put tools in MCP — not instructions. That is a cost decision, not a style preference.

What each layer actually loads

Anthropic's Claude Code steering guide makes the same split: root CLAUDE.md is high context cost, skills load the body on demand, and hooks enforce "never" rules outside markdown. Cursor's rules docs mirror it with alwaysApply, globs, and description-based rules.

A simple decision rule

1. Would you ask a new teammate to memorise this before their first PR? If yes, it can live in the root instruction file. If no, move it.
2. Is it a procedure ("when releasing, do these 8 steps")? Put it in a skill so the body loads only when that work starts.
3. Is it a capability ("query Postgres", "open a PR")? That is MCP (or a built-in tool), not an instruction file. Do not paste API docs into AGENTS.md to fake a tool.
4. Must it never fail? Markdown is advisory. Use a hook, linter, or CI check for true guardrails.
5. Does it only apply under src/api/**? Prefer a path-scoped Cursor rule or nested CLAUDE.md over stuffing the root file.

Where people usually go wrong

• Procedures in the root file. A 30-line release checklist in AGENTS.md taxes every chat, including ones that never ship.
• Instructions stuffed into MCP. MCP is for tools. Long server instructions and eager schemas are a silent token tax every turn the server stays connected.
• Everything set to always-on. Cursor alwaysApply: true and unscoped Claude rules behave like root CLAUDE.md: paid whether relevant or not.
• The same rule in three places. A "never commit secrets" line in AGENTS.md, a skill, and an MCP blurb wastes tokens and invites contradictions.

Rules that should "almost always" apply but are not worth a permanent tax belong in a skill with a tight description, or a Cursor rule with a clear description / globs — not in the root file "just in case."

How to migrate without guessing

1. Paste your root AGENTS.md / CLAUDE.md and always-on Cursor rules into Clogmeter.
2. Cut anything the agent can discover by reading the repo (long architecture essays, pasted READMEs).
3. Move multi-step workflows into skills; leave only pointers in the root file.
4. Audit connected MCP servers: disable ones you are not using this session, and keep schemas lean.
5. Re-weigh. The always-on budget should shrink; skill bodies and MCP stay available when needed.

If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, I built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.

Originally published on clogmeter.vercel.app.

When AGENTS.md, CLAUDE.md, Cursor rules, and skills all load, the agent does not get “more guidance” — it gets three copies of the same rule and often one quiet contradiction. Always/never pairs that disagree burn tokens twice and teach the model to hedge.

Quick fix: open every instruction file side by side and search for the same verb (“never commit”, “always run tests”). Keep one canonical line in a single source of truth; delete or @-import the rest. Then weigh what is left.

If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, I built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.

Originally published on clogmeter.vercel.app.

On X and Reddit, “Cursor is ignoring my rules” is often not an adherence problem — the rule never entered context. Cursor project rules live in .cursor/rules/ as .mdc files with YAML frontmatter. A plain .md in that folder is ignored. Cursor also reads root AGENTS.md / CLAUDE.md as simpler always-on markdown.

Checklist below matches Cursor’s public Rules docs (keep rules under 500 lines; split large ones).

Five checks before you rewrite the rule

1. Extension: file must end in .mdc inside .cursor/rules/.
2. Frontmatter fields: only description, globs, and alwaysApply control load mode.
3. Always Apply: alwaysApply: true puts the rule in every chat (use sparingly — it costs tokens every turn).
4. File-scoped: set globs and alwaysApply: false so it attaches when matching files are in context.
5. Apply Intelligently / manual: a description without globs lets the agent decide; with neither description nor globs nor alwaysApply, you typically need to @-mention the rule.

Minimal working example

---
description: TypeScript conventions for this repo
globs:
  - "**/*.ts"
  - "**/*.tsx"
alwaysApply: false
---

- Prefer explicit return types on exported functions
- Follow the patterns in @src/lib/result.ts instead of inventing new Result helpers

If it loads but still feels ignored

• Vague wording: “write clean code” loses to “use 2-space indentation” — Cursor’s docs ask for actionable rules.
• Conflicts: the same always/never restated differently across AGENTS.md and several .mdc files makes the model hedge. Cut one canonical line first.
• Too much always-on: large always-applied rules compete with the task. Prefer globs/skills for procedures.
• Stale pasted docs: reference canonical files; don’t paste whole style guides (Cursor explicitly warns against this).

Prefer a short AGENTS.md example for cross-tool basics, and reserve .mdc for activation control. Compare formats in CLAUDE.md vs AGENTS.md vs Cursor rules.

If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, I built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.

Originally published on clogmeter.vercel.app.

Short answer: aim for a lean always-on file — roughly under 200 lines per CLAUDE.md (Anthropic’s documented target) and treat Cursor project rules as under 500 lines each, split by concern. There is no universal “perfect” line count. The real limit is whether the model still follows the rules that matter once system prompt, tools, skills and the task compete for the same attention budget.

No invented benchmarks here. The numbers below come from vendor docs and published guidance as of late 2026.

What the tools themselves say

Community write-ups often talk about a practical “~150 instruction” attention budget for frontier models before adherence drops — that is research/context, not a hard file limit. Your instruction file shares that budget with the agent’s system prompt and tool descriptions, so leave headroom.

Why bloated files get ignored

• Everything always-on costs every turn. Root CLAUDE.md / AGENTS.md is re-read at session start; fat files tax every message and every general-purpose subagent.
• Markdown is advisory. Claude Code docs treat memory files as context, not enforced config. A “never” in prose can still be skipped; hooks and permissions enforce must-holds.
• Conflicts cancel each other. Duplicate or contradictory always/never rules across files make the model pick arbitrarily.
• Long sessions compress early rules. Mid-thread, package-manager or style rules often shrink first while code stays — which feels like “Cursor/Claude is ignoring my rules.”

A practical size checklist

1. Measure first. In Claude Code, run /context (and /doctor for trim proposals). For any stack, paste the files into Clogmeter to see token weight vs common windows and spot duplicates/conflicts.
2. Keep always-on content tiny. Project identity, hard constraints, build/test commands, and pointers. Delete anything the agent can discover by reading the repo.
3. Move procedures to skills. Release checklists and long how-tos should load on demand, not on every prompt.
4. Scope directory rules. Nested AGENTS.md / path-scoped Cursor or .claude/rules files beat one giant root file.
5. Enforce never-rules outside markdown. If ignoring it once would hurt, use a hook, linter or CI check.
6. One source of truth. Prefer a canonical AGENTS.md with thin CLAUDE.md / Cursor adapters instead of divergent copies.

How long is “too long” in practice?

If the root file is hundreds of lines, mixes architecture essays with one-off workflows, or repeats the same rule in three places, it is already too long for reliable adherence — even if the model still “sees” the file. Vendors warn that longer instruction files reduce compliance before hard truncation kicks in (Codex’s 32 KiB cap being the blunt case).

A useful rule of thumb many teams use: if you would not ask a new teammate to memorise the whole file before their first PR, do not force the agent to either. Make the root file the map; put the territory in scoped docs and skills.

If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, I built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.