AGENTS.md in Cursor: Complete Setup Guide (2026)

AGENTS.md works in Cursor — and when combined with .cursor/rules/ properly, the two systems complement each other instead of fighting for control. This is the complete setup guide for using both in the same project.

How Cursor Discovers and Reads AGENTS.md (2026)

Cursor does not require any configuration to start reading AGENTS.md. Drop the file in your project root and Cursor’s agent picks it up automatically.

Discovery order

Cursor walks the filesystem using a nearest-ancestor approach:

1. Project root AGENTS.md — loaded first, applies project-wide
2. Subdirectory AGENTS.md files — loaded when the agent is working within that subdirectory, takes precedence over root-level content for that scope
3. CLAUDE.md — Cursor also reads CLAUDE.md (in addition to its own .cursor/rules/ and the project-level AGENTS.md), treating it as equivalent context

This means a monorepo can have:

repo-root/
├── AGENTS.md          ← applies everywhere
├── packages/
│   ├── api/
│   │   └── AGENTS.md  ← applies only when working in packages/api/
│   └── web/
│       └── AGENTS.md  ← applies only when working in packages/web/

Cursor 0.48+ behavior (2026)

Starting with Cursor 0.48, AGENTS.md is read in all modes: Chat, Composer, and Agent mode. This is the key behavioral difference from .cursorrules, which is not read in Agent mode. If your team uses Cursor Agent mode for autonomous tasks — long-running refactors, test generation, multi-file edits — AGENTS.md is the only instruction file that covers all three modes.

Priority relative to .cursor/rules/

AGENTS.md and .cursor/rules/*.mdc files are not in competition — Cursor reads both and merges their context. When content overlaps, .mdc rules applied via alwaysApply: true or matching glob patterns tend to have higher contextual weight because they are scoped more precisely. The safe rule: do not duplicate content between the two systems.

AGENTS.md vs .cursor/rules/ .mdc Format — What Goes Where

The formats solve different parts of the same problem.

The allocation rule

• Cross-tool standards → AGENTS.md. If a rule should apply whether someone uses Cursor, Codex, or Claude Code, it belongs in AGENTS.md. Tech stack, commands, naming conventions, architecture boundaries.
• Cursor-specific behavior → .mdc files. If a rule references Cursor features, depends on glob activation, or only makes sense in Cursor’s context model, it belongs in .mdc. Component patterns scoped to *.tsx, database conventions scoped to src/db/**, etc.

A .mdc rule that says “always use TypeScript strict mode” is doing AGENTS.md’s job. A .mdc rule that says “for *.tsx files, prefer server components and use the use client directive only at leaf nodes” is doing something AGENTS.md cannot — applying a rule only when editing .tsx files.

Setting Up AGENTS.md for a Cursor Project (Step by Step)

Step 1: Create the file

touch AGENTS.md

Place it at your Git repository root, not inside src/ or any subdirectory. The root placement ensures Cursor reads it regardless of which file you have open.

Step 2: Fill in the sections Cursor pays most attention to

Cursor’s agent weights these sections most heavily:

• Commands — Build, test, lint, dev server commands. Cursor uses these to run verification after edits.
• Code Style — Language, formatter settings, naming conventions, things the linter does not catch.
• Architecture — Directory structure, where things live, what not to touch.

Less impactful but still useful: Background context, constraints, external service notes.

Step 3: Full template (TypeScript/React project)

# AGENTS.md

## Commands

\`\`\`bash
# Install
pnpm install

# Development
pnpm dev             # Next.js dev server on :3000
pnpm dev:api         # Express API server on :4000

# Testing
pnpm test            # Vitest unit tests
pnpm test:e2e        # Playwright E2E (requires dev servers running)
pnpm test:watch      # Vitest watch mode

# Quality
pnpm lint            # ESLint
pnpm typecheck       # tsc --noEmit
pnpm format          # Prettier

# Build
pnpm build           # Production build
\`\`\`

## Code Style

- TypeScript strict mode; `noUncheckedIndexedAccess: true` is enabled
- No `any` — use `unknown` and narrow with type guards
- Named exports only; no default exports except pages and layouts
- `const` over `let`; avoid mutation
- Error handling: always return `{ data, error }` tuples from service functions — never throw in service layer
- Imports: use `@/` path alias for `src/`; no relative paths that go up more than one level

## Architecture

- **App layer**: `src/app/` — Next.js App Router pages and layouts only
- **Components**: `src/components/` — shared UI; `src/features/` — feature-specific components
- **Services**: `src/services/` — all external API calls; no fetch() calls in components
- **Database**: `src/db/` — Drizzle ORM schema and queries only; no raw SQL elsewhere
- **Config**: environment variables in `src/config/env.ts` via `t3-env`; never access `process.env` directly

## Constraints

- Never modify files in `src/db/migrations/` manually — run `pnpm db:generate` instead
- Do not add dependencies without checking if there is already a utility in `src/lib/`
- Auth logic lives in `src/middleware/auth.ts` — do not inline auth checks in route handlers
- All server actions must use the `safeAction` wrapper from `src/lib/safe-action.ts`

Step 4: Verify Cursor is reading your AGENTS.md

Open Cursor and start a new Chat or Composer session. Ask:

“What commands does this project use for testing?”

If Cursor responds with the exact commands from your AGENTS.md (e.g., pnpm test, pnpm test:e2e), the file is being read. If it guesses generic commands like npm test, something is wrong.

Common causes of AGENTS.md not being picked up:

• File is not in the project root (it is inside src/ or another subdirectory)
• Cursor workspace is opened at a parent directory above the repo root
• AGENTS.md is listed in .gitignore (unlikely, but happens)
• Cursor version older than 0.43 (AGENTS.md support was added in 0.43)

Combining AGENTS.md + .mdc Rules Without Conflict

The most common mistake is duplicating content between AGENTS.md and .mdc files. When a rule exists in both places, you get two problems: Cursor receives redundant context that wastes tokens, and when you update one file, the other becomes stale and contradicts it.

Rule: if it is in AGENTS.md, do not repeat it in .mdc

If AGENTS.md says “use TypeScript strict mode,” your .mdc files do not need to say it again. They can add precision on top — for example, strict-mode-specific patterns for a particular file type — but repeating the base rule creates maintenance debt.

Use .mdc for file-type scoping

AGENTS.md applies uniformly. .mdc files let you apply different rules to different parts of the codebase.

.cursor/rules/
├── react-components.mdc     # glob: src/components/**/*.tsx
├── api-routes.mdc           # glob: src/app/api/**/*.ts
├── database.mdc             # glob: src/db/**/*.ts
└── tests.mdc                # glob: **/*.test.ts, **/*.spec.ts

