Context Engineering for AI Coding Tools in 2026: CLAUDE.md, Cursor Rules, AGENTS.md, and Spec Files That Actually Work

By AICoderScope Team · 13 min read
claude-codecursorclinecopilotagents-mdsetup-guideworkflowcontext-engineering

TL;DR: Whether Claude Code or Cursor ships correct code on the first attempt is mostly decided before you type the prompt — by what the agent reads at session start. The winning layout in 2026: one AGENTS.md as the cross-tool base, tool-native scoped rules on top, and a per-feature spec file for anything multi-step. Keep every always-loaded file under ~200 lines; past that, adherence drops.

What you’ll be able to do after this guide:

  • Structure a CLAUDE.md that Claude Code actually follows — and verify it loaded with /context instead of guessing
  • Scope Cursor and Claude Code rules by file path so they only spend context when the agent touches matching files
  • Run one AGENTS.md across Claude Code, Cursor, Cline, and GitHub Copilot without duplicating instructions in four formats

Honest take: Most teams’ problem isn’t a missing context file — it’s a bloated one. A 400-line CLAUDE.md stuffed with directory listings the agent can derive itself performs worse than a 60-line file that names the build command, the test command, and the five conventions that differ from tool defaults. Write the short file first; add scoped rules only when the agent makes the same mistake twice.

The context budget is the product

Every AI coding agent starts each session with a fresh context window, then loads your instruction files into it before reading a single line of your code. Those files compete with your actual codebase for the same token budget, on every turn, for the life of the session.

That’s why “more context” stops helping fast. Anthropic’s memory documentation is unusually blunt about it: CLAUDE.md content is “context, not enforced configuration,” files should target under 200 lines because “longer files consume more context and reduce adherence,” and a file over 4 MiB is skipped entirely. Instructions land as a user message after the system prompt — the agent reads them and tries to comply, with no guarantee. The more specific and concise the file, the more consistently it’s followed.

So context engineering in 2026 is two decisions, repeated:

  1. What must the agent hold in every session? (Goes in the always-loaded file.)
  2. What only matters sometimes? (Goes in a path-scoped rule, a skill, or a spec file that loads on demand.)

Get the split wrong in one direction and the agent asks three clarifying questions before touching code, or worse, invents conventions — wrong import style, wrong test framework, handlers in the wrong directory. Get it wrong in the other direction and you’re paying for 2,000 tokens of directory tree on every request while the instructions that matter drown in the middle.

Who reads what in 2026

Four tools, four native formats — plus one shared one. Verified Aug 31, 2026 against the official docs for Claude Code, Cursor, Cline, and GitHub Copilot:

