Cursor Rules vs CLAUDE.md vs Codex Instructions: AI Dev Config

If you have used an AI coding agent for more than a week, you have noticed the pattern: the agent writes code that works but does not match your team's conventions. It picks the wrong state management library. It uses a CSS approach you abandoned six months ago. It writes tests in a framework you do not use. The code is functional but foreign, and the review cycle becomes a loop of "change this, not that" corrections.

Project-level configuration files solve this. Cursor has .cursorrules (and the newer .cursor/rules directory). Claude Code reads CLAUDE.md files from your repo root and home directory. OpenAI's Codex accepts system-level instructions and reads AGENTS.md files. Each mechanism lets you encode your conventions, architecture decisions, forbidden patterns, and style preferences into a file that the AI reads before writing a single line of code.

The impact is immediate. Teams that invest 30 minutes writing a good config file report 40-60% fewer review comments on agent-generated pull requests. But the three tools handle configuration differently, and the differences matter for team workflows, version control, and migration.

This guide covers each config system: file format, scope, what to include, how to version control it, and how to share it across a team. We will also cover migration strategies for teams that use multiple tools, because in 2026, most serious engineering teams are not locked into a single AI coding agent.

Cursor's configuration system has evolved since launch. The original approach was a single .cursorrules file in your project root. In 2025, Cursor introduced the .cursor/rules directory, which supports multiple rule files with metadata like file-glob patterns and descriptions. Both approaches still work, but the directory-based system is where Cursor is heading.

File Format and Structure

A .cursorrules file is plain text, typically Markdown-formatted, placed at the root of your repository. You write instructions in natural language, and Cursor injects them into the system prompt for every AI interaction. The newer .cursor/rules directory holds individual .mdc files (Markdown with front matter) that each target specific file patterns. You might have one rule file for React components, another for API routes, and a third for database migrations.

Here is what a practical .cursorrules file looks like for a Next.js project:

• Framework: Next.js 15 with App Router. Never use pages/ directory patterns.
• Styling: Tailwind CSS v4. No CSS modules, no styled-components.
• State: Zustand for client state. Server state via React Query with TanStack Query v5.
• Testing: Vitest for unit tests, Playwright for E2E. No Jest.
• Components: Use shadcn/ui primitives. Do not install new UI libraries without asking.
• Forbidden: No "use client" unless absolutely necessary. No default exports except for pages and layouts. No any type in TypeScript.

Scope: Project vs Global

Cursor supports both project-level and global rules. Project rules live in .cursorrules or .cursor/rules/ within your repo. Global rules are set in Cursor's settings UI (Settings > General > Rules for AI) and apply to every project you open. Global rules work for personal preferences: "Always explain your reasoning before writing code" or "Use American English in comments." Project rules override global rules when there is a conflict.

Version Control Strategy

Commit your .cursorrules file or .cursor/rules directory to the repository. This is not optional for teams. If your rules live only on one developer's machine, every other developer's Cursor instance is guessing differently. We commit the file alongside the code and review changes in pull requests just like any other configuration.

Anthropic's approach to AI coding configuration is both simpler and more flexible than Cursor's. Claude Code reads Markdown files named CLAUDE.md at multiple levels of your project, and the content becomes part of the agent's context for every interaction. There is no special syntax, no front matter, no metadata. It is a Markdown file with instructions, and Claude follows them.

File Locations and Hierarchy

Claude Code looks for CLAUDE.md in several places, and each serves a different purpose:

• ~/CLAUDE.md (home directory): Personal preferences that apply to all your projects. "Prefer concise commit messages." "Always run the linter before committing."
• ./CLAUDE.md (project root): Team-wide conventions for this specific repository. Architecture decisions, tech stack constraints, testing requirements.
• ./src/CLAUDE.md, ./packages/api/CLAUDE.md (subdirectory): Module-specific or package-specific rules for monorepos. The API package might have different conventions than the frontend package.

Claude merges all applicable CLAUDE.md files, with more specific (deeper) files taking precedence. This hierarchy is powerful for monorepos. A team working on a Python backend and TypeScript frontend in the same repo can maintain separate CLAUDE.md files for each, plus a shared root file for repo-wide standards like commit message format and branch naming.

What to Include

The most effective CLAUDE.md files share a common structure: a one-paragraph project description, a "Tech Stack" section with frameworks and versions, a "Conventions" section covering code style and testing expectations, and a "Forbidden Patterns" section listing things the agent should never do.

The "Forbidden Patterns" section is the highest-ROI part. Without it, Claude occasionally reaches for patterns that are technically valid but wrong for your project. Examples we include regularly: "Never use relative imports that go up more than one level." "Do not add new dependencies without explicit approval." "Never modify migration files that have already been applied to production."

CLAUDE.md vs .cursorrules

The key architectural difference is that CLAUDE.md is hierarchical and scoped, while .cursorrules is flat (unless you use the newer .cursor/rules directory). CLAUDE.md also works in Claude Code's terminal environment, meaning the agent reads and reasons about it as part of its extended thinking. It is not just injected as a system prompt; it is part of the codebase context. This matters for complex instructions that require reasoning, not just pattern matching.

