AGENTS.md vs CLAUDE.md vs Cursor Rules vs Skills vs MCP: What Actually Belongs Where?
I use multiple AI coding agents in my development workflow.
Claude Code for some tasks. Codex for others. Cursor when I want to work directly inside the editor.
At first, my approach was simple:
Give each AI tool enough instructions to understand the project.
That worked. Until it didn't.
My repositories gradually started accumulating instructions everywhere:
AGENTS.md
CLAUDE.md
.cursor/rules/
README.md
architecture docs
feature plans
skills
MCP configurations
random prompts
Many of these files contained overlapping information. I was mixing project conventions, architecture decisions, feature requirements, and agent workflows into the same documents. Whenever I updated a rule, I had to remember where else I'd duplicated it.
The problem wasn't that my agents needed more context.
The problem was how I organized that context.
So I started separating shared repository knowledge from tool-specific instructions and task-specific requirements.
This article explains the structure, why I use it, and how to avoid a subtle configuration problem that can make Claude Code silently ignore your shared AGENTS.md.
Important: This is my approach, not a universal standard. Each coding agent has its own instruction discovery behavior, and that behavior changes between releases. Tool-specific details below were checked against official documentation in September 2026. Always confirm against your tool's current docs.
1. The Problem: Every AI Agent Needs Context
Imagine you're developing a production application using:
- Next.js and TypeScript
- React Server Components
- A backend API
- Authentication and permissions
- Shared UI components
- Automated tests
- Established architectural conventions
You ask your coding agent:
Add filtering to the users page.
That sounds straightforward. But the agent needs answers to several questions:
- Does the application already have a reusable filter component?
- Are filters stored in URL parameters?
- Does the backend already support filtering?
- Where should data fetching happen?
More importantly: which existing patterns should the agent preserve?
Without sufficient context, an agent might introduce a second filtering system instead of extending the existing one.
That's where AI-generated code becomes expensive. Not because the code is incorrect, but because it doesn't fit the existing system.
2. My First Mistake: The Giant Instruction File
Initially, I put almost everything into one instruction file:
- Project architecture
- Folder structure
- Coding conventions
- API conventions
- Testing instructions
- Deployment instructions
- Feature requirements
- Git workflows
- UI guidelines
It became difficult to maintain. Permanent instructions, temporary requirements, and reference documentation were all competing for the same space.
A small UI change didn't need deployment documentation. A backend bug didn't need animation guidelines. And a feature requirement shouldn't permanently live alongside repository-wide conventions.
It also has a real cost: instruction files are loaded into the agent's context, so every line consumes space that could be used for the actual task. Claude Code's documentation, for example, recommends keeping each CLAUDE.md under roughly 200 lines, because longer files reduce adherence.
More context is not automatically better context.
3. The Mental Model I Use Now
I separate context by responsibility:
| Context | Responsibility | Example |
|---|---|---|
AGENTS.md |
Shared repository instructions | Commands, conventions, boundaries |
CLAUDE.md |
Claude-specific instructions and imports | Imports AGENTS.md, adds Claude-only guidance |
.cursor/rules/ / .claude/rules/
|
File-scoped instructions | Rules that apply only to frontend or API files |
Intent documents (intent/*.md) |
Task-specific requirements | Expected behavior and acceptance criteria |
docs/ |
Durable project knowledge | Architecture, authentication, API design |
| Skills | Repeatable agent workflows | Code review, regression analysis |
| MCP | External tools and data access | GitHub, issue trackers, documentation |
Repository instructions explain how an agent should work. Intent documents explain what a particular change should accomplish. Documentation explains how the system works.
A note about compatibility
All three tools support AGENTS.md, but they don't discover it the same way:
| Tool | How it finds instructions |
|---|---|
| Codex | Reads AGENTS.md from your Codex home directory, then walks from the project root down to your current directory, loading at most one file per directory. AGENTS.override.md takes priority over AGENTS.md in the same directory. Combined instructions are capped at 32 KiB by default. |
| Claude Code | Reads CLAUDE.md files. Since v2.1.277 it can also read AGENTS.md directly, but by default only when no CLAUDE.md or CLAUDE.local.md exists (details in section 5). |
| Cursor | Reads AGENTS.md in the project root and nested subdirectories (applied when working with files in that directory), alongside its own .cursor/rules/ system. |
One consequence: nested AGENTS.md files behave differently across tools. Cursor applies them when the agent works with files in that folder. Codex only includes them when you start Codex inside that folder (or below it).
The goal isn't to force every agent into an identical configuration. It's to maintain shared knowledge once and add tool-specific instructions only where they add value.
4. AGENTS.md: Shared Repository Instructions
I treat AGENTS.md as the single source of shared repository guidance. It contains what stays true regardless of which feature I'm implementing.
A simplified example for a Next.js application:
# Project
Next.js application using TypeScript and App Router.
## Commands
- Install dependencies: npm install
- Development: npm run dev
- Tests: npm run test
- Lint: npm run lint
- Build: npm run build
## Architecture
- Follow the existing App Router architecture.
- Prefer Server Components unless interactivity
or browser APIs require Client Components.
- Reuse existing UI components before creating new ones.
- Use the API client in src/lib/api for all backend calls.
## TypeScript
- Avoid `any`; prefer existing and inferred types.
- Derive types from Zod schemas where a schema exists.
## Implementation
- Investigate existing implementations before
introducing new abstractions.
- Keep changes scoped to the requested task.
- Before reporting completion, run lint and the
tests for the affected modules.
## Documentation
- Use docs/architecture.md for service boundaries
and architectural changes.
- Use docs/authentication.md for authentication changes.
- Use docs/api.md for API integration changes.
Two things to notice.
First, the file points to documentation instead of containing it. It says when each document is relevant rather than "read all of these before every task." A typo fix shouldn't require the same investigation as an authentication redesign.
Second, instructions are specific enough to verify. "Use the API client in src/lib/api" is more useful than "follow the established API patterns." Vague instructions get interpreted; specific ones get followed.
Also revisit your instructions as models improve. Guidance like "always run tests" was essential for older models. Some newer models do this on their own, and OpenAI has noted that such instructions can now cause unnecessary extra work. Keep what's still needed; delete what isn't.
5. CLAUDE.md: Claude-Specific Instructions
This is where the subtle configuration problem lives.
Claude Code can read AGENTS.md directly, but its default behavior depends on which files exist:
| Your repository has | Claude Code reads (default) |
|---|---|
AGENTS.md only |
AGENTS.md |
AGENTS.md and a CLAUDE.md or CLAUDE.local.md
|
Only the CLAUDE.md files |
A CLAUDE.md that imports @AGENTS.md
|
CLAUDE.md, with AGENTS.md included |
The trap is the second row.
Imagine your team relies on a shared AGENTS.md. Then someone creates a personal, gitignored CLAUDE.local.md for their own sandbox URLs. From that moment, Claude stops reading AGENTS.md for that person, with no error, while everyone else's setup works fine.
So I make the relationship explicit. My CLAUDE.md looks like this:
@AGENTS.md
# Claude-Specific Instructions
For complex architectural changes:
- Investigate the affected implementation.
- Identify existing reusable patterns.
- Explain significant architectural trade-offs
before editing.
When investigating regressions:
- Trace the affected execution path.
- Identify the underlying cause.
- Check related implementations for similar issues.
The @AGENTS.md line imports the shared instructions. Everything below it is Claude-only guidance.
This works regardless of which other files exist, and according to Anthropic's documentation, keeping the import never causes AGENTS.md to load twice.
Alternatives, depending on your situation:
-
Change the default. In Claude Code, run
/configand set Project instructions toclaude-md-and-agents-mdto always load both. -
Use a symlink (
ln -s AGENTS.md CLAUDE.md) if you have no Claude-specific content. Avoid this if anyone on the team uses Windows: Git checks out committed symlinks as plain text files unlesscore.symlinksis enabled.
Claude Code also supports file-scoped rules in .claude/rules/ using paths: frontmatter, the equivalent of Cursor's glob-based rules:
---
paths:
- "src/app/api/**/*.ts"
---
# API Route Rules
- Validate request input with the existing Zod schemas.
- Use the shared error response format.
Reference: Claude Code: How Claude remembers your project
6. Cursor Rules
Cursor supports AGENTS.md for plain instructions and .cursor/rules/ for structured, scoped rules.
my-project/
├── AGENTS.md
│
└── .cursor/
└── rules/
├── frontend.mdc
└── backend.mdc
Project rules must use the .mdc extension. A plain .md file in .cursor/rules/ is ignored.
A frontend rule scoped to specific files:
---
description: Frontend development conventions
globs: src/components/**/*.tsx, src/app/**/*.tsx
alwaysApply: false
---
# Frontend Rules
- Follow the existing component architecture.
- Reuse shared UI components.
- Preserve accessibility behavior.
- Check responsive layouts when modifying UI.
Note that globs is a comma-separated string, as shown in Cursor's documentation.
How the frontmatter fields interact:
alwaysApply |
description |
globs |
Behavior |
|---|---|---|---|
true |
any | any | Always included |
false |
any | set | Auto-attached when a matching file is in context |
false |
set | not set | Agent decides based on the description |
false |
not set | not set | Only when you @-mention the rule |
I keep common rules in AGENTS.md and use .mdc files only for guidance that should apply to specific parts of the codebase. I never copy shared instructions into every rule file.
Watch for conflicts. Cursor merges Team Rules, Project Rules, User Rules, and AGENTS.md. Contradictory instructions across these sources produce inconsistent behavior, so keep each rule in exactly one place.
Reference: Cursor Rules documentation
7. Intent Documents: What Are We Actually Trying to Change?
Repository instructions explain how to work. Architecture documentation explains how the application works. Neither explains what a particular change should achieve.
That's what intent documents are for. I keep one per feature in an intent/ folder.
Important: This is a convention in my workflow, not an official standard. No coding agent discovers these files automatically. You point the agent to the relevant file in your prompt.
Consider this requirement:
Users should be able to filter orders by delivery status.
I create intent/order-status-filter.md:
# Intent: Order Status Filtering
## Objective
Allow users to filter orders by delivery status.
## Expected Behavior
Users can select multiple statuses:
- Pending
- In Progress
- Completed
- Cancelled
Selected filters must persist in URL parameters.
## Constraints
- Reuse the existing table filtering architecture.
- Do not introduce a second filtering system.
- Do not change backend endpoints.
## Acceptance Criteria
- Multiple statuses can be selected.
- Refreshing preserves the selected filters.
- Clearing filters restores the complete list.
- Existing pagination continues working.
Now the agent has a definition of success, and I have a reference for code review. I compare the implementation against the acceptance criteria instead of relying on the agent's summary of what it did.
I covered this approach in more depth in a previous article (which used a single intent.md file; the per-feature folder is how I organize it now):
What Is intent.md in Claude Code? A Practical Guide with an Example
8. Architecture Documentation: Explain the System
Some information deserves more detail than an instruction file should hold:
- Authentication and authorization flows
- Multi-tenant architecture
- API integration patterns
- Background job processing
- Database design
- Deployment architecture
I keep that in dedicated documents:
docs/
├── architecture.md
├── authentication.md
├── permissions.md
├── api.md
└── deployment.md
The folder name doesn't matter. What matters is the separation between durable project knowledge and instructions for the agent.
AGENTS.md says when a document is relevant. The document explains how the system works. The agent retrieves detail only when the task needs it.
One warning: outdated documentation is worse than missing documentation, because the agent will trust it. I keep a small number of accurate documents rather than a large collection nobody maintains.
9. Skills: Reusable Workflows
Some instructions describe repeatable procedures rather than permanent rules:
- Reviewing a pull request
- Investigating a regression
- Performing an accessibility review
- Validating a database migration
- Checking an implementation against acceptance criteria
These are good candidates for skills. Unlike instruction files, skills load only when invoked or when the agent decides they're relevant, so they don't consume context on every task.
For Claude Code:
.claude/
└── skills/
├── code-review/
│ └── SKILL.md
├── regression-analysis/
│ └── SKILL.md
└── frontend-review/
└── SKILL.md
A code-review skill:
---
name: code-review
description: Review a diff for bugs, regressions, and
violations of project patterns. Use when asked to
review changes or a pull request.
---
# Code Review
When reviewing a change:
1. Understand the requested behavior.
2. Inspect the relevant diff.
3. Trace affected execution paths.
4. Identify potential regressions.
5. Check existing project conventions.
6. Review relevant tests.
7. Report actionable findings.
Do not modify code unless explicitly requested.
Keep the description short and specific about when the skill applies. Agents use it to decide whether to load the skill, and overly broad descriptions cause it to load for unrelated tasks.
Skill discovery paths vary across tools. A skill in .claude/skills/ shouldn't be assumed to work in Codex or Cursor. Share skills deliberately and verify that each tool can discover them.
10. MCP: Capabilities and External Context
MCP solves a different problem: giving the agent access to information or capabilities outside the repository.
- GitHub repositories and pull requests
- Issue trackers
- External documentation
- Browser automation
- Design tools
- Internal services
MCP isn't a replacement for instructions, documentation, or skills:
| Layer | Primary purpose |
|---|---|
| Instructions | Define expected agent behavior |
| Documentation | Explain the existing system |
| Intent | Define the requested change |
| Skills | Provide repeatable workflows |
| MCP | Connect external tools and resources |
For example, a code-review skill defines the review process. During that process, an MCP integration retrieves the linked ticket from the issue tracker. They're complementary.
Security matters here. Each integration should serve a clear purpose and have the minimum permissions it needs. The same applies to committed instruction files and skills: in a shared repository, they're text an agent will act on, so review changes to them like you review code. Claude Code, for example, asks for approval before loading @ imports that point outside the project.
11. My Repository Structure
An example multi-agent project:
my-project/
│
├── AGENTS.md
├── CLAUDE.md
│
├── .cursor/
│ └── rules/
│ ├── frontend.mdc
│ └── backend.mdc
│
├── .claude/
│ ├── rules/
│ │ └── api.md
│ └── skills/
│ ├── code-review/
│ │ └── SKILL.md
│ └── regression-analysis/
│ └── SKILL.md
│
├── intent/
│ ├── order-status-filter.md
│ └── vehicle-edit-action.md
│
├── docs/
│ ├── architecture.md
│ ├── authentication.md
│ ├── permissions.md
│ └── api.md
│
└── src/
MCP configuration is managed separately, according to each tool's supported configuration and scope.
This structure is illustrative. I only create files when the project needs them. For a small application, AGENTS.md and a few focused documents are often enough.
12. A Practical Example: Implementing a Production Feature
Suppose I receive this requirement:
Add an explicit Edit Vehicle action to trip cards.
The application already has vehicle editing and an established permission system. I don't want a second editing flow.
First, intent/vehicle-edit-action.md:
# Intent: Edit Vehicle Action
## Objective
Allow authorized users to edit a vehicle
directly from the trip card.
## Requirements
- Reuse the existing vehicle editing flow.
- Respect existing vehicle-edit permissions.
- Preserve the current trip-card layout.
- Avoid introducing unnecessary components.
## Acceptance Criteria
- Authorized users can access the action.
- Unauthorized users cannot access it.
- The existing editing flow is reused.
- Existing trip actions continue working.
Then a focused prompt:
Review intent/vehicle-edit-action.md.
Investigate the existing trip card, vehicle
editing flow, and permission implementation.
Identify which existing components and
patterns should be reused.
For any significant architectural change,
explain the proposed approach before coding.
Implement the smallest change that satisfies
the acceptance criteria.
Run the relevant tests and report any
verification that could not be completed.
I don't repeat the folder structure, TypeScript conventions, or test commands. Those already live in the repository. The prompt focuses only on the specific change.
13. Verify Your Instructions Actually Load
Everything above depends on one assumption: that each tool actually reads the files you think it reads. Don't assume. Check.
| Tool | How to verify |
|---|---|
| Claude Code | Run /memory or /context and confirm CLAUDE.md (and AGENTS.md, if loaded directly) appears under memory files. |
| Codex | Run codex --ask-for-approval never "List the instruction sources you loaded." from the directory you normally work in. |
| Cursor | Open Customize → Rules to see which rules exist and their status. |
I do this whenever I:
- Add or rename an instruction file
- Add a
CLAUDE.local.mdorAGENTS.override.md - Upgrade a tool to a new major version
- Onboard a teammate who uses a different agent
It takes a minute and catches the silent failures described in section 5.
14. Context Engineering vs Prompt Engineering
Early on, I spent a lot of time writing better prompts. But a perfectly written prompt can't compensate for missing architectural context, and a massive prompt containing the entire repository isn't the answer either.
The question I ask now is:
What information does the agent need to complete this particular task correctly?
The giant-prompt approach:
Here is the entire project architecture.
Here are all the coding conventions.
Here are the API rules.
Here are the testing instructions.
Here are the feature requirements.
Now implement the requested change.
It works once, but it's repetitive, expensive in context, and impossible to keep consistent across tasks.
With structured context, the prompt only needs to state the objective and point to the intent document. Conventions, architecture, and workflows are already where the agent can find them.
Context engineering doesn't mean creating as many context files as possible. It means organizing useful information, removing unnecessary instructions, and making the right context available when needed. The goal is relevance, not volume.
15. What I Stopped Doing
- Maintaining duplicate instructions. One shared source of truth, with tool-specific extensions only where needed.
- Putting temporary requirements into permanent instructions. Feature requirements belong in intent documents, tickets, or prompts.
- Creating documentation nobody maintains. Documentation must reflect the actual codebase.
- Forcing every agent to read everything. I point to relevant documents instead of requiring an exhaustive review.
- Accepting new abstractions without investigation. Agents inspect existing patterns first.
- Assuming instruction files load. I verify them (section 13).
- Treating generated code as delivered code. An implementation isn't done because the agent says it is.
16. The Verification Step Still Matters
A good context structure improves an agent's understanding. It doesn't guarantee correctness.
My workflow:
- Understand the requested behavior.
- Investigate the existing implementation.
- Plan significant changes when necessary.
- Implement the requested behavior.
- Run relevant automated checks.
- Review the resulting diff.
- Verify the acceptance criteria.
For example, an agent might add a permission check in the frontend while missing the corresponding backend authorization. Or it might reuse the right component but introduce a regression elsewhere.
Context engineering reduces avoidable misunderstandings. It doesn't replace engineering judgment.
17. One Repository, Multiple Agents
The biggest benefit is that the repository's core knowledge isn't tied to a single tool:
AGENTS.md
|
Shared repository rules
|
+-----------+-----------+
| | |
Codex Claude Cursor
| | |
| CLAUDE.md |
| imports |
| AGENTS.md |
| | |
| .claude/rules/ .cursor/rules/
| | |
+-----------+-----------+
|
Project knowledge
|
+-----------+-----------+
| | |
Intent Docs Skills
This is a conceptual diagram, not a literal description of each tool's loading behavior. The actual configuration still matters, which is why section 13 exists.
Portability requires a little discipline. But it's far easier than maintaining several independent copies of the same instructions.
18. My Rule of Thumb
Before adding any AI-related configuration, I ask:
What kind of information is this, and who actually needs it?
| Question | Where it belongs |
|---|---|
| Is it a shared repository convention? | AGENTS.md |
| Is it specific to Claude? | CLAUDE.md |
| Does it apply only to certain files? |
.claude/rules/ or .cursor/rules/
|
| Does it describe a particular change? | An intent document |
| Does it explain the existing architecture? | docs/ |
| Is it a reusable procedure? | A skill |
| Does it require external capabilities? | An integration, such as MCP |
I also ask whether the information needs to exist at all.
Sometimes the best instruction is no instruction. A capable agent can discover straightforward details directly from the codebase. Configuration should provide useful constraints, not restrict every decision.
19. Final Thoughts
AI coding agents are becoming increasingly capable. But generating code is only part of software engineering. The hard part is understanding how a change fits into an existing system.
That's why I care about context engineering. Not because every project needs an elaborate collection of Markdown files, but because separating different kinds of information makes the workflow easier to maintain.
My approach:
Keep shared instructions concise, make architecture discoverable, separate feature intent, use specialized workflows only when they add value, and verify that every tool actually loads what you wrote.
Then verify the result.
The goal isn't to make a repository work for one AI agent. It's to give every agent the same reliable project knowledge.
Further Reading
- Claude Code: How Claude Remembers Your Project
- Cursor: Rules and AGENTS.md
- Codex: Custom Instructions with AGENTS.md
- AGENTS.md: The Open Format
- OpenAI: Rethinking Skills and Prompts for GPT-6 Astra
- Model Context Protocol
My previous article:
What Is intent.md in Claude Code? A Practical Guide with an Example
What's Your Setup?
If you're using multiple coding agents, I'd like to know how you organize your repository.
Do you maintain one shared AGENTS.md? Do you use separate CLAUDE.md instructions and Cursor Rules? Have you introduced reusable skills, or do you keep your setup minimal?
And have you ever been caught by an instruction file that silently wasn't loading?
Share your approach in the comments.
My next article will cover a practical AGENTS.md setup for a production Next.js and TypeScript project: what I keep, what I deliberately leave out, and how I use it across multiple coding agents.
Top comments (1)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.