NEWn1n v2.0.1 is live! Enterprise Unified LLM API Gateway with 500+ AI Models, up to 90% off, Try now

One AGENTS.md to Rule Claude Code, Cursor and Codex

Authors
  • avatar
    Name
    Nino
    Occupation
    Senior Tech Editor

If you use more than one AI coding agent, you have probably ended up with three instruction files: a CLAUDE.md for Claude Code, a pile of .cursor/rules for Cursor, and an AGENTS.md for Codex. They start out identical. A month later one still says npm, another says pnpm, and the third forgot that tests live next to the code.

That is how instruction files drift apart. The fix is simple: make AGENTS.md the single source of truth and keep every tool-specific file thin. This post shows the layout, how each tool actually picks up AGENTS.md, and a template you can copy.

your-repo/
├── AGENTS.md            # canonical: commands, layout, conventions, definition of done
├── CLAUDE.md            # "@AGENTS.md" + Claude-only notes
├── .claude/
│   ├── settings.json    # permissions + hooks
│   ├── agents/          # subagents
│   └── skills/          # procedures that load on demand
├── .cursor/
│   ├── rules/           # .mdc rules, with the core rule pointing at AGENTS.md
│   └── cli.json         # permissions for the `agent` CLI
├── .cursorignore
└── .codex/
    ├── config.toml      # sandbox + approval defaults
    └── agents/          # custom agents

AGENTS.md holds everything every agent needs. The other files hold only what is specific to one tool: its behaviour, permissions, and features. When working with high-performance APIs or scaling your development workflows via robust infrastructure like n1n.ai, maintaining clean, unified documentation files becomes critical for automated agents to fetch accurate context.

How Each Tool Loads Instructions Differently

This is the part people get wrong, because the three tools load it differently.

  • Codex builds an instruction chain once per run. It starts with the global file (~/.codex/AGENTS.override.md or AGENTS.md), then walks every directory from the project root down to your working directory. In each one it checks AGENTS.override.md, then AGENTS.md, then any project_doc_fallback_filenames, and takes at most one file per directory. Files closer to your working directory come later, so they win when instructions conflict. The combined chain has a default size cap of 32 KiB, and Codex stops adding files once it reaches it.

  • Cursor supports AGENTS.md in the root and in subdirectories. Nested files combine with their parents, and the more specific instructions take precedence.

  • Claude Code has the catch. It reads AGENTS.md directly only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above. Once you add a CLAUDE.md, put an import at the top so both load:

# CLAUDE.md
@AGENTS.md

A personal, uncommitted CLAUDE.local.md also counts as "a CLAUDE.md exists". So even if you never create a project CLAUDE.md, adding a local one silently stops Claude reading AGENTS.md. Keep the explicit @AGENTS.md import and that cannot happen.

The Universal AGENTS.md Template

Here is a trimmed version of the template I use. Replace the placeholders with your own stack.

# AGENTS.md

## Project snapshot
- What it is: <one sentence>
- Main language / runtime: <TypeScript 5, Node 22>
- Package manager: <pnpm>. Do not use any other package manager.
- Layout:
  - `apps/web/`: frontend
  - `apps/api/`: HTTP API (handlers in `apps/api/src/handlers/`)
  - `packages/db/`: schema + migrations

## Commands
- Install: `<pnpm install>`
- Unit tests (fast, run often): `<pnpm test>`
- Single test file: `<pnpm test -- path/to/file.test.ts>`
- Lint + types: `<pnpm lint && pnpm typecheck>`
- Build: `<pnpm build>`

## Conventions
- Named exports, no default exports.
- Errors: return `{ code, message }` objects from services; never throw raw strings.
- New code needs tests next to it (`*.test.ts`).

## Working agreement
1. Restate the task in one or two lines and list the files you expect to touch before editing.
2. Make the smallest change that solves the task. No drive-by refactors.
3. If requirements are ambiguous, stop and ask. Do not guess on behaviour.
4. Never commit secrets, tokens, or `.env*` files.
5. Do not run `git push`, `git reset --hard`, `git clean -fd`, force-pushes,
   or destructive DB commands unless explicitly asked.

