This is the fast reference for prompting Windsurf — the agentic, VS Code-based IDE from Cognition AI whose flagship agent is Cascade. Bookmark it: every @-mention, mode, rule trigger, and modifier that actually changes Cascade's behavior is in a table below, followed by ready-to-paste prompts.
For deeper walkthroughs, pair this with the 40 best Windsurf prompts roundup and the guide to prompting Cascade. Prompts here are Cascade messages (or rule/workflow files where noted); fill the [bracketed placeholders] before sending.
@-mentions reference
@-mentions are context primitives you type into the Cascade pane to point the agent at exact context instead of hoping it finds the right files. Reach for them in every non-trivial prompt.
| Symbol | What it pulls in | When to use |
|---|---|---|
@codebase | Semantic search across the whole indexed repo | You don't know which files matter yet |
@file | One specific file's contents | You know the exact file to edit or reference |
@folder | A directory of files | Scoping work to one module or feature area |
@function / symbol | A named function, class, or symbol | Targeting one unit without the whole file |
@docs | Indexed library / framework documentation | Using an API correctly from real docs |
@web | Live web search results | Checking current syntax, versions, or errors online |
@terminal | Recent terminal output | Feeding a stack trace or build log back to Cascade |
@git | Diffs and commit context | Reviewing changes or writing commit messages |
Example prompts that combine several @-mentions:
Use @codebase to find how we currently handle auth, then update @file:src/middleware/auth.ts to support API keys in addition to sessions. Follow the patterns in @folder:src/middleware. Don't touch unrelated files. Show me the plan first.Why it works: @codebase gathers the pattern, @file and @folder scope the edit precisely.
The build is failing — see @terminal. Cross-reference @docs for the Prisma client and fix @file:src/db/client.ts. If you need current syntax, check @web. Run the build again and iterate until it passes.Best for: handing Cascade the error, the docs, and the target file in one message so it can self-correct.
Cascade modes & keys
Cascade has an agentic Write mode and a read-only Chat/Ask mode; below them, Tab / Supercomplete handles inline prediction. You pick the model per chat — Claude Opus 4.8 / Sonnet 5, GPT-5.x, Gemini, or a fast/auto option.
| Mode / Key | What it does | When to use |
|---|---|---|
| Write mode | Agentic: edits files and runs terminal commands, reads output, self-corrects | Building, fixing, refactoring — anything that changes code |
| Chat / Ask mode | Read-only Q&A; won't edit files | Understanding code, exploring options, planning |
| Planning step | Cascade proposes a plan before executing | Multi-file or risky changes you want to approve first |
| Tab / Supercomplete | Predicts the next edit, imports, and cross-file jumps | Fast in-line editing without a chat message |
Cmd/Ctrl+P | Quick file open (VS Code) | Jumping to a file to @-mention or edit |
Cmd/Ctrl+Shift+P | Command palette (VS Code) | Any command, including Windsurf actions |
Cmd/Ctrl+` | Toggle integrated terminal | Watching commands Cascade runs |
Tip: plan in Chat mode, then switch to Write mode to execute the agreed plan. Same VS Code keybindings you already know still apply, since Windsurf is a VS Code fork.
Rules files
Rules are durable instructions Cascade loads every session, so you stop re-explaining conventions in every prompt. They live in three places and fire based on a trigger in the file's frontmatter.
| Location | Scope | Notes |
|---|---|---|
.windsurf/rules/*.md | Project (scoped, modern) | Multiple small files, each with its own trigger |
.windsurfrules | Project-wide (single file) | One file at repo root |
global_rules.md | All workspaces | Applies everywhere you use Windsurf |
| Trigger | When it fires |
|---|---|
| Always On | Loaded into every Cascade session automatically |
| Manual | Only when you explicitly reference the rule |
| Model Decision | Cascade decides whether the rule is relevant (a.k.a. Agent/Model Requested) |
| Glob | Fires when the files touched match a glob pattern |
Precedence (highest to lowest): Global Rules > .windsurfrules > Memories > your current prompt. Best practice is a short always-on rule that says "follow the matching glob rules," plus several scoped glob rules — that beats one giant always-on file.
Example scoped rule file at .windsurf/rules/react.md:
---
trigger: glob
globs: ["src/**/*.tsx", "src/**/*.jsx"]
---
# React conventions
- Use function components and hooks only; no class components.
- Co-locate a *.test.tsx next to every component.
- Type all props with an explicit interface named <Component>Props.
- Never import default-exported components; use named exports.
- Keep components under 150 lines; extract hooks into src/hooks/.Memories & Workflows
Memories are short workspace facts that survive across sessions; Workflows are reusable multi-step recipes invoked by a slash command. Use Memories for durable context, Workflows for sequences you'd otherwise retype.
| Memories | Workflows | |
|---|---|---|
| Scope | Workspace-scoped facts / conventions | Multi-step agentic recipe (.windsurf/workflows/) |
| Lifespan | Persist across sessions | Persist as a Markdown file in the repo |
| How invoked | Auto-loaded; auto-generated or you ask Cascade to create one | Typed as /workflow-name in Cascade |
Ask Cascade to create a memory:
Create a memory: our API base URL comes from process.env.API_URL, all fetch calls go through src/lib/api.ts, and we never call fetch() directly in components.Example workflow file at .windsurf/workflows/ship.md, invoked with /ship:
---
description: Lint, test, build, and open a PR
---
# Ship
1. Run `npm run lint -- --fix` and fix any remaining errors.
2. Run `npm test` and iterate until every test passes.
3. Run `npm run build`; fix any type or build errors.
4. Summarize the diff, then create a branch and open a PR
with a title and description that reference @git.Rule of thumb: make a workflow when you'd otherwise rewrite the same prompt by hand at least weekly.
Prompt modifiers that work
These reusable phrases reliably steer Cascade. Drop them into any prompt to control scope, verification, and blast radius.
| Modifier phrase | Effect |
|---|---|
| "Plan before you edit." | Cascade proposes a plan you approve before it writes code |
| "Only touch these files: [paths]." | Constrains the edit to a known blast radius |
| "Run the tests and fix until green." | Sets an acceptance criterion; Cascade iterates until tests pass |
| "Don't change public APIs or signatures." | Prevents breaking callers during a refactor |
| "Explain, don't edit." | Forces read-only behavior even in Write mode |
| "Show the diff, then wait for approval." | Lets you review per-file changes before accepting |
| "Add tests for the change and run them." | Cascade writes and executes tests alongside the code |
Stack them — a good prompt usually names exact paths, sets acceptance criteria, and scopes the change in one message. See the Windsurf prompt templates for fill-in-the-blank versions.
Copy-paste starter prompts
Five high-utility prompts covering the common jobs: onboard, build, debug, refactor, and ship. Paste into Cascade and fill the placeholders.
Onboard Cascade to a new repo
Chat mode. Use @codebase to give me a map of this project: entry points, main modules, how data flows, the test setup, and the build/run commands. Then propose a .windsurfrules file capturing the conventions you inferred. Explain, don't edit.Build a feature
Write mode. Add [feature] to @folder:[dir]. Use @docs for [library]. Plan before you edit, then implement it, add tests for the change, and run the tests and fix until green. Only touch files inside @folder:[dir]. Show the diff before finishing.Debug an error
Here's the failure in @terminal. Use @codebase to trace the root cause, propose the smallest fix, and apply it to the exact file(s) responsible. Don't change public APIs. Re-run the failing command and iterate until it passes.Refactor safely
Refactor @file:[path] for readability and to remove duplication. Keep behavior identical and don't change public signatures. Run the existing tests after each step and fix until green. Show me the diff before accepting.Ship the change
Run lint, tests, and build; fix anything that fails until all three are green. Then summarize the diff using @git and draft a commit message and PR description. Don't push — show me first.For 40 more field-tested prompts, see the best Windsurf prompts roundup.
Frequently Asked Questions
What are @-mentions in Windsurf?
@-mentions are context primitives you type in the Cascade pane to point the agent at exact context: @codebase, @file, @folder, a @function or symbol, @docs, @web, @terminal, and @git. They replace guessing with precise, scoped context.
What is the difference between Write mode and Chat/Ask mode?
Write mode is agentic: Cascade edits files and runs terminal commands. Chat/Ask mode is read-only — it answers questions and helps you plan but won't modify files. Use Chat to plan, then switch to Write to execute.
Where do Windsurf rules live?
In the .windsurf/rules/ directory as scoped Markdown files, in a single .windsurfrules file at the repo root for project-wide rules, and in global_rules.md which applies across every workspace. Each rule file has a trigger: Always On, Manual, Model Decision, or Glob.
What is the precedence order for Windsurf context?
Highest to lowest: Global Rules, then .windsurfrules, then Memories, then your current prompt. Higher layers win when instructions conflict.
How are Memories different from Workflows?
Memories are short workspace-scoped facts that survive across sessions so you stop re-explaining conventions. Workflows are reusable multi-step agentic recipes stored in .windsurf/workflows/ and invoked with a /workflow-name slash command.
Can I choose which model Cascade uses?
Yes. You pick the model per Cascade chat: Claude Opus 4.8 or Sonnet 5, GPT-5.x, Gemini, or a fast/auto option. Prompting technique usually matters more than the model choice.