OpenAI's Codex takes a two-layer approach to configuration. There is a system-level instructions field you set through the Codex interface or API, and there are AGENTS.md files that Codex reads from your repository. The system instructions are closer to Cursor's global rules. AGENTS.md files are analogous to CLAUDE.md but with important differences.

System Instructions

When you create a Codex task, you can provide system-level instructions that apply to all tasks in that workspace: which package manager to use, what test framework to run, how to format commit messages. These persist across tasks within the same workspace, so you set them once and they apply to every task you assign.

AGENTS.md Files

Codex reads AGENTS.md files from your repository similarly to CLAUDE.md. Place them at the repo root or in subdirectories, and Codex merges the applicable files. However, Codex's sandboxed execution environment means your AGENTS.md needs to account for constraints that do not apply to Claude Code or Cursor. Codex cannot access the internet, cannot call external APIs, and runs in an isolated container. Your instructions should reflect this: "Run tests with the local test database" rather than "Run tests against the staging API."

What Makes Codex Configuration Different

The sandbox constraint is the defining characteristic. Codex clones your repo into a clean environment, installs dependencies, and works entirely offline. Your AGENTS.md needs to specify setup steps that work in isolation: "Run npm install before any task." "Use sqlite for test database." "Mock all external API calls in tests." Front-load these environment setup instructions so every task starts from a known-good state.

The other key distinction is that Codex is task-oriented, not session-oriented. Each task gets a fresh environment. Codex cannot "remember" previous conversations unless it is written in the AGENTS.md or system instructions. For Codex, the config file is not just a preference file; it is the agent's entire understanding of your project's operational context.

Regardless of which tool you use, the content of your configuration file determines its effectiveness. The goal is a file comprehensive enough to prevent common mistakes but concise enough that the AI can process it without losing focus.

Architecture and Tech Stack

Be specific about versions. "React" is not enough. "React 19 with Server Components, Next.js 15 App Router, TypeScript 5.6 strict mode" gives the agent the precision it needs. List key dependencies: ORM (Drizzle, Prisma), auth (NextAuth, Clerk), payments (Stripe), email (Resend). Include file structure conventions: "API routes live in src/app/api/. Server actions live in src/actions/. Shared types live in src/types/."

Code Style and Naming Conventions

Your linter catches syntax issues, but it does not enforce architectural preferences. Specify naming conventions: "React components use PascalCase file names. Utility functions use camelCase. Database table names use snake_case." Specify imports: "Use path aliases (@/components, @/lib) instead of relative paths." Specify error handling: "Wrap all async route handlers in a tryCatch utility. Never use bare try/catch blocks in API routes."

Testing Requirements

This section prevents the agent from writing tests in the wrong framework or skipping them entirely. "Every new function must have at least one unit test. Use Vitest, not Jest. Place test files adjacent to source files with a .test.ts suffix. For React components, use Testing Library with user-event for interactions. Do not use enzyme. Do not use snapshot tests."

Forbidden Patterns

This is the most important section. Explicit prohibitions prevent the AI from falling back on common patterns that are wrong for your project. Examples from real production config files we maintain:

• Never use the any type in TypeScript. Use unknown if the type is genuinely uncertain.
• Never add new npm dependencies without explicit approval. Use existing utilities first.
• Never write SQL queries directly. Use the Drizzle ORM query builder.
• Never use useEffect for data fetching. Use server components or React Query.
• Never commit .env files, API keys, or secrets of any kind.
• Never modify database migration files after they have been applied.

What to Leave Out

Resist the urge to turn your config file into a 5,000-word document. Every unnecessary word is a word of code context the agent cannot process. Leave out what your linter already enforces (semicolons, indentation, bracket style). Leave out obvious language features ("use const instead of var"). Focus on decisions specific to your project that the agent cannot infer from reading your code.

A config file on one developer's machine is a personal hack. A config file committed to the repo and maintained by the team is an engineering standard.

Commit the File to Your Repository

All three config file types (.cursorrules, CLAUDE.md, AGENTS.md) should be committed to your repository. When a new developer clones the repo, they should immediately get the AI configuration that reflects current conventions. For teams using agentic coding workflows, the config file is as important as your linter config or your CI pipeline definition.

Review Config Changes in Pull Requests

When someone updates the config file, that change should go through code review. A config change that says "stop using Zustand, switch to Jotai" affects every future AI interaction in the project. We add a CODEOWNERS entry for config files so that changes require approval from a senior engineer or tech lead.

Maintaining Multiple Config Files for Multi-Tool Teams

Most teams we work with use more than one AI tool. Your repo might contain .cursorrules, CLAUDE.md, and AGENTS.md simultaneously, and the content will overlap significantly.

