Windsurf Rules vs Cursor Rules vs AGENTS.md: Which Config File Does What (2026)

Every AI coding tool now ships some form of rule file. Windsurf has global_rules.md and workspace rules. Cursor has .cursorrules and the newer MDC format. AGENTS.md is the cross-tool open standard that many tools — including both Windsurf and Cursor — now read alongside their native format.

If you have ever wondered which file actually does what, or how they compare when you need to migrate between tools, this guide cuts through the noise. We cover file locations, activation behavior, character limits, versioning, and practical migration paths.

The Problem All Three Are Solving

AI coding assistants are stateless by default. Every chat session starts from scratch, with no memory of your project conventions, your testing approach, your preferred error handling patterns, or your team’s naming rules.

Rule files solve this by injecting persistent instructions into the AI’s context on every session. They are your codebase’s constitution — a document the AI reads before it touches anything.

The three formats in this guide all solve the same problem. They differ in scope, portability, and the sophistication of their activation controls.

Quick Overview

Windsurf Rules: global_rules.md and Workspace Rules

File Locations

Windsurf has three distinct rule scopes:

Global rules live at ~/.codeium/windsurf/memories/global_rules.md. These apply to every project you open in Windsurf. Use this for personal preferences — your preferred comment style, language habits, or defaults you want across all your work. The file has a 6,000 character limit.

Workspace rules live in .windsurf/rules/*.md inside your project. These are markdown files with YAML frontmatter that you commit to version control and share with your team. Each file has a 6,000 character limit, and the combined total across all rules cannot exceed 12,000 characters.

Enterprise/system rules are deployed to OS-level directories (/Library/Application Support/Windsurf/rules/ on macOS) for organization-wide enforcement.

The Four Activation Modes

This is where Windsurf’s rules system gets interesting. Each workspace rule file declares how it should be applied:

---
trigger: always_on
description: "Core coding standards for this project"
---

- Use TypeScript strict mode
- Functional components with named exports
- Colocate tests next to source files

The four trigger values:

• always_on — Full rule content is injected into the system prompt on every message. Use this for your most critical, universal standards.
• model_decision — Only the description appears in context initially. Cascade reads the description and decides whether to load the full rule based on relevance. Good for specialized rules (e.g., database migration guidelines) that only apply sometimes.
• glob — Rule activates when files matching a specified path pattern are being edited. The file-type-specific equivalent of Cursor’s globs.
• manual — Rule only loads when you explicitly @mention it in Cascade’s input. Useful for reference material you want available on demand.

The Legacy .windsurfrules Format

Before Wave 8, Windsurf used a single .windsurfrules file at the project root. It still works, but it has no activation modes — all rules are always active. If you are starting fresh, use the .windsurf/rules/ directory approach. If you have an existing .windsurfrules, migration is straightforward: split the content into separate files with appropriate trigger modes.

What Windsurf Rules Cannot Do

Windsurf rules have no equivalent to CLAUDE.md’s @import system — you cannot reference external files. The 12,000 character total cap is also relatively tight; large projects with complex conventions will need to prioritize carefully and use model_decision mode to avoid hitting the ceiling.

Cursor Rules: From .cursorrules to MDC

The Legacy .cursorrules Format

The original Cursor rules format was a single .cursorrules file in your project root. Plain markdown, no frontmatter, always active. If you still have this file, it mostly works — but Cursor officially considers it deprecated. More importantly, .cursorrules is ignored by Agent mode, which is increasingly where serious work happens in Cursor.

The MDC Format (.cursor/rules/)

The current standard is MDC (Markdown Components) files in .cursor/rules/. Each rule is a .mdc file with YAML frontmatter controlling activation:

---
description: API route conventions
globs: ["src/api/**/*.ts", "src/handlers/**/*.ts"]
alwaysApply: false
---

All API handlers must:
- Validate input with Zod schemas
- Return standardized error responses via ApiError class
- Log 5xx errors with full request context

