Windsurf Rules Guide: Examples, Locations, and Activation Modes

The official documentation changed during the Windsurf-to-Devin transition. It now prefers workspace rules in .devin/rules/*.md, while .windsurf/rules/*.md remains a fallback for backward compatibility. The legacy root file .windsurfrules is still read.

This distinction matters. A guide that only recommends .windsurf/rules/ no longer reflects the current preferred location.

Windsurf Rules at a glance

Choose the right rule location

Use .devin/rules/*.md for a new repository when you want Windsurf’s current workspace-rule format.

Use AGENTS.md when the instruction should also work with other agents that support the file.

Use global rules only for personal preferences that truly apply across projects. Do not place repository commands or architecture in a global file.

Use system-level rules only through an authorized enterprise administration process.

Windsurf activation modes

Each workspace rule declares its activation mode with a trigger field.

Always-on content consumes context on every request. Reserve it for short, high-value constraints.

Create a workspace rule

In Cascade, open Customizations, select Rules, then choose + Workspace. The current documentation says new rules are saved in .devin/rules/ in the current workspace.

You can also create the file directly.

Glob rule example

Create .devin/rules/typescript-tests.md:

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

# TypeScript test rules

- Use the existing Vitest setup.
- Test behavior through public interfaces.
- Reuse test factories from `test/factories/`.
- Mock external APIs at the network boundary.
- Do not use time-based sleeps.
- Run `pnpm vitest run <changed-test>` before completion.

Model Decision rule example

Create .devin/rules/database-work.md:

---
trigger: model_decision
description: Database schema, migration, and query requirements
---

# Database work

- Put queries in `packages/data/src/repositories/`.
- Create a new migration; never rewrite an applied migration.
- Include a rollback plan for destructive schema changes.
- Do not run a production migration.
- Add an integration test for changed persistence behavior.

The description is important because it is the part Cascade sees before deciding whether to load the full rule.

Manual rule example

Create .devin/rules/security-review.md:

---
trigger: manual
---

# Security review

Review the selected changes for:

1. authentication and authorization gaps;
2. unvalidated external input;
3. secrets or personal data in logs;
4. unsafe redirects or file paths;
5. missing rate limits on public endpoints.

Return findings with file references and severity. Do not edit files unless asked.

Invoke it with @security-review in the Cascade input box.

Always-on rule example

Create .devin/rules/project-basics.md:

---
trigger: always_on
---

# Project basics

- Use `pnpm`; do not create npm or Yarn lockfiles.
- Do not edit `generated/` or commit `.env` files.
- Ask before adding a runtime dependency.
- Run the narrowest relevant test for changed behavior.
- Report verification and any checks not run.

Do not turn a full handbook into one Always On rule. Link to stable project documents or use narrower rules.

Use AGENTS.md with Windsurf

Windsurf processes AGENTS.md through the same Rules engine.

• A root-level AGENTS.md is always on.
• A nested AGENTS.md automatically applies to its directory.
• The file does not need Windsurf rule front matter.

Example structure:

project/
├── AGENTS.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── services/
    └── api/
        └── AGENTS.md

Use the root file for repository-wide commands and boundaries. Use nested files for subproject details.

If the same requirement appears in AGENTS.md and .devin/rules/, choose one authoritative location. Duplicated rules are harder to update and may conflict later.

Current and legacy rule locations

If you already have working .windsurf/rules/ files, do not move them blindly. Check your installed product version, commit the current state, migrate in a branch, and verify rule discovery.

Migrate .windsurfrules safely

1. Review each instruction for accuracy.
2. Remove generic statements such as “write good code.”
3. Split unrelated concerns into separate files.
4. Select an activation mode for each file.
5. Put new files in .devin/rules/ for the current preferred layout.
6. Test Always, Glob, Model Decision, and Manual behavior where used.
7. Remove the legacy file only after verification.

A migration is a good time to replace broad restrictions with observable instructions and exact commands.

Write rules Cascade can follow

Prefer this:

- Run `pnpm vitest run <changed-test>` for affected TypeScript behavior.
- Do not edit files under `src/generated/`.
- Put database access in `packages/data/src/repositories/`.

Avoid this:

- Follow best practices.
- Be careful.
- Make the code production ready.

Good rules are short, specific, and testable. The official docs also recommend bullets, numbered lists, and clear Markdown instead of long paragraphs.

Test whether a Windsurf rule works

1. Open the repository in the target Windsurf or Devin Desktop version.
2. Confirm the rule appears in Customizations → Rules.
3. Start a new Cascade conversation.
4. Trigger a safe, distinctive instruction.
5. For a Glob rule, test one matching and one non-matching file.
6. For a Manual rule, invoke its exact @rule-name.
7. Check for duplicate legacy and current rules.

Rule discovery confirms that content was presented to the model. It does not guarantee deterministic compliance, so tests and code review remain necessary.

Fix Windsurf Rules that do not work

A new rule is not discovered

Check whether it is inside the current workspace. The documentation says new rules are saved relative to the current workspace, which is not always the Git root in a multi-folder setup.

A Glob rule does not activate

Check the trigger value and test the glob against the exact path Cascade reads or edits.

Model Decision never selects a rule

Rewrite description to name the situations in which the rule applies. Keep the full rule focused on that description.

Old and new rules both appear

Search .devin/rules/, .windsurf/rules/, .windsurfrules, global rules, and AGENTS.md. Remove duplicated instructions after confirming the preferred source.

A rule is ignored

Shorten it, remove conflicts, and make each instruction observable. Rules guide an AI model; they do not enforce behavior like permissions, tests, or hooks.

Frequently asked questions

Are Windsurf Rules stored in .windsurf/rules?

That location remains supported as a fallback. The current official documentation prefers .devin/rules/*.md for new workspace rules.

Does Windsurf support AGENTS.md?

Yes. The current documentation says a root file is always on and nested files are scoped to their directories.

Is .windsurfrules still supported?

The current documentation says the legacy single file is still read. New setups should use separate workspace rules or AGENTS.md when portability matters.

Should rules be committed to Git?

Commit workspace rules and AGENTS.md when they describe shared project requirements. Do not commit personal or secret information.

Sources and verification

• Windsurf documentation index
• Windsurf documentation: Memories and Rules
• Windsurf documentation: AGENTS.md

The official product and paths are changing. Recheck the current documentation and installed application before publishing UI screenshots or migration instructions.

Related Markdific guides

• AGENTS.md guide
• Markdown files for AI agents
• Cursor Rules guide