Example: layered without duplication

AGENTS.md (project-wide):

## Code Style
- TypeScript strict mode
- Named exports only
- No `any` — use `unknown`

.cursor/rules/react-components.mdc (scoped to *.tsx):

---
description: React component patterns
globs: ["src/**/*.tsx", "src/**/*.jsx"]
alwaysApply: false
---

## React Patterns

Server components by default. Add `"use client"` only when you need:
- Browser APIs (window, document, localStorage)
- useState or useReducer
- useEffect or lifecycle methods
- Event handlers with client-side state

Component file structure:
1. Imports
2. Types/interfaces
3. Component function
4. Sub-components (if small and only used here)
5. Named export at the bottom

The .mdc file adds React-specific precision that is only relevant when editing .tsx files. The AGENTS.md handles everything that applies everywhere.

Monorepo Setup with Per-Package AGENTS.md in Cursor

Monorepos benefit most from AGENTS.md’s directory-based scoping. Each package can carry its own context without polluting the root.

Directory structure

repo-root/
├── AGENTS.md                    ← shared: workspace commands, global conventions
├── package.json                 ← workspace root
├── packages/
│   ├── api/
│   │   ├── AGENTS.md           ← API-specific: Fastify patterns, DB access rules
│   │   └── src/
│   ├── web/
│   │   ├── AGENTS.md           ← Web-specific: Next.js patterns, component rules
│   │   └── src/
│   └── shared/
│       ├── AGENTS.md           ← Shared lib: what's exported, what's internal
│       └── src/
└── .cursor/
    └── rules/
        ├── monorepo-root.mdc   # alwaysApply: true — workspace-level Cursor rules
        ├── api-package.mdc     # glob: packages/api/**
        └── web-package.mdc     # glob: packages/web/**

How Cursor’s nearest-ancestor rule works

When you open packages/api/src/routes/users.ts, Cursor loads:

1. repo-root/AGENTS.md (root, always)
2. repo-root/packages/api/AGENTS.md (nearest ancestor in scope)

It does not load packages/web/AGENTS.md or packages/shared/AGENTS.md — those are not ancestors of the current file.

Root AGENTS.md (shared workspace rules)

# AGENTS.md

## Workspace Commands

