Windsurf Rules Examples: 7 Rules to Copy (.windsurf/rules and .devin/rules)

Published 2026-10-27 · 6 min read · by AgentKit Co

Windsurf's Cascade agent reads Markdown rule files so you stop repeating "use pnpm, run the tests, don't touch the generated folder" in every chat. Front matter at the top of each file sets a trigger that decides when the rule loads: always, for matching files, when the model decides it's relevant, or only when you @mention it.

This page gives you seven rules to copy, free and without a signup. Everything here was checked on 2026-10-27 against the official Memories & Rules and Workflows docs. Those docs now call the editor Devin Desktop and prefer a .devin/ folder, so this guide covers both the new and the legacy paths. Re-check anything you rely on; this product changes often.

Where the rules live

.devin/ takes precedence over .windsurf/. Rules are also discovered in subfolders and in parent folders up to the git root, and new rules created from the Customizations panel are saved in .devin/rules/ of the current workspace. If you already have a .windsurf/rules/ folder, it keeps working; you don't have to rename it today.

The four triggers

global_rules.md and the root AGENTS.md take no front matter; they are always on.

1. Project basics (always on)

Save as .devin/rules/project.md (or .windsurf/rules/project.md). Keep always-on rules short, because they cost context on every message.

---
trigger: always_on
---

# Project

Invoicer is a web app for freelancers to send invoices and track payments.

- Package manager: pnpm. Never use npm or yarn.
- Before saying a task is done, run `pnpm lint` and `pnpm test` and report the result.
- Money is integer cents plus a currency code. Never use floats for amounts.
- Do not edit anything in `src/generated/`; it is rebuilt by `pnpm codegen`.

2. Tests only (glob)

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

# Tests

- Use `describe`/`it` blocks from Vitest.
- Mock every network call; tests must pass offline.
- One behaviour per test. Name tests after the behaviour, not the function.

The docs' own example uses **/*.test.ts. Patterns like *.js or src/**/*.ts also work; test yours against a real path.

3. Frontend components (glob)

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

# Components

- Function components with typed props; no default exports.
- Style with Tailwind classes. No inline `style={{}}` except for dynamic values.
- Every interactive element needs a visible focus state and an accessible name.

4. Database changes (model decision)

Only the description sits in the prompt until Cascade decides it needs the rest, so write it the way a request would be phrased:

---
trigger: model_decision
description: Use when creating or changing database tables, migrations, indexes or queries.
---

# Database

- Every schema change is a new migration in `db/migrations/`; never edit an applied one.
- Add an index for every new foreign key.
- No raw SQL string concatenation; use the query builder's parameters.

A vague description ("db stuff") gives the model nothing to match.

5. Release checklist (manual)

---
trigger: manual
---

# Release

1. Confirm `main` is green in CI. Stop and tell me if it isn't.
2. Bump the version following semver and explain why it's a patch, minor or major.
3. Update `CHANGELOG.md` from merged PR titles since the last tag.
4. Do not push tags or publish. Print the commands for me to run.

Type @release in the Cascade input to pull it in.

6. Personal defaults (global_rules.md)

~/.codeium/windsurf/memories/global_rules.md applies in every workspace, has no front matter and is capped at 6,000 characters:

# My defaults

- Explain the plan in 3 bullets before large edits.
- Prefer small diffs; don't reformat files you aren't changing.
- Ask before adding a new dependency.

7. A workflow (slash command)

Rules shape behaviour; workflows are step lists you run on demand with /name. Save as .devin/workflows/address-pr-comments.md (or .windsurf/workflows/; global ones go in ~/.codeium/windsurf/global_workflows/). Cascade never runs a workflow on its own, and a workflow can call another (Call /run-tests).

# Address PR comments

1. Check out the PR branch: `gh pr checkout [id]`.
2. List the review comments with `gh api repos/[owner]/[repo]/pulls/[id]/comments`.
3. Handle one comment at a time. If a comment is unclear, don't change anything; ask me.
4. Finish with a summary of what changed and which comments still need me.

Workflow files are also capped at 12,000 characters.

Reusing AGENTS.md

The same rules engine reads AGENTS.md: the root file is always on and a subfolder AGENTS.md is applied like a glob for that folder, with no front matter needed. If you already keep an AGENTS.md for Codex, Cursor, Copilot or Kiro, Cascade uses it too; put only Windsurf-specific or narrowly scoped rules in .devin/rules/ so the same instruction isn't sent twice. See our AGENTS.md examples and AGENTS.md vs CLAUDE.md vs Cursor rules.

Why Cascade ignores a rule

• Wrong or missing trigger. A rule without front matter, or with a typo like trigger: always, won't behave as you expect. Use exactly always_on, glob, model_decision or manual.
• Front matter not first. Put the opening --- on the first line, with nothing above it.
• Over the limit. Workspace rule files stop at 12,000 characters and global_rules.md at 6,000. Split long files by topic.
• The glob doesn't match. *.tsx and src/components/**/*.tsx are different scopes.
• A weak description. model_decision rules only load when the description matches the request.
• You're on the new default agent. The docs say auto-generated memories and workflows apply to the legacy Cascade agent, not the Devin Local agent that new tabs now use, and point to a "Devin: Open Cascade Migration Wizard" command to move them into skills. If a workflow or memory stopped working after an update, check which agent the tab is using.
• Vague rules. "Write good code" changes nothing; the docs say generic rules are unnecessary. "Run pnpm test before finishing" does.
• Relying on memories. Auto-generated memories stay on your machine in ~/.codeium/windsurf/memories/ and only in that workspace. For anything the team needs, write a rule or AGENTS.md entry and commit it.

FAQ

Is .windsurfrules still supported? Yes, the docs say the legacy root file is still read, but per-rule files in .devin/rules/ (or .windsurf/rules/) let each rule have its own trigger.

Should I rename .windsurf/ to .devin/? It's optional for now: .devin/ is preferred and wins when both exist, and .windsurf/ remains a fallback.

Do memories cost credits? The docs say creating and using auto-generated memories does not consume credits.

Get matching files for every tool

The free AGENTS.md generator builds AGENTS.md, CLAUDE.md, GEMINI.md, Cursor, Copilot and Kiro files in your browser from your package.json or pyproject.toml, and AGENTS.md is read by Windsurf too. The AI Coding Agent Config Kit adds stack templates and prompts that audit and test them.

Keep reading