Windsurf Prompts & Rules

Windsurf's Cascade agent is powerful in direct proportion to how well you constrain it. Two levers matter: a .windsurfrules file that applies to every interaction (stack, testing, commit conventions, dependency discipline), and per-task workflows that force the plan → build → verify order instead of a 30-file sweep.

Start with the rules template, then use the workflow prompts for anything bigger than a one-line change.

# Project Rules

- Stack: <your stack — e.g. Next.js 15 + TypeScript + Tailwind + Postgres>
- All new code must type-check and lint clean before you report done
- Prefer editing existing files over creating new ones; never create a file without stating why
- Tests colocated as *.test.ts, Vitest; every bug fix ships with a failing-first test
- No new dependencies without asking; if a task seems to need one, propose it and wait
- Commits: imperative, under 72 chars; never mix refactor and feature
- When requirements are ambiguous, list the 2 most likely readings and pick the conservative one, noting the choice

We're building: <feature description>. Follow this workflow strictly:
PLAN — list every file you'll touch and the order; wait for my OK.
BUILD — one file at a time, each step must compile; stop if a step breaks something unexpected and tell me.
VERIFY — run the full test suite plus a manual test script you write for this feature; report results honestly, including what you did NOT test.
Do not skip PLAN even when the feature seems small.

Refactor <file or module> with one rule above all: BEHAVIOR MUST NOT CHANGE.
Sequence: (1) list current observable behaviors as test cases and add them BEFORE touching code; (2) run them green; (3) refactor in small commits — rename, extract, dedupe — running tests after each; (4) report the diff summary and any dead code found but not deleted. If a test fails mid-refactor, stop and show me.

Bootstrap tests for <module>: (1) inventory every exported function with a one-line behavior guess; (2) for each, write happy-path + one edge case + one failure case; (3) flag any function you cannot test without mocks and propose the mock design; (4) run the suite and report coverage before/after. Tests must fail meaningfully when the code breaks — verify by temporarily breaking one thing (then restore it).