WINDSURF RULES FORMAT

Windsurf's agent reads always-on AGENTS.md files plus rule files with trigger frontmatter. Its documentation is now published under the Devin name, and the newer rule folder is .devin/rules, with the older Windsurf locations still imported.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

What Are Windsurf Rules?

Rules are the persistent instructions Windsurf's agent (Cascade) follows in a workspace. Last verified 2026-11-13 against the vendor documentation. Windsurf's documentation now lives on the Devin documentation site, and it describes two layers: AGENTS.md files, which are always on, and individual rule files, which declare when they apply.

See which other agents read these files on the compatibility page.

Where Do Windsurf Rule Files Live?

  • AGENTS.md, AGENTS.local.md (personal, kept out of version control) and AGENT.md: always-on rules, read at the workspace root and in each directory between the root and the directory being worked on.
  • .devin/rules/*.md: one rule per file, with trigger frontmatter.
  • .devin/global_rules.md: a single always-on file; the same files in your home directory apply to every project.
  • Legacy .windsurf/rules/*.md, .windsurf/global_rules.md and .windsurfrules are still imported by default.

Rule files in both .devin/rules and .windsurf/rules load. When both global_rules.md files exist, only the .devin one loads.

What Trigger Values Can a Rule Use?

Each rule file can declare when it applies with a trigger field:

  • always_on: applied to every task.
  • model_decision: the agent decides whether it is relevant.
  • glob: applied when the agent works with files matching globs.
  • manual: applied only when you invoke it.
---
trigger: glob
globs: "**/*.test.ts"
---

- Tests use Vitest. Import from vitest, not jest.
- One behavior per test; name tests after the behavior, not the function.

How Should You Use AGENTS.md With Windsurf?

Because Windsurf treats AGENTS.md as always-on and scopes nested AGENTS.md files to their directory, it fits the AGENTS.md-first pattern without any wrapper file. 2prompt does not generate a separate Windsurf file for this reason.

  1. Put shared rules in the root AGENTS.md.
  2. Add nested AGENTS.md files for directories with different rules.
  3. Use .devin/rules only for rules that need a trigger, such as glob-scoped test conventions.
  4. Delete .windsurfrules once its content has moved.

How Long Can Windsurf Rules Be?

Windsurf has published per-file character limits for rules, but we did not verify the current numbers on 2026-11-13, so check the vendor documentation before relying on a specific figure. Independent of any limit, always-on rules are sent with every task, so keep them short and push detail into triggered rules.

How Do AGENTS.md Files Stack Across Directories?

Windsurf reads AGENTS.md at the workspace root and in each directory between the root and the directory the agent is working in. In a repository with a web app and an API, a root file can hold the shared commit and review rules, while apps/web/AGENTS.md and services/api/AGENTS.md hold the commands and conventions for each part.

  • Write the shared rules once, at the root.
  • In nested files, write only what differs for that directory.
  • Keep the nested file next to the code it governs so it moves with the code.

Codex and Cursor treat nested AGENTS.md files in a similar way, so this layout also works for teammates using those agents.

If you also keep legacy .windsurf/rules files, read them alongside the AGENTS.md files during a migration. Both are loaded, so any rule left in the old folder still applies until you delete it.

What Are the Common Mistakes?

  • Keeping a long .windsurfrules file alongside AGENTS.md with different content.
  • Marking every rule always_on, which defeats the point of triggers.
  • A glob trigger with no globs value, so the rule never matches.
  • Committing AGENTS.local.md, which is meant for personal rules.

Generate an AGENTS.md with the generator and check legacy files with the linter. Moving from Cursor? See .cursorrules to AGENTS.md.

Frequently Asked Questions

Does Windsurf read AGENTS.md?

Yes. Windsurf reads AGENTS.md, AGENTS.local.md and AGENT.md as always-on rules, at the workspace root and in each directory between the root and the directory the agent is working in.

Is .windsurfrules still read?

Yes, as a legacy file. The current documentation says the legacy .windsurfrules, .windsurf/rules and .windsurf/global_rules.md files are imported by default. New rules belong in AGENTS.md or .devin/rules.

Why do the Windsurf docs say Devin?

Windsurf's documentation is now published on the Devin documentation site, and the newer rule folder is named .devin/rules. The older .windsurf folder still works, so existing projects keep their rules.

Does 2prompt generate a Windsurf rules file?

No separate one. Windsurf reads AGENTS.md as an always-on rule, so the AGENTS.md the generator produces already covers it. Add a .devin/rules file only for rules that need a trigger.

Was this helpful?