Windsurf Rules and Prompt Templates (2026)

TL;DR: Windsurf's rule files as of September 2026: a global global_rules.md (6,000-character cap, always on), workspace rules in .devin/rules/*.md — the new preferred location — with .windsurf/rules/*.md and the single legacy .windsurfrules both still read as fallbacks (12,000 characters per file), and AGENTS.md fed into the same engine automatically. Four activation modes, six copy-paste templates below.

Search for "windsurf rules" today and you will land on a lot of content that is confidently wrong about one specific thing: which directory you should be writing to. That is not because the writers were careless. It is because Cognition, the company behind the AI agent Devin, acquired Windsurf, and the product's own documentation domain now forwards to Cognition's. docs.windsurf.com/windsurf/cascade/memories resolves, as of this writing, to docs.devin.ai/desktop/cascade/memories. The page still works. The rules still work. But the docs quietly introduced a new preferred folder, .devin/rules/, and downgraded the folder every existing tutorial tells you to use, .windsurf/rules/, to a fallback.

None of that is a reason to panic, and none of it breaks anything you have already written. Below: exactly which files Windsurf reads today and in what order, per its own documentation; the two character limits that actually apply; the four activation modes and what each one costs in context; and six complete rule files, plus an AGENTS.md example, to paste and edit.

Which rule files does Windsurf actually read today?

Four mechanisms, one engine. Windsurf's documentation (hosted at docs.devin.ai, still reachable via docs.windsurf.com) describes Memories and Rules as the two ways to persist context, and only Rules are the version-controlled, shareable, deliberately-authored kind. Memories, by contrast, are auto-generated by Cascade and live locally in ~/.codeium/windsurf/memories/, never committed to your repo.

Rules break down like this:

The doc states the current precedence plainly: ".devin/ is preferred and takes precedence over .windsurf/". What it does not spell out is what happens if you have a rule with the same filename in both directories at once — the discovery section only documents deduplication for the case of the same workspace folder opened twice, not for two different source directories colliding. Until Windsurf documents that case explicitly, the safe move is to pick one directory and stay there rather than let both accumulate.

Is .windsurfrules dead, or does it still work?

It still works, which puts Windsurf one step behind Cursor here rather than one step ahead. Cursor's own help pages call the equivalent single-file .cursorrules legacy and describe a four-step migration off it. See Cursor rules and prompt templates for that side of the comparison. Windsurf's documentation is more permissive. The workspace scope table states outright: "The legacy single-file .windsurfrules at the workspace root is also still read." No deprecation language, no migration deadline attached.

That does not make it the file to start with today. It has no frontmatter, so it cannot declare an activation mode — it behaves like an always_on rule whether you want that or not, competing for every request's context budget regardless of whether the current task touches what it describes. If you are starting fresh, write to .devin/rules/ or .windsurf/rules/ instead and give each rule the narrowest activation mode that still does the job.

What do the frontmatter fields actually control?

One field, trigger, decides everything, and it takes four values. Windsurf's own docs describe this field as controlling both when a rule's content reaches Cascade and how much of the context window it consumes on a given message.

The docs give a worked example for the glob case:

---
trigger: glob
globs: "**/*.test.ts"
---

All test files must use `describe` / `it` blocks and mock external API calls.

Two files never use frontmatter at all, because their location already decides the mode: the global global_rules.md, and any root-level AGENTS.md. Both are always on by definition, so there is nothing left for a trigger field to declare.

Six Windsurf rule templates you can paste today

Replace anything in CAPS_LIKE_THIS, delete what doesn't describe your repo, and remember every always_on file is a permanent tax on every message from here forward.

1. Global house style: global_rules.md, always on by default

The one file with no trigger field, because location alone makes it always-on. Keep this under a few hundred characters; the 6,000-character cap is a ceiling, not a target, and this file loads on literally everything you do in Windsurf.

- Package manager is PACKAGE_MANAGER. Never hand-edit a lockfile.
- Prefer editing an existing file over creating a new one.
- When unsure how something is done in this repo, read a neighboring file first.
- Never invent an API, a flag, or a config key you have not verified exists.