The four activation types:

• Always Apply (alwaysApply: true) — Injects the rule into every chat session. The equivalent of always_on in Windsurf.
• Apply Intelligently — Cursor’s agent evaluates relevance based on the description field. Similar to Windsurf’s model_decision.
• Apply to Specific Files (globs patterns) — Activates when files matching the patterns are in context. Matches Windsurf’s glob mode.
• Apply Manually — Only loads when you @mention the rule file by name.

Cursor recommends keeping rules under 500 lines and splitting complex guidance into multiple composable files. There is no hard character limit documented, but overly long rules degrade agent performance.

User-Level Rules

Cursor also supports user-level rules in ~/.cursor/rules/ — personal rules that apply across all your projects, analogous to Windsurf’s global_rules.md. This is where you put personal style preferences that your teammates do not need to share.

AGENTS.md in Cursor

Cursor has added AGENTS.md as a supported format alongside its native rules. From Cursor’s documentation, AGENTS.md is described as “a simple alternative” to the structured rules system — useful when you want one file that also works in other tools. When Cursor finds both an AGENTS.md and .cursor/rules/ files, it reads both.

AGENTS.md: The Cross-Tool Standard

AGENTS.md is different from the other two in a fundamental way: it has no native owner. It is an open standard stewarded by the Agentic AI Foundation under the Linux Foundation, designed to work across any AI coding tool.

How It Is Discovered

The discovery algorithm is consistent across tools that support it:

1. Starting at the project root (or Git root), walk down toward the file being edited.
2. At each directory level, check for AGENTS.override.md first, then AGENTS.md.
3. Concatenate all found files from root down, with deeper files appearing later (and thus taking precedence for overlapping instructions).

In Codex specifically, there is also a global scope at ~/.codex/AGENTS.md for personal preferences.

Directory Scoping

AGENTS.md’s killer feature compared to a single global config is directory-level scoping. In a monorepo:

my-repo/
  AGENTS.md              # Global project rules
  services/
    payments/
      AGENTS.md          # Payment service rules (appended to global)
    auth/
      AGENTS.override.md # Auth service rules (replaces global for files in this scope)

An agent editing files in services/payments/ reads both the root AGENTS.md and the payments-specific one. An agent editing files in services/auth/ reads only the auth override. This is coarser than CLAUDE.md’s path-scoped rules but more portable.

Size Limits

Codex enforces a 32 KiB combined limit across all loaded AGENTS.md files. This is configurable in ~/.codex/config.toml:

project_doc_max_bytes = 65536

Other tools that support AGENTS.md (Windsurf, Cursor, GitHub Copilot, Gemini CLI) may have different internal limits — they do not necessarily use Codex’s config.

No Activation Modes

AGENTS.md has no frontmatter, no activation controls, no glob patterns. All instructions in a file are always applied when that file is in scope. This is a deliberate design choice for portability — a lowest-common-denominator format that any tool can parse without understanding custom metadata.

If you need fine-grained activation control, AGENTS.md is not the right tool. Use it for universal project rules and let your native tool config handle the nuance.

Feature Comparison Matrix

Migration Guide

From .cursorrules to Cursor MDC

This is the most common migration path right now. The .cursorrules format is deprecated and ignored by Agent mode.

1. Create the .cursor/rules/ directory in your project root.
2. Split your .cursorrules content into logical files — one per concern (code style, testing, architecture, etc.).
3. Add YAML frontmatter to each file. Start with alwaysApply: true for core rules, then tune from there.
4. Delete .cursorrules or leave it for tools that still read it — it will be ignored by Cursor’s Agent mode either way.
5. Test each rule by opening a new chat session and checking whether the context is injected correctly.

# Before (.cursorrules — one big file)
You are an expert TypeScript developer.
Use strict mode. Write functional components.
Test everything with Vitest. No any types.
Organize imports: React first, then external, then local.
...