We handle this with a two-file approach. Maintain a single source of truth: a CONVENTIONS.md file that documents conventions in a tool-agnostic format. Then have each tool-specific config file reference the shared conventions and add only tool-specific instructions. CLAUDE.md might include "Read CONVENTIONS.md for project standards" plus "Use extended thinking for tasks that touch more than three files." The .cursorrules file references the same conventions plus "When using Composer, create a new branch before making changes."

Keeping Config Files Current

Stale config files are worse than no config file. If your config says "use React Query v4" but you upgraded to v5, the agent will write v4-style code that breaks. Schedule a quarterly review of your AI config files alongside dependency updates. When you make a significant architectural change, update the config file in the same PR.

Switching AI tools should not mean rewriting your configuration from scratch. The three config systems are different in format but nearly identical in content. A practical migration takes 15 minutes.

From .cursorrules to CLAUDE.md

This is the most common migration we see. The content transfers directly: copy your .cursorrules into a CLAUDE.md file. Then add Claude-specific instructions. Claude Code can run shell commands, so add "Run npm run lint after making changes" or "Run the test suite and fix failures before finishing." Claude Code's extended thinking also benefits from context about why conventions exist. Instead of "Use Zustand for state," write "Use Zustand for client state because the team chose it for minimal boilerplate and TypeScript inference."

From CLAUDE.md to AGENTS.md

Migrating to Codex requires accounting for the sandbox. Add an environment setup section: dependencies to install, environment variables (with placeholder values), and commands to run before starting. Remove instructions that assume internet access. Replace "Test against the staging API" with "Test against the mock server in tests/mocks/." The rest transfers without changes.

Maintaining a Universal Config

For teams using all three tools, the universal config approach saves maintenance overhead. Create a base Markdown file with your conventions. Then create thin wrapper files for each tool:

• .cursorrules: Project conventions (inline or referenced) plus Cursor-specific UI and workflow instructions.
• CLAUDE.md: Project conventions plus shell commands to run, extended thinking guidance, and Git workflow instructions.
• AGENTS.md: Project conventions plus sandbox setup steps, offline testing configuration, and environment isolation notes.

The shared content stays in sync because it lives in one place. The tool-specific additions are small and easy to maintain independently. Everyone gets consistent AI behavior regardless of which agent they are talking to.

We track code quality metrics across all client projects, and the data on config file adoption is clear. Here are the numbers from 18 projects we managed between January and June 2026.

Review Cycle Reduction

Pull requests generated by AI agents with a config file averaged 1.4 review cycles before merge. Without a config file, the average was 2.8 cycles. The primary reasons for extra cycles: wrong framework usage (Jest instead of Vitest), style mismatches (wrong import patterns, inconsistent naming), and forbidden pattern violations (bare try/catch, direct SQL, unnecessary dependencies).

First-Pass Approval Rate

With config files, 62% of agent-generated PRs were approved on the first review pass. Without them, 28%. The gap is almost entirely explained by convention adherence. The code logic was correct in both cases; config-equipped agents just wrote code that looked like it belonged in the project.

Time Savings

Each avoided review cycle saves 20-40 minutes. Across a team of five developers generating 30 agent-assisted PRs per week, the improvement from 2.8 to 1.4 cycles saves roughly 14-28 hours per week of combined team time. That is the equivalent of hiring an extra part-time developer, and it costs nothing beyond the initial 30-minute config file investment.

Consistent code from AI agents is also easier to maintain. When every agent-generated file follows the same patterns, future developers (human or AI) can read and modify it predictably. Inconsistent agent output creates a maintenance tax that compounds over time.

You do not need the perfect config file on day one. Start with the basics, ship it, and iterate based on review feedback. Here is a process that works regardless of which tool you use.

Step 1: Document Your Stack (2 Minutes)

List your framework, language, major dependencies, and their versions. This alone prevents the most common agent mistakes. "Next.js 15, TypeScript 5.6, Tailwind CSS v4, Drizzle ORM, PostgreSQL, Vitest, Playwright." One line, massive impact.

Step 2: List Your Top 5 Conventions (3 Minutes)

Think about the last five times you corrected AI-generated code during review. Those corrections are your first conventions. "Use path aliases, not relative imports." "Server components by default; only add use client when the component needs browser APIs." "All database queries go through the repository pattern in src/repositories/."

Step 3: Write Your Forbidden Patterns (3 Minutes)

List the things the agent should never do. Check your code review checklist for patterns that come up repeatedly. "No any types. No default exports. No new dependencies without approval. No inline styles except Tailwind classes."

Step 4: Commit and Iterate (2 Minutes)

Commit the file and start using it. After a week, review the pull request feedback. Every repeated correction is a missing convention in your config file. Add it. Over two to three weeks, your file will converge on the instructions that eliminate 90% of review friction.

If your team is working on a complex project with multiple AI tools, investing in proper configuration pays for itself within the first sprint. The agents become more predictable, reviews get faster, and code quality stays high as you scale.

We help engineering teams configure AI development workflows from tool selection through production deployment. If you want your AI coding tools producing review-ready code from day one, book a free strategy call and we will walk through your setup together.