2. Workspace house style: .devin/rules/style.md, always on

Everything the global file should not carry, because it is specific to one repo.

---
trigger: always_on
---

- Imports use the `@/` alias for anything under `src/`. No deep relative paths.
- Errors are returned across module boundaries, not thrown. Internal helpers may throw.
- No new dependency without asking first — check `package.json` before suggesting one.
- Server components by default; add a client directive only when the file needs
  state, effects, or browser APIs, and say why in a one-line comment.

3. Framework rule: .devin/rules/react.md, glob-attached

Scoped by file pattern, so it costs nothing while you are editing anything else.

---
trigger: glob
globs: "src/components/**/*.tsx"
---

- Components are named exports. No default exports.
- Data fetching happens in STATE_LAYER; components receive data as props.
- Keep a component under 200 lines. Past that, extract a subcomponent into the
  same directory instead of adding another prop.
- Any user-facing string goes through I18N_HELPER. A bare string literal in JSX
  is a bug, not a detail.

4. How a change gets made here: .devin/rules/workflow.md, model-decision

No glob, just a description Cascade reads to judge relevance. This is the rule that pays for itself fastest, because it encodes the sequence a new contributor spends a week learning.

---
trigger: model_decision
description: How to add or change a feature in this codebase — required order of edits, where each layer lives, what must be updated together
---

Adding a feature touches four places, in this order:

1. Schema first, in MIGRATIONS_DIR, numbered and additive only. Never edit a
   migration that has already run.
2. Data access next, in DATA_DIR — one file per domain, no queries elsewhere.
3. Server action or endpoint in API_DIR, validating input with
   VALIDATION_LIBRARY before anything else runs.
4. UI last, in UI_DIR, consuming the action through STATE_LAYER.

New fields are optional or defaulted. Never rename or remove a column, an
exported symbol, or a route parameter in the same change that adds something —
split it, and say so before writing code if a break is unavoidable.

5. Review: .devin/rules/review.md, manual via @-mention

Loads only when you type @review, because a review pass should be deliberate, not sitting in context by default.

---
trigger: manual
---

Review the current diff. Do not rewrite it. Report findings only, each with the
file, the line, what breaks, and the smallest fix.

Check, in order: correctness (off-by-one, unhandled null, wrong await); contract
breaks (a changed signature, a renamed export, a stored key existing callers
depend on); missing tests for the branch this diff introduces; anything that
duplicates a helper already in HELPERS_DIR.

If the diff is clean, say so in one sentence. Do not invent findings.

6. AGENTS.md: directory-scoped, no frontmatter at all

Drop this at frontend/AGENTS.md and it auto-glob-scopes to everything under frontend/, per Windsurf's own scoping rule: root level is always-on, any subdirectory becomes <directory>/**.

# Frontend conventions

- Functional components with hooks only.
- Naming: ComponentName.tsx for components, useHookName.ts for hooks.
- Every component ships with ComponentName.test.tsx.
- Export components as named exports, never default.

Does Windsurf read AGENTS.md, and how does it decide scope?

Yes, and the mechanism is the cleanest thing about this whole system, because Windsurf's docs describe it as reusing the same engine rather than bolting on a second one: "Devin Desktop automatically discovers it and feeds it into the same Rules engine that powers .devin/rules/ (and the legacy .windsurf/rules/) — just with the activation mode inferred from the file’s location instead of frontmatter". A root-level AGENTS.md behaves like an always_on rule. One inside a subdirectory behaves like a glob rule auto-scoped to <directory>/**. Both AGENTS.md and the lowercase agents.md are recognized, and the docs note that for git repositories, discovery searches up to the git root, the same way .devin/rules/ discovery does.

Windsurf's own comparison table is direct about when to reach for which: use AGENTS.md when you want "simple, location-based instructions", and use Rules "when you need more control over when and how instructions are applied." If you already keep an AGENTS.md for other tools, Windsurf reads it without any extra configuration. See the AGENTS.md standard, explained for what that file format promises across the wider ecosystem.