# After (.cursor/rules/typescript.mdc)
---
description: TypeScript and React conventions
alwaysApply: true
---
- Strict mode, no `any` types
- Functional components with named exports
- Organize imports: React, external packages, local files

# After (.cursor/rules/testing.mdc)
---
description: Testing conventions with Vitest
globs: ["**/*.test.ts", "**/*.spec.ts"]
alwaysApply: false
---
- Use Vitest for all tests
- Colocate tests next to source files
- Table-driven tests for logic with multiple cases

From .windsurfrules to Windsurf Rules Directory

Windsurf’s old .windsurfrules format works, but gives you no activation control.

1. Create .windsurf/rules/ in your project root.
2. Split .windsurfrules content by concern.
3. Add frontmatter with appropriate trigger modes. Anything you always want active: trigger: always_on. Context-specific rules: consider trigger: model_decision or trigger: glob.
4. Keep your .windsurfrules for backward compatibility if teammates haven’t updated Windsurf.

From Windsurf Rules to Cursor MDC

The format is nearly identical — both use YAML frontmatter with similar activation concepts. The main translation:

Copy your .md files, rename to .mdc, translate the frontmatter, done. The rule content itself (the instructions) does not need changes.

Adding AGENTS.md Without Breaking Existing Rules

If you already have Windsurf or Cursor rules and want to add AGENTS.md for cross-tool portability:

1. Extract the universal rules from your existing config — code style, architecture patterns, testing requirements, project structure. These are the rules that would make sense to any AI tool.
2. Put those in AGENTS.md at the project root.
3. In your Windsurf/Cursor config, reference the universal rules minimally or leave them. There is no @import AGENTS.md syntax in these tools — you may end up with some duplication, which is acceptable.
4. Keep tool-specific rules (glob activation, personal preferences, Windsurf/Cursor-specific formatting) in the native format.

The result: contributors using Copilot or Gemini CLI get the AGENTS.md baseline; your Windsurf and Cursor users get that plus fine-grained activation control.

Which One Should You Choose?

Use Windsurf Rules if Windsurf is your primary tool and you want the richest native experience. The four activation modes — especially model_decision and glob — give you precise control over context loading. The global/workspace separation is clean. The 12,000 character cap is tight for complex projects but manageable with good rule organization.

Use Cursor MDC if Cursor is your primary tool, especially if you use Agent mode regularly. The .cursor/rules/ system is similar to Windsurf’s but without the hard character limits. Migrate from .cursorrules immediately — it is deprecated and does not work in Agent mode.

Use AGENTS.md if you care about portability. It works across Windsurf, Cursor, GitHub Copilot, Gemini CLI, OpenAI Codex, Aider, Zed, Warp, and more. If your team uses different tools, or you maintain an open-source project, AGENTS.md gives everyone a baseline without requiring them to share your editor choice.

Use both when you need maximum reach and maximum control. The pragmatic pattern:

project/
  AGENTS.md              # Universal rules — works everywhere
  .windsurf/
    rules/
      core.md            # Windsurf-specific: activation tuning
      testing.md         # Glob-scoped to test files
  .cursor/
    rules/
      core.mdc           # Cursor-specific: same content, MDC format

This is more maintenance, but it is the right call for any project where contributors use different tools and you want each of them to have a good experience.

If you are just starting out: write an AGENTS.md first. Get the universal rules right. Then layer on tool-specific configs only where the native features buy you something meaningful — glob activation for complex monorepos, model_decision for large rule sets, personal global rules for individual preferences.

Further Reading

• AGENTS.md vs CLAUDE.md: What’s the Difference — how AGENTS.md compares to Claude Code’s native format
• Best AI Coding Rules 2026 — curated examples from real open-source projects
• AGENTS.md rules gallery — real AGENTS.md files you can learn from
• Cursor rules gallery — real .cursorrules and MDC files