## Definition of done
- [ ] Lint + types pass
- [ ] Tests pass (and a new test covers the change)
- [ ] Diff is limited to files related to the task
- [ ] Short summary: what changed, why, how it was verified, open risks

## Code Review Rules
- Flag any handler that reads request input without validation.
- Flag SQL built with string concatenation.

Commands come first because wrong commands cause most wasted agent turns: npm instead of pnpm, or the wrong test runner. The single-file test command also saves tokens, since the agent stops running the whole suite on every iteration.

The working agreement turns common failure modes, like silent scope creep and guessing, into explicit rules. The definition of done gives every agent the same exit criteria. Without it you get "Done!" while the tests still fail.

## Code Review Rules is a heading Codex's GitHub code review looks for, so the review guidance comes along for free. When integrating enterprise LLM workflows or deploying multi-agent systems via n1n.ai, keeping instructions standardized ensures every model instance respects safety boundaries.

Keep it short. Leave formatting checks to CI, not the rule file. And write instructions the agent can verify: "Run pnpm test before finishing" works better than "test your changes".

Tool-Specific Configurations

CLAUDE.md: Project Instructions for Claude Code

<!-- Keep this file under ~200 lines. HTML comments are stripped before Claude sees them. -->

@AGENTS.md

## Claude Code specifics
- Use plan mode before touching more than 3 files.
- For searches that would flood the context, delegate to a subagent
  and ask for a summary with file paths.
- Before calling a task done, run the checks in "Definition of done"
  and paste the command output summary.

## Things that went wrong before
- Do not "fix" failing tests by loosening assertions or adding `.skip`.

Two details: imports are relative to CLAUDE.md and can nest up to four hops. Block-level HTML comments are stripped before injection, so notes for humans cost no context. Run /context to confirm which memory files actually loaded.

Cursor Project Rules

Cursor project rules must be .mdc files in .cursor/rules/. A plain .md file there is ignored. The always-on core rule just points to AGENTS.md and adds a few hard limits:

---
description: "Core working agreement for every Agent chat in this repo"
alwaysApply: true
---

- Follow `AGENTS.md` at the repo root for commands, layout and definition of done.
- Before editing, list the files you plan to change. Keep the diff limited to the task.
- Never read, print, or edit `.env*`, `*.pem`, `*.key` or credential files.
- Finish every task with: what changed, how you verified it (exact commands), open risks.

Stack-specific rules go in separate .mdc files that attach by globs, so they only cost tokens when a matching file is in context.

Codex Configuration

Codex instructions come from AGENTS.md. Behaviour (sandbox, approvals, subagents) lives in config.toml:

approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[agents]
max_concurrent_threads_per_session = 4

Codex loads a project's .codex/ layers only when you trust the project.

Troubleshooting and Optimization

If an agent ignores your conventions, the cause is almost always that the rule file is too long, vague or contradictory, or was not loaded at all. Check before rewriting anything:

  • Claude Code: /context and /memory
  • Codex: /status
  • Cursor: Customize → Rules

Then shorten the file, make the instructions verifiable, and remove conflicts. One canonical file makes that much easier, because there is only one place to fix.

Summary Checklist

  1. AGENTS.md is canonical. CLAUDE.md and .cursor/rules stay thin and point to it.
  2. In CLAUDE.md, always add an explicit @AGENTS.md import.
  3. Put commands first, use verifiable instructions, and give every agent the same definition of done.
  4. Keep tool behaviour (permissions, sandbox, hooks) in each tool's own config, not in the instructions.

Whether you are orchestrating local IDE extensions or routing complex reasoning tasks through n1n.ai, unifying your core instruction files prevents expensive token waste and behavioral regressions.

Get a free API key at n1n.ai

Source: https://dev.to/mars_peakul/one-agentsmd-to-rule-claude-code-cursor-and-codex-3jmi