Rules, AGENTS.md, Workflows, Skills, Memories: which one do you actually want?

Windsurf's docs draw this distinction explicitly, because "windsurf prompts" covers at least three different mechanisms people mean by that phrase, and picking the wrong one wastes the least of your time, not the most.

The practical split: a Rule is the right home for anything phrased as "always behave this way." A Workflow is the right home for anything phrased as "when I run this specific process, do these steps in order" — which is the closer match for what most people actually mean by a reusable prompt template, and it is a separate mechanism from Rules entirely, triggered by typing the workflow's name as a slash command rather than by editing a rule file. If what you are trying to persist is a one-off fact rather than a standing instruction, none of the above is the right tool — that is what Memories already do automatically, and the docs are explicit that anything you want kept reliably and shared with a team belongs in a Rule or AGENTS.md instead, because Memories live only on your machine and are never committed to the repo.

How does this compare to Cursor and Claude Code?

That last row is worth sitting with. Claude Code's own documentation states that an unflagged /init "reads Cursor rules, in .cursor/rules/ or .cursorrules, and Copilot rules, in .github/copilot-instructions.md," and folds the relevant parts into the CLAUDE.md it generates. Windsurf is not in that default list at all. Only with the CLAUDE_CODE_NEW_INIT=1 environment variable set does /init additionally read AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules. If you have written a Windsurf rule set and expect a fresh claude /init to pick it up automatically, it will not, unless that flag is set. That gap is a real, current, and easy-to-miss cost of switching tools mid-project.

Where does AGENTS.md's governance fit into this?

Briefly, because it matters for how much you should trust the format's staying power rather than for anything Windsurf-specific. AGENTS.md was created by OpenAI and, per the Linux Foundation's own announcement, was contributed — alongside Anthropic's Model Context Protocol and Block's goose — to a new Agentic AI Foundation (AAIF) formed under the Linux Foundation on December 9, 2025, with Platinum members including Amazon Web Services, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft and OpenAI. That is neutral, multi-vendor governance for a format that started as one company's convention, which is part of why it keeps showing up as a second, tool-agnostic option next to every vendor-specific rules folder above.

The format's own site, agents.md, describes itself as "used by over 60k open-source projects" and lists a Windsurf entry captioned "from Cognition" among its adopters. That figure is the spec site's own unaudited claim about itself, not a third-party count. Cite it as such rather than as an independently verified number.

Start with two files, not six

If you are setting up Windsurf rules from nothing today, resist writing all six templates above at once. Start with a workspace house-style file, always_on, kept under twenty lines: your package manager, your import convention, the one mistake Cascade has already made twice. Add a model_decision file describing how a change gets made in your specific codebase, because that is the knowledge that takes a new contributor the longest to absorb. Everything else, the glob-scoped framework rule, the manual review rule, a directory-level AGENTS.md, earns its place the second time you correct the same mistake by hand, not before.

One honest note on where Prompt Architects fits into any of this: we do not generate .devin/rules/ or .windsurf/rules/ files, and our MCP server lists Claude Desktop, Claude.ai, Cursor, Claude Code, Codex and Codex CLI as its documented, tested clients. Windsurf is not one of the six. If you want a Prompt Architects prompt inside Windsurf today, copying it from your saved library into the chat box is the path that actually works, not an MCP connection we have verified. Everything about rule files above is Windsurf's own feature, documented by Windsurf, and holds whether or not you ever touch our product. The same honest split is covered from Cursor's side in why Cursor ignores your rules file.

Every mechanic in this post was verified against Windsurf's own documentation, resolved at docs.devin.ai/desktop/cascade/memories and docs.devin.ai/desktop/cascade/agents-md, on September 3, 2026. This is a company mid-rebrand, so if something here disagrees with what you see in the app next month, Windsurf's current docs are the tiebreaker, not this page.