ToolAlways-loaded project filePath-scoped rulesReads AGENTS.md?
Claude CodeCLAUDE.md (root or .claude/).claude/rules/*.md with paths: frontmatterVia @AGENTS.md import or symlink — not natively
Cursor.cursor/rules/*.mdc with alwaysApply: true.mdc rules with globs:Yes, natively
Cline.clinerules/ folderPer-file rule togglesYes, as fallback; plus global ~/.agents/AGENTS.md
GitHub Copilot.github/copilot-instructions.md.github/instructions/*.instructions.md with applyTo:Yes, coding agent since Aug 2025, nested files included

The pattern that fell out of this convergence: AGENTS.md is the base layer, native formats are the overrides. Write the instructions every tool needs once, then keep only tool-specific behavior (Cursor activation modes, Claude Code hooks, Copilot path scoping) in the native files.

CLAUDE.md: the 200-line discipline

Claude Code loads CLAUDE.md from your working directory and every directory above it, concatenated broadest-first, plus ~/.claude/CLAUDE.md for personal preferences and an optional gitignored CLAUDE.local.md. Subdirectory CLAUDE.md files don’t load at launch — they’re pulled in when the agent reads files in those directories, which is the cheap way to give a monorepo package its own instructions.

What earns a line in the file, per Anthropic’s own guidance: build and test commands, conventions that differ from defaults, “always do X” rules, and anything you’ve re-explained twice. What doesn’t: architecture overviews, dependency lists, directory layouts — everything the agent can derive from the code. The /doctor command now proposes exactly these trims on checked-in CLAUDE.md files.

Specificity is the difference between a rule that works and one that gets skipped. The docs’ own examples draw the line well — “Use 2-space indentation” beats “Format code properly”; “Run npm test before committing” beats “Test your changes.” A rule you can verify is a rule the agent can follow.

For everything that only matters sometimes, use .claude/rules/ with paths: frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates input with zod before touching the DB
- Errors use the envelope in src/api/errors.ts — never raw strings

Rules without a paths: field load at launch like CLAUDE.md; rules with one load only when the agent reads a matching file. That’s the context-budget knob most Claude Code setups never touch. (Slash commands, subagents, and hooks are the next layer up — covered in our Claude Code power-user setup.)

Two verification habits close the loop. Run /context and check the Memory files list — if your file isn’t there, the agent literally cannot see it, and no amount of rewriting will help. And for anything that must happen — a lint gate before every commit, a blocked path — use a hook, not an instruction. The docs are explicit that memory files shape behavior while hooks enforce it.

One trap we hit setting this up: the @path import syntax is live everywhere in a CLAUDE.md, not just in a dedicated imports section. We wrote “see @README for details” as prose and Claude Code expanded the entire README into context at launch — imports load at startup and don’t save tokens, they just organize files. The documented fix is backticks: `@README` stays literal text, @README imports the file. If your context window looks mysteriously full at session start, audit your CLAUDE.md for bare @ references. (Block-level HTML comments, by contrast, are free — Claude Code strips <!-- --> before injection, so maintainer notes cost zero tokens.)

Cursor rules: activation modes are the budget knob

Cursor moved from the single .cursorrules file to the .cursor/rules/ directory of .mdc files back in late 2024, and that’s still the system in 2026 — the legacy file is deprecated but still read, so old projects don’t break. Each .mdc file carries three frontmatter fields that decide when it loads:

---
description: Standards for React components
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

That maps to four activation modes: Always (alwaysApply: true — in context on every request), Auto Attached (loads when a file matching globs enters the conversation), Agent Requested (the model reads the description and decides), and Manual (only when you invoke it with @ruleName). Cursor’s docs cap individual rules at roughly 500 lines, but the always-apply slot is where discipline pays: every alwaysApply: true rule taxes every single request, exactly like an oversized CLAUDE.md.

The layout that holds up in practice: one short always-on rule for universal conventions, three or four auto-attached rules scoped by file type, and manual rules for occasional workflows like release notes. Nested .cursor/rules/ directories work in monorepos — a frontend/.cursor/rules/ applies only in that subtree. We published tested, copy-paste Cursor rule templates and a primer on the rules workflow if you want the concrete starting point rather than the theory.

AGENTS.md: write it once, everything reads it

AGENTS.md is the open format that answered the obvious question: why maintain four dialects of “here’s how to build and test this repo”? It’s a plain markdown file at the repo root — no required schema — covering setup commands, test protocol, and contribution standards. Tool support crossed the threshold from experiment to standard when GitHub’s Copilot coding agent added it (including nested AGENTS.md files for monorepo subtrees) while continuing to read CLAUDE.md too. Cursor reads it natively from the root and subdirectories. Cline treats it as the fallback when no .clinerules/ folder exists and additionally reads a global ~/.agents/AGENTS.md.

Claude Code is the notable holdout — it reads CLAUDE.md, not AGENTS.md — but the official docs ship the bridge pattern:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The import loads AGENTS.md at session start, then appends Claude-specific lines below. If you have nothing tool-specific to add, a symlink does the same job:

ln -s AGENTS.md CLAUDE.md

The command prints nothing on success; run /context in your next session and confirm CLAUDE.md shows under Memory files. (On Windows, symlinks need Developer Mode — use the @AGENTS.md import instead.) Claude Code’s /init will also fold existing .cursor/rules/, .cursorrules, and .github/copilot-instructions.md content into a generated CLAUDE.md, which is the fastest migration path for a repo that accumulated rule files tool by tool.

If your stack includes open-source agents — Aider, Goose, OpenCode and the rest of the FOSS coding-agent field — the same logic applies: the cross-tool file is the one that survives tool churn. And if those agents run against a local backend, remember the instruction files bite twice: an 8K-context local model loses a meaningful slice of its window to an oversized always-loaded file before work begins. We’ve seen that failure mode repeatedly in local setups — it’s cousin to the Ollama num_ctx trap, and sizing the model’s window to fit real context loads is a hardware question our sister site covers in its local model VRAM guide.

Spec files: context for the task, not the repo

CLAUDE.md and rules describe the repository. For a multi-step feature, the agent also needs the task pinned down, or it drifts by step three. That’s the gap spec files fill, and GitHub’s open-source spec-kit turned the practice into tooling: a specify CLI (Python 3.11+, installed via uv) that scaffolds slash commands across 30+ agents including Claude Code, Copilot, and Cursor. Its pipeline runs /speckit.constitution (project principles) → /speckit.specify (requirements and user stories) → /speckit.plan (technical approach) → /speckit.tasks (work breakdown) → /speckit.implement, with a /speckit.converge phase that audits the codebase against the spec afterward.

You don’t need the toolkit to get the benefit. A spec.md in the feature branch — what’s being built, what’s explicitly out of scope, acceptance criteria, files expected to change — referenced in your prompt does most of the work. The mechanism is the same one that makes short CLAUDE.md files work: the agent stops guessing intent because intent is written down. The difference shows up in agent fan-out especially; a subagent spawned mid-task inherits none of your conversation, so the spec file is often the only shared ground truth (subagent routing makes that concrete).

What goes where

ContentWrong placeRight place
Build/test commands, naming conventionsA 300-line always-on ruleAGENTS.md (≤200 lines), imported by CLAUDE.md
Framework rules for one file typeCLAUDE.mdAuto-attached .mdc rule / .claude/rules/ with paths:
Multi-step procedure (release, migration)CLAUDE.mdA skill or slash command — loads only when invoked
”Never push to main,” lint gatesAny instruction fileA hook or branch protection — enforcement, not context
Current feature’s requirementsThe chat prompt, retyped dailyspec.md in the branch
Directory layout, dependency listAnywhereNowhere — the agent derives it from the code

The before/after is easy to reproduce on your own repo. Ask an agent in a bare project to “add rate limiting to the API” and you’ll get clarifying questions — which framework? middleware or per-route? where do errors go? — or silent guesses on all three. Give it a 60-line file naming Express, the middleware directory, the error envelope, and npm test as the gate, and the same prompt returns a mergeable diff in one pass. Anthropic’s docs describe exactly this failure signature from the other side: vague or conflicting instructions get followed inconsistently, and when two rules contradict, the model “may pick one arbitrarily.” The fix is never a longer file. It’s a sharper one.

FAQ

Should I keep both CLAUDE.md and AGENTS.md? Keep AGENTS.md as the single source and make CLAUDE.md a one-line @AGENTS.md import (plus any Claude-specific additions) or a symlink. Duplicating content guarantees the two files drift, and conflicting instructions measurably degrade adherence.

Is .cursorrules dead? Deprecated, not dead — Cursor still reads a legacy .cursorrules file, but new rules belong in .cursor/rules/*.mdc, which adds activation modes, glob scoping, and nested directories the single file never had.

How big is too big for an always-loaded file? Anthropic’s docs say target under 200 lines per CLAUDE.md; Cursor’s guidance caps rules around 500 lines, with always-apply rules kept far smaller. If a file needs more, that’s the signal to split it into path-scoped rules — splitting into @ imports alone organizes the text but still loads every token at launch.

Do instruction files work with local models? Yes — Cline, Continue.dev, and Aider all apply their rule files regardless of backend. But the context math is harsher: a 3,000-token instruction load is background noise in a 200K cloud window and a real tax on a local model at 8K–32K. Trim harder, and check the model’s effective window actually matches what the tool requests.

Can I make an instruction mandatory? No — instruction files are suggestions the model usually follows, not policy. Claude Code’s docs route hard requirements to hooks (shell commands at fixed lifecycle events) or permission rules; Copilot and Cursor equivalents are branch protection and CI. If violating the rule must be impossible, it doesn’t belong in a markdown file.

Sources

Last updated August 31, 2026. Tool behavior and file-format support change frequently; verify current state in the official docs before restructuring a team setup.

Was this article helpful?

Know which coding tool is worth paying for

Hands-on comparisons of AI coding assistants and what each one costs to run — including the local-model path. Sent only when something changes. Unsubscribe anytime.