\`\`\`bash
# Install all packages
pnpm install

# Run all tests
pnpm test

# Build all packages
pnpm build

# Work on a specific package
pnpm --filter @repo/api dev
pnpm --filter @repo/web dev
\`\`\`

## Shared Conventions

- All packages use TypeScript strict mode
- Package names follow `@repo/<name>` convention
- Shared utilities live in `packages/shared/` — check there before adding new utilities
- Do not add cross-package dependencies without checking the dependency graph

## Repository Structure

- `packages/api/` — Fastify REST API
- `packages/web/` — Next.js frontend
- `packages/shared/` — Shared types, utilities, constants

Package-level AGENTS.md (API-specific)

# packages/api/AGENTS.md

## Commands

\`\`\`bash
pnpm dev        # Start API server on :4000
pnpm test       # Run API tests (Vitest)
pnpm db:push    # Push schema changes to dev database
pnpm db:studio  # Open Drizzle Studio
\`\`\`

## Architecture

- Routes: `src/routes/` — one file per resource
- Services: `src/services/` — business logic; no DB calls in routes
- Database: `src/db/` — Drizzle schema and queries only

## API Conventions

- All routes return `{ data, error, meta }` shape
- Validation with Zod; schemas in `src/schemas/`
- Authentication via JWT; middleware in `src/middleware/auth.ts`
- Error codes defined in `src/lib/errors.ts` — use these, do not invent new ones

Migration from .cursorrules to AGENTS.md

What to keep in AGENTS.md

Content that is not Cursor-specific transfers directly:

• Build and test commands
• Code style rules (naming conventions, formatting preferences, import structure)
• Architecture descriptions (what directories contain, what files not to touch)
• Tech stack (framework, language version, key libraries)
• Workflow notes (how PRs work, what needs review)

What to move to .mdc

Content that is Cursor-specific or benefits from scoping:

• Rules that should only apply to specific file types
• Instructions that reference Cursor features (“when suggesting completions…”)
• Context that is only relevant for certain areas of the codebase

Migration script

This script splits your existing .cursorrules into a starter AGENTS.md:

#!/bin/bash
# migrate-cursorrules.sh
# Copies .cursorrules to AGENTS.md with a header

if [ ! -f ".cursorrules" ]; then
  echo "No .cursorrules found in current directory"
  exit 1
fi

if [ -f "AGENTS.md" ]; then
  echo "AGENTS.md already exists. Aborting to prevent overwrite."
  echo "Merge manually: diff .cursorrules AGENTS.md"
  exit 1
fi

cat > AGENTS.md << 'HEADER'
# AGENTS.md

<!-- Migrated from .cursorrules. Review and reorganize as needed. -->
<!-- Remove Cursor-specific rules and move them to .cursor/rules/*.mdc -->

HEADER

cat .cursorrules >> AGENTS.md

echo "Created AGENTS.md from .cursorrules"
echo "Next steps:"
echo "  1. Review AGENTS.md and remove Cursor-specific content"
echo "  2. Move Cursor-specific rules to .cursor/rules/*.mdc"
echo "  3. Keep .cursorrules for backward compatibility or delete it"

Should you keep .cursorrules after migration?

When both .cursorrules and AGENTS.md exist in a project, Cursor reads AGENTS.md in all modes (Chat, Composer, Agent) and falls back to .cursorrules in Chat/Composer for older behavior. In practice: keep .cursorrules during a transition period if you have teammates who may be on older Cursor versions. Once everyone is on 0.43+, delete .cursorrules to avoid the maintenance burden of keeping two files in sync.

If you are starting a new project today, skip .cursorrules entirely and go straight to AGENTS.md + .cursor/rules/*.mdc.

FAQ

Does Cursor read AGENTS.md?

Yes. Cursor reads AGENTS.md in Chat, Composer, and Agent mode starting from version 0.43. It uses a nearest-ancestor discovery model: it reads AGENTS.md from the project root and from any subdirectory that is an ancestor of the files you are working on. No configuration is required.

What is the difference between AGENTS.md and .cursor/rules/ in Cursor?

AGENTS.md is a cross-tool standard — Codex, Copilot, Gemini CLI, and other tools also read it. It uses directory-based scoping: a file applies to everything in its directory and below. .cursor/rules/ files use YAML frontmatter with glob patterns for precise file-type scoping and conditional activation. AGENTS.md is always loaded when in scope; .mdc rules load only when their conditions are met.

Should I use AGENTS.md or .cursorrules in Cursor?

AGENTS.md, for new projects. .cursorrules is not read in Cursor’s Agent mode, which makes it incomplete for agentic workflows. AGENTS.md covers all three Cursor modes and is also read by other AI tools, making it the better investment. For existing projects, migrate gradually: copy cross-tool content into AGENTS.md and move Cursor-specific rules into .mdc files.

How do I verify Cursor is reading my AGENTS.md?

Open a new Chat or Composer session and ask a question that is answered by your AGENTS.md — for example, “What command runs the tests in this project?” If Cursor responds with the exact command from your file (not a guess), the file is being read. You can also check Cursor’s context panel if your version exposes it.

Can I have both AGENTS.md and .cursor/rules/ files?

Yes, and this is the recommended setup. AGENTS.md handles cross-tool, project-wide context. .cursor/rules/*.mdc files handle Cursor-specific behavior and file-type scoping. The only rule is: do not duplicate content between them. If a rule is in AGENTS.md, the .mdc file should add precision on top — not repeat the same instruction.

Does AGENTS.md work in Cursor Agent Mode?

Yes — and this is one of the primary reasons to use AGENTS.md over .cursorrules. Cursor’s Agent mode reads AGENTS.md but does not read .cursorrules. If you want your project instructions to be available when Cursor is running autonomously — multi-file refactors, test generation, automated changes — AGENTS.md is the only format that works across all modes.

Related Articles

• AGENTS.md vs Cursor Project Rules: Which to Use and How to Run Both
• Migrating from .cursorrules to AGENTS.md
• AGENTS.md Best Practices 2026

Keep API Keys Out of Your Cursor Workflows

When AGENTS.md references internal services or environment-specific endpoints, keep credentials out of the file itself. 1Password CLI’s op run injects secrets at runtime so your team can share AGENTS.md safely without exposing keys in plaintext.