Free Windsurf rules

Windsurf (now also shipped as Devin Desktop) reads workspace rules from Markdown files in .windsurf/rules/. Each file has a trigger in its frontmatter; always_on includes it in every Cascade message.

Goes in: .windsurf/rules/core.md · Format: Workspace rule (.md with trigger frontmatter)

How to install

Create the folder .windsurf/rules/ in your repo root.
Save the file below as .windsurf/rules/core.md.
Fill in the [bracketed] project facts: stack, commands, files not to touch.
Commit it. Each workspace rule file is capped at 12,000 characters; this one is about 2,000.

The rules file

DOWNLOAD windsurf-core.md

---
trigger: always_on
description: Core agent workflow - read first, small diffs, no secrets, verify, report
---
# Core agent rules (always on)

## Project facts (edit these)
- Stack: [e.g. Next.js 15, TypeScript, Tailwind, Postgres via Drizzle]
- Dev: `[npm run dev]` | Test: `[npm test]` | Typecheck: `[npx tsc --noEmit]` | Lint: `[npm run lint]`
- Don't touch: [generated files, e.g. `*.gen.ts`, `migrations/`, `components/ui/`]

## Before editing
- Read the files you will change plus 2-3 neighbours. Match their patterns, naming, error handling and test style.
- If the task touches more than one file or ~30 lines, write a short plan (files + approach) and wait for an OK.
- If the request is ambiguous, ask one focused question instead of guessing.

## While editing
- Make the smallest diff that fully solves the task. No drive-by refactors, renames or reformatting.
- Don't invent APIs, config options or package names. Check the codebase, lockfile or official docs first.
- Don't add a dependency without saying why. Prefer the standard library or what is already installed.
- Keep types honest: no `any`, `@ts-ignore`, `# type: ignore` or disabled lint rules to make errors go away.
- Don't hand-edit generated files, lockfiles or applied migrations unless asked.

## Terminal commands
- Safe to run without asking: read-only commands, typecheck, lint, tests, build.
- Always ask first: installs, deletes, `git push`, database writes, anything touching production.

## Secrets and safety
- Never hard-code, log or echo secrets. Read them from env vars at runtime.
- Every env var the code reads goes in `.env.example` with a placeholder value. `.env*` files (except `.env.example`) stay out of git.
- Public prefixes (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`, `PUBLIC_`) end up in the browser bundle. Never put server keys behind them.

## Verify
- Run what the project has: typecheck, lint, tests, build. Fix failures instead of suppressing them.
- New behaviour gets a test, or a one-line reason why not.

## Report
End every task with: what changed, files touched, how you verified it, and anything left undone or risky.

Notes

Other trigger values: model_decision (Cascade decides from the description), glob (add globs: for matching files), manual (only when you @-mention the rule).
Still on the old single-file setup? Paste the body (without the --- frontmatter block) into .windsurfrules at the repo root. It's legacy, so prefer the folder.
Newer Devin Desktop builds also read .devin/rules/ with the same format; .windsurf/rules/ keeps working.

Using Cursor or Claude Code too? The Mega Pack has stack-specific rules for Next.js, FastAPI, Godot, Unity and discord.js. The Rules Mega Pack ($19) has them.

See how Windsurf ranks on AgentRank (sister project)

Other tools: Cursor · Claude Code · Lovable · Bolt