AgentdexBlog · · Agentdex Editorial
Windsurf Rules: How to Write Rules That Work (2026)
Windsurf rules are markdown files that tell the AI agent how to work in your project: which stack you use, how you name things, what to test and what to avoid. Windsurf was renamed Devin Desktop (Agentdex profile) on June 2, 2026, but the rules system carried over, and old Windsurf rule files still work. This guide covers where rules live, how activation modes work, the character limits and how to write rules that actually change the agent's behavior, based on the official Devin Desktop docs as of October 24, 2026.
Key Takeaways
- Windsurf is now Devin Desktop. Workspace rules go in
.devin/rules/*.md, and the older.windsurf/rules/folder and root.windsurfrulesfile are still read. - Global rules live in
~/.codeium/windsurf/memories/global_rules.mdand apply to every project. - Each rule uses a
triggerin its frontmatter:always_on,model_decision,globormanual. - Limits: 6,000 characters for the global rules file and 12,000 characters per workspace rule file.
- AGENTS.md is also supported, and Devin Desktop can import Cursor (Agentdex profile) rules.
- Keep rules short and specific. Generic advice like "write clean code" wastes context.
What changed when Windsurf became Devin Desktop
Devin Desktop is the same editor with a new name and the same pricing (see our Windsurf pricing guide). The bigger change is the agent. Devin Local is now the default agent for new conversations. It shares its harness with the Devin CLI, supports subagents and sandboxing, and uses up to 30% fewer tokens than the previous Cascade agent. Old Cascade chats remain, but new conversations no longer start on Cascade.
For rules, this means:
.devin/rules/is the preferred workspace folder and takes precedence over.windsurf/rules/.- New rules you create in the app are saved to
.devin/rules/. - Existing
.windsurf/rules/files and a root.windsurfrulesfile are still read, so you don't have to migrate right away. - Memories only apply to the legacy Cascade agent. Devin Local doesn't keep memories, so move anything important into rules or skills. The Cascade Migration Wizard can convert memories to skills.
Where Windsurf rules live
Scope | Location | Limit |
|---|---|---|
Global | ~/.codeium/windsurf/memories/global_rules.md (always on) | 6,000 characters |
Workspace | .devin/rules/*.md (preferred) or .windsurf/rules/*.md | 12,000 characters per file |
Legacy | .windsurfrules in the project root | Still read |
AGENTS.md | Root file is always on; a file in a subfolder applies to files in that folder | n/a |
System (Enterprise) | /etc/devin/rules/ on Linux, /Library/Application Support/Devin/rules/ on macOS, C:\ProgramData\Devin\rules\ on Windows | Set by admins |
Devin Desktop looks for workspace rules in the current workspace, its subfolders and parent folders up to the git root, so a monorepo can have shared rules at the top and package-specific rules lower down. There is no .devinrules file; use the .devin/rules/ folder.
Activation modes
Every workspace rule file starts with frontmatter that sets its trigger. Choosing the right trigger matters more than anything else, because always-on rules are sent with every message and cost context.
Trigger | How it works | Use it for |
|---|---|---|
always_on | Full rule included in every message | Stack, core conventions, hard "never do" rules |
model_decision | Only the description is shown; the agent loads the full rule when relevant | Topic guides such as auth, payments or migrations |
glob | Applied when the agent reads or edits files matching a pattern | Test, component or API conventions |
manual | Only applied when you mention it with @rule-name | Occasional tasks like release notes |
Example rule files
An always-on project rule
---
trigger: always_on
---
# Project basics
- Stack: Next.js (App Router), TypeScript, Tailwind CSS, Supabase.
- Use pnpm, never npm or yarn.
- Put shared UI in components/ui and data access in lib/db.
- Never commit secrets. Read keys from environment variables.
- Run pnpm lint and pnpm test before saying a task is done.A glob rule for tests
---
trigger: glob
globs: **/*.test.ts
---
- Use Vitest with describe/it blocks.
- One behavior per test. Name tests after the behavior, not the function.
- Mock network calls; never hit real APIs in tests.A model-decision rule
---
trigger: model_decision
description: How to add or change database tables and migrations
---
- Create a new migration file; never edit an applied migration.
- Add row-level security policies for every new table.
- Update the generated types after schema changes.How to create rules in Devin Desktop
- Open Customizations, then Rules.
- Click "+ Global" for a rule that applies everywhere, or "+ Workspace" for this project.
- Name the rule, pick a trigger and write the content.
- Commit workspace rules to git so your whole team shares them.
Devin Desktop can also import Cursor's .cursor/rules files into .devin/rules/, which helps if you switch editors. Official rule templates are available in the Windsurf rules directory.
How to write rules that work
- Be specific. "Use Zod schemas in lib/validation for all API input" changes behavior. "Validate input properly" doesn't.
- Use bullet points and markdown headings. The docs recommend concise, structured rules. XML-style tags can help group related rules.
- Skip generic rules. The model already knows to write readable code. Spend your characters on what's unique to your project.
- Keep always-on rules small. Move topic-specific guidance to
model_decisionorglobrules so it only loads when needed. - Split by concern. Several focused files are easier to maintain than one long file near the 12,000-character limit.
- Update rules when the agent repeats a mistake. A rule written after a real failure is usually the most useful one you have.
Rules, AGENTS.md, workflows and skills
Rules aren't the only way to guide the agent:
- AGENTS.md works across many AI coding tools. Use it for instructions you want Devin Desktop, Claude Code (Agentdex profile), Codex (Agentdex profile) and others to share.
- Workflows are saved prompts you run manually with a slash command.
- Skills are reusable bundles of instructions and resources that the agent loads when relevant. The docs recommend skills for larger guidance, since they cost less context than always-on rules.
If you use the Devin CLI as well, it reads AGENTS.md, .windsurfrules, CLAUDE.md and .devin/rules/, so one set of files can cover both.
Windsurf rules vs Cursor rules
The two systems are similar. Cursor uses .cursor/rules with .mdc files and its own activation types, while Devin Desktop uses markdown files with a trigger field. If you use both editors, keep shared instructions in AGENTS.md and editor-specific details in each tool's rules folder. Our Cursor rules guide covers the Cursor side.
FAQ
Where do I put Windsurf rules?
Put workspace rules in .devin/rules/ in your project. The older .windsurf/rules/ folder and root .windsurfrules file still work. Global rules go in ~/.codeium/windsurf/memories/global_rules.md.
Is .windsurfrules still supported?
Yes. Devin Desktop still reads a root .windsurfrules file, but new rules should go in .devin/rules/, which also supports activation modes.
What is the character limit for Windsurf rules?
The global rules file is limited to 6,000 characters, and each workspace rule file to 12,000 characters.
Do Windsurf memories still work?
Memories only apply to the legacy Cascade agent. Devin Local, the new default agent, doesn't keep memories, so move important ones into rules or skills.
Can I use my Cursor rules in Devin Desktop?
Yes. Devin Desktop can import .cursor/rules files into .devin/rules/, and both tools support AGENTS.md.
Written by Agentdex Editorial. Agentdex is an independent directory reviewing AI coding tools; we are not affiliated with the companies mentioned. Prices and features are as of October 24, 2026, from official sources linked above. Always confirm on the vendor's site.