Windsurf Prompts That Steer Cascade Like a Senior Engineer
30 copy-paste prompts for building, refactoring, debugging, and testing across your codebase — each engineered to give Cascade the scope, context, and constraints it needs to ship clean code autonomously.
In short: This page contains 30 copy-paste ready prompts, organized into 6 categories with a description and pro tip for each. The first 15 prompts are free instantly — no signup needed. Hand-curated and tested by the AI Academy team.
Building Features
5 promptsScoped Feature Build
1/30<context> Feature: [WHAT YOU ARE BUILDING] Codebase/stack: [YOUR CODEBASE/STACK] Where it lives: [FILES/DIRECTORIES TO TOUCH] Out of scope: [WHAT NOT TO CHANGE] </context> <task> Build this feature end to end. Before writing code: 1. Search the codebase for existing patterns I should follow (naming, file structure, state management, API layer). 2. Restate the plan as a short numbered checklist and list every file you will create or edit. 3. Implement, reusing existing utilities and components instead of duplicating logic. 4. Wire up the feature so it is reachable from the UI/entry point, not just defined in isolation. 5. Run the build/typecheck and fix any errors before reporting done. Do not touch anything in the out-of-scope list. </task>
Produces a fully wired, convention-matching feature implementation with a verification pass.
Pro tip: Keep the out-of-scope list explicit — Cascade is most accurate when its blast radius is bounded.
Spec-First Component
2/30<context> Component: [COMPONENT NAME / PURPOSE] Stack: [YOUR CODEBASE/STACK] Inputs (props/params): [LIST] States to handle: [LOADING / EMPTY / ERROR / SUCCESS] Design reference: [LINK, FILE, OR DESCRIPTION] </context> <task> Write a one-paragraph spec of the component's behavior, then implement it. 1. Match the existing component structure and styling system in the repo. 2. Handle every state listed above explicitly. 3. Make it accessible: keyboard navigation, focus states, ARIA labels where relevant. 4. Add usage examples or a story if the repo uses Storybook. 5. Show me the spec first, then the diff. </task>
Generates a behavior spec plus an accessible, state-complete component matching repo conventions.
Pro tip: Paste a screenshot into Cascade alongside this prompt — it reads images and matches visual layouts closely.
API Endpoint With Validation
3/30<context> Endpoint: [METHOD + ROUTE, e.g. POST /api/orders] Stack/framework: [YOUR CODEBASE/STACK] Request shape: [FIELDS + TYPES] Response shape: [FIELDS + TYPES] Auth: [WHO CAN CALL THIS] </context> <task> Implement this endpoint following the repo's existing route patterns. 1. Validate the request body and return structured 4xx errors on bad input. 2. Enforce the auth rule before any business logic runs. 3. Use the existing data-access layer; do not write raw queries if an ORM/repository exists. 4. Return the exact response shape, with correct status codes. 5. Add at least two tests: a happy path and a validation-failure path. </task>
Delivers a validated, authorized endpoint plus baseline tests in the repo's style.
Pro tip: Name the existing data-access file so Cascade reuses it instead of inventing a new query layer.
Incremental Feature Flag Rollout
4/30<context> Feature: [FEATURE TO GATE] Flag system: [YOUR FLAG TOOL OR ENV VAR] Stack: [YOUR CODEBASE/STACK] </context> <task> Add this feature behind a flag so it can ship dark. 1. Find how flags are currently read in the codebase and follow that pattern. 2. Wrap all new behavior so the old path is the default when the flag is off. 3. Ensure the off-path is byte-for-byte the previous behavior (no regressions). 4. Document how to enable the flag locally and in production. 5. List exactly which lines change behavior when the flag flips. </task>
Produces a dark-shippable feature gated cleanly behind your existing flag system.
Pro tip: Ask Cascade to diff the off-path against current behavior so you can confirm zero regression risk.
Third-Party Integration
5/30<context> Integrate: [SERVICE/API NAME] Goal: [WHAT IT SHOULD DO] Stack: [YOUR CODEBASE/STACK] Credentials live in: [ENV VARS / SECRET STORE] </context> <task> Integrate this service safely. 1. Read the official docs for the relevant endpoints before coding (use the docs link if I provide one). 2. Create a thin client/wrapper module so the rest of the app does not call the SDK directly. 3. Never hardcode secrets; read them from the configured location and fail loudly if missing. 4. Handle rate limits, timeouts, and retryable errors. 5. Add a smoke test that mocks the external call. </task>
Builds an isolated, secret-safe integration wrapper with error handling and a mocked test.
Pro tip: A wrapper module keeps the vendor SDK swappable and makes Cascade's later refactors far cleaner.
Prompts get you started. Tutorials level you up.
A growing library of 300+ hands-on AI tutorials. New tutorials added every week.
Refactoring
5 promptsSafe Extract & Dedupe
6/30<context> Target: [FILE/FUNCTION/MODULE TO REFACTOR] Stack: [YOUR CODEBASE/STACK] Constraint: behavior must stay identical. </context> <task> Refactor this code without changing its observable behavior. 1. First, list the duplicated or tangled logic you see, with line references. 2. Propose the target structure (extracted functions, shared module) before editing. 3. Make the change in small steps, keeping every call site working. 4. Update all references across the codebase, not just the file I named. 5. Run the existing tests and confirm they still pass. </task>
Performs a behavior-preserving refactor with full call-site updates and a test confirmation.
Pro tip: Insist on 'observable behavior unchanged' — it stops Cascade from sneaking in feature changes during cleanup.
Modernize Legacy Pattern
7/30<context> Legacy pattern: [WHAT TO REPLACE, e.g. callbacks, class components, var] Replace with: [TARGET PATTERN] Scope: [FILES/DIRECTORY] Stack: [YOUR CODEBASE/STACK] </context> <task> Migrate the legacy pattern to the target pattern across the given scope. 1. Find every occurrence within scope and list them before editing. 2. Convert one representative file first and show me the diff for approval. 3. After I approve, apply the same transformation to the rest consistently. 4. Do not change unrelated code or formatting outside the migration. 5. Re-run typecheck/lint and fix anything the migration broke. </task>
Migrates a legacy pattern codebase-wide with a sample-first approval gate.
Pro tip: The approve-one-then-batch flow lets you catch a wrong transformation before it spreads across 40 files.
Split a God File
8/30<context> File: [THE OVERSIZED FILE] Stack: [YOUR CODEBASE/STACK] What it does: [RESPONSIBILITIES] </context> <task> Break this file into focused modules. 1. Map its current responsibilities and group related code. 2. Propose a new file layout (names + what moves where) before moving anything. 3. Move code in coherent chunks, fixing imports as you go. 4. Keep the public API stable so external imports do not break. 5. Confirm the app builds and existing imports resolve. </task>
Splits an overgrown file into cohesive modules while preserving the public import surface.
Pro tip: Ask Cascade to keep a thin re-export at the old path so nothing downstream breaks during the split.
Type-Safety Hardening
9/30<context> Area: [FILES/MODULE WITH WEAK TYPES] Stack: [YOUR CODEBASE/STACK] Goal: remove any/implicit-any and tighten types. </context> <task> Increase type safety in this area. 1. Identify every any, unchecked cast, or implicit-any and list them. 2. Replace them with precise types derived from real usage, not guesses. 3. Add types at module boundaries (function signatures, exports) first. 4. Do not introduce runtime behavior changes. 5. Run the typechecker and report the before/after error count. </task>
Tightens types across a module with no runtime changes and a measurable error-count delta.
Pro tip: Have Cascade derive types from actual call sites — generated guesses often hide the very bugs you are chasing.
Performance Pass
10/30<context> Slow path: [WHAT IS SLOW + HOW YOU MEASURED IT] Stack: [YOUR CODEBASE/STACK] Constraint: keep behavior identical. </context> <task> Optimize this path without changing results. 1. Analyze the code and name the likely bottlenecks (N+1 queries, re-renders, unbatched I/O, etc.). 2. Rank fixes by impact-to-effort and tell me which you will do. 3. Implement the high-impact fixes, leaving comments only where the optimization is non-obvious. 4. Add a quick benchmark or note how to measure the improvement. 5. Verify outputs match the pre-optimization behavior. </task>
Diagnoses and fixes real bottlenecks while proving outputs are unchanged.
Pro tip: Give Cascade your actual measurement (a slow query log, a profiler flame graph) so it targets the real hot path.
Debugging
5 promptsRoot-Cause From Error
11/30<context> Error/symptom: [PASTE THE STACK TRACE OR DESCRIBE THE BUG] When it happens: [STEPS TO REPRODUCE] Stack: [YOUR CODEBASE/STACK] </context> <task> Find and fix the root cause — not just the symptom. 1. Trace the error back through the codebase to its origin and explain the actual cause. 2. State your hypothesis before changing anything. 3. Apply the minimal fix that addresses the root cause. 4. Add a regression test that fails without your fix and passes with it. 5. Note any other places in the code with the same latent bug. </task>
Traces a bug to its true origin, applies a minimal fix, and locks it in with a regression test.
Pro tip: Paste the full stack trace, not a paraphrase — Cascade follows real file:line references straight to the cause.
Reproduce Then Fix
12/30<context> Bug: [WHAT GOES WRONG] Expected vs actual: [WHAT SHOULD HAPPEN / WHAT HAPPENS] Stack: [YOUR CODEBASE/STACK] </context> <task> Reproduce the bug before fixing it. 1. Write a failing test or a minimal script that reproduces the issue. 2. Run it and confirm it reproduces; paste the output. 3. Diagnose the cause and fix it. 4. Re-run the repro to confirm it now passes. 5. Summarize what was wrong and why the fix is correct. </task>
Forces a reproducible failing case first, so the fix is verified rather than assumed.
Pro tip: Reproduce-first prevents Cascade from 'fixing' code that was never actually the problem.
Heisenbug / Intermittent Failure
13/30<context> Flaky behavior: [WHAT FAILS SOMETIMES] Frequency/conditions: [WHEN IT TENDS TO HAPPEN] Stack: [YOUR CODEBASE/STACK] </context> <task> Hunt down this intermittent failure. 1. List plausible causes of non-determinism here: race conditions, shared state, timing, ordering, unmocked time/randomness. 2. Search the relevant code for each and report what you find. 3. Propose the most likely culprit with evidence. 4. Implement a fix that removes the non-determinism, not just retries. 5. Add a deterministic test that would catch a regression. </task>
Systematically isolates sources of non-determinism behind a flaky bug and removes them.
Pro tip: Ask Cascade to run the suspect test in a loop in the terminal to confirm the flake is actually gone.
Regression Bisect
14/30<context> Broke recently: [WHAT WORKED BEFORE AND NOW DOESN'T] Last known good: [COMMIT / DATE / VERSION] Stack: [YOUR CODEBASE/STACK] </context> <task> Find what introduced this regression. 1. Review recent changes to the affected area using git history. 2. Identify the most likely offending change and explain why. 3. Confirm by reasoning through how that change causes the symptom. 4. Fix the regression without reverting unrelated improvements. 5. Add a test that pins the correct behavior going forward. </task>
Uses recent history to pinpoint the change that broke things, then fixes it surgically.
Pro tip: Let Cascade run git log/blame itself — it reads the diffs and reasons about which one matches the symptom.
Explain Then Fix Confusing Code
15/30<context> Confusing code: [FILE/FUNCTION] What I think it should do: [YOUR UNDERSTANDING] Stack: [YOUR CODEBASE/STACK] </context> <task> Help me understand this code, then fix the discrepancy. 1. Walk through what the code actually does, step by step. 2. Point out where it diverges from my stated expectation. 3. Tell me whether the code or my expectation is wrong. 4. If the code is wrong, fix it; if my mental model is wrong, explain why. 5. Leave a short clarifying comment only where the logic is genuinely non-obvious. </task>
Reconciles your mental model with the real code behavior and fixes whichever is wrong.
Pro tip: Stating your assumption explicitly surfaces the exact line where your understanding and the code part ways.
Writing Tests
5 promptsCover an Untested Module
16/30<context> Module: [FILE/FUNCTION TO TEST] Stack + test framework: [YOUR CODEBASE/STACK] </context> <task> Write a meaningful test suite for this module. 1. Read the code and list its behaviors, branches, and edge cases. 2. Follow the repo's existing test conventions (framework, naming, mocks, fixtures). 3. Cover happy paths, error paths, and boundary conditions — not just the obvious case. 4. Avoid brittle tests that assert on implementation details rather than behavior. 5. Run the suite and confirm it passes; report coverage if available. </task>
Generates a behavior-focused test suite covering branches and edge cases, matching repo conventions.
Pro tip: Ask for tests on behavior, not internals — implementation-coupled tests break on every refactor.
Edge-Case Generator
17/30<context> Function under test: [SIGNATURE + WHAT IT DOES] Stack: [YOUR CODEBASE/STACK] </context> <task> Enumerate edge cases I probably missed, then test them. 1. List edge cases: empty/null inputs, max/min values, unicode, concurrency, ordering, off-by-one. 2. Mark which are realistic for this function versus theoretical. 3. Write tests for the realistic ones in the repo's framework. 4. Flag any edge case the current code handles incorrectly. 5. Run the tests and report failures separately from passes. </task>
Surfaces overlooked edge cases and turns the realistic ones into tests that may expose real bugs.
Pro tip: Failing edge-case tests are a feature here — they reveal bugs before your users do.
Integration Test For a Flow
18/30<context> Flow: [USER/SYSTEM FLOW, e.g. signup -> verify -> first login] Stack + test setup: [YOUR CODEBASE/STACK] </context> <task> Write an integration test for the full flow. 1. Identify the components/services the flow touches. 2. Set up realistic test data and tear it down afterward. 3. Assert on observable outcomes at each step (DB state, responses, side effects). 4. Mock only true external boundaries (third-party APIs), not internal modules. 5. Make the test runnable in CI without manual setup. </task>
Produces a CI-ready integration test exercising a real multi-step flow end to end.
Pro tip: Mocking internal modules defeats integration tests — keep mocks at the external boundary only.
Backfill Tests Before Refactor
19/30<context> About to refactor: [CODE YOU WILL CHANGE] Stack: [YOUR CODEBASE/STACK] </context> <task> Create a safety net of characterization tests for the current behavior before I refactor. 1. Capture what the code does today, including quirks, as passing tests. 2. Do not fix bugs yet — just document current behavior so refactors are detectable. 3. Cover the main inputs and outputs that the refactor must preserve. 4. Run them and confirm they pass against the current code. 5. Tell me which behaviors are unclear and need my input. </task>
Builds characterization tests that pin current behavior so an upcoming refactor stays safe.
Pro tip: Lock in current behavior first; then any refactor that breaks a test is caught instantly.
Diagnose & Fix a Flaky Test
20/30<context> Flaky test: [TEST NAME/FILE] How it fails: [INTERMITTENT? CI-ONLY? ORDER-DEPENDENT?] Stack: [YOUR CODEBASE/STACK] </context> <task> Make this test reliable. 1. Identify the source of flakiness: timing, shared state, unmocked time/random, test ordering. 2. Run the test repeatedly to confirm the failure mode. 3. Fix the underlying cause; do not just add sleeps or retries. 4. Confirm it passes consistently across multiple runs and in isolation. 5. Note whether other tests share the same flaky pattern. </task>
Eliminates the real cause of a flaky test rather than masking it with retries.
Pro tip: Have Cascade run the test 20 times in the terminal — a fix that survives a loop is a real fix.
Scaffolding Projects
5 promptsNew Project Scaffold
21/30<context> Project: [WHAT YOU ARE BUILDING] Stack: [YOUR CODEBASE/STACK] Must include: [AUTH? DB? TESTING? CI?] </context> <task> Scaffold a clean starting point for this project. 1. Propose the folder structure and key files before generating anything. 2. Set up the chosen stack with sensible defaults and a working hello-world entry point. 3. Add linting, formatting, and a test runner wired into scripts. 4. Create a README with setup, run, and test instructions. 5. Confirm the project installs and the dev server/build runs cleanly. </task>
Bootstraps a runnable, lint-and-test-ready project skeleton with documentation.
Pro tip: Approve the proposed structure before generation — restructuring a scaffold later is more work than tweaking the plan.
Add a New Module to Existing App
22/30<context> New module: [FEATURE AREA, e.g. billing, notifications] Stack: [YOUR CODEBASE/STACK] Existing conventions: [HOW MODULES ARE STRUCTURED HERE] </context> <task> Scaffold a new module that fits the existing architecture. 1. Study how current modules are organized and mirror that structure exactly. 2. Create the directories, entry files, and routing/registration the app expects. 3. Stub the public interface with clear TODOs for the real logic. 4. Wire the module into the app so it is discoverable, not orphaned. 5. Add a placeholder test file in the right location. </task>
Drops in a new module that matches existing architecture and is wired into the app.
Pro tip: Point Cascade at one existing module as a template so the new one is structurally identical.
Dev Environment & Tooling Setup
23/30<context> Project: [REPO/STACK] Goal: reproducible local dev setup. Stack: [YOUR CODEBASE/STACK] </context> <task> Make this project easy to run from a clean clone. 1. Audit what is currently required to run it and what is undocumented. 2. Add or fix the setup: env example file, scripts, and a one-command dev start. 3. Pin tool/runtime versions where it matters. 4. Document common gotchas you discovered. 5. Verify by reasoning through a fresh-clone run; flag steps that still need a real machine. </task>
Turns an undocumented project into a one-command, reproducible local setup.
Pro tip: Ask Cascade to list undocumented assumptions — those hidden steps are what break new contributors.
CI Pipeline Scaffold
24/30<context> CI provider: [GITHUB ACTIONS / GITLAB CI / OTHER] Stack: [YOUR CODEBASE/STACK] Must run: [LINT / TYPECHECK / TEST / BUILD] </context> <task> Create a CI pipeline for this repo. 1. Detect the package manager and scripts already defined. 2. Write a pipeline that installs deps with caching and runs the required checks. 3. Fail fast on lint/typecheck before running the full test suite. 4. Use the project's real script names, not invented ones. 5. Explain how to extend it for deploys later. </task>
Generates a caching, fail-fast CI config wired to your actual project scripts.
Pro tip: Have Cascade read package.json/Makefile first so the pipeline calls scripts that genuinely exist.
Data Model & Migration Scaffold
25/30<context> Entities: [WHAT YOU NEED TO MODEL + RELATIONSHIPS] ORM/DB: [YOUR CODEBASE/STACK] </context> <task> Scaffold the data model and migrations. 1. Propose the schema (tables/models, fields, types, relations, indexes) before generating. 2. Follow the repo's existing schema and migration conventions. 3. Generate the migration files; do not edit a previously applied migration. 4. Add the model/repository layer the app uses to access this data. 5. Tell me the exact command to apply the migration locally. </task>
Produces schema, migrations, and a data-access layer consistent with your ORM conventions.
Pro tip: Never let an agent edit an already-applied migration — always confirm it generates a new one.
Go from copy-pasting to actually mastering AI.
AI Academy: 300+ hands-on tutorials on ChatGPT, Claude, Midjourney, and 50+ other tools. New tutorials added every week.
Steering Cascade
5 promptsPlan Before You Code
26/30<context> Task: [WHAT YOU WANT BUILT/CHANGED] Stack: [YOUR CODEBASE/STACK] </context> <task> Do NOT write code yet. First, produce a plan. 1. Restate the goal in your own words to confirm understanding. 2. List the files you would create or edit and why. 3. Call out risks, unknowns, and decisions that need my input. 4. Give me a numbered implementation checklist. 5. Wait for my approval before making any edits. </task>
Forces Cascade to surface a reviewable plan and open questions before touching code.
Pro tip: A planning turn catches misunderstandings cheaply — fixing a plan beats reverting 12 files.
Constrain the Blast Radius
27/30<context> Change: [THE SPECIFIC CHANGE] Stack: [YOUR CODEBASE/STACK] May edit: [ALLOWED FILES/DIRS] Must NOT touch: [PROTECTED AREAS] </context> <task> Make only this change, nothing more. 1. Limit edits to the allowed files; never modify the protected areas. 2. Do not reformat, rename, or refactor code unrelated to the task. 3. If the task seems to require touching a protected area, stop and ask instead. 4. Show me the complete diff before applying. 5. Confirm at the end that no out-of-scope files changed. </task>
Keeps Cascade tightly scoped so it cannot make unrequested edits across the codebase.
Pro tip: Naming protected areas explicitly is the single best guard against an agent's well-meaning scope creep.
Ground Cascade in Project Context
28/30<context> Task: [WHAT TO DO] Key context: [ARCHITECTURE NOTES, CONVENTIONS, GOTCHAS] Reference files: [PATHS CASCADE SHOULD READ FIRST] Stack: [YOUR CODEBASE/STACK] </context> <task> Before doing anything, build context. 1. Read the reference files and any rules/conventions files in the repo. 2. Summarize back to me how this codebase does the relevant thing. 3. Point out where the task conflicts with existing patterns, if anywhere. 4. Then propose your approach grounded in what you found. 5. Proceed only after I confirm your understanding is correct. </task>
Makes Cascade read and confirm real project context before proposing a solution.
Pro tip: Add the conventions to a Windsurf Rules file so Cascade follows them automatically on every task.
Self-Review Before Done
29/30<context> Just-completed change: [WHAT YOU BUILT] Stack: [YOUR CODEBASE/STACK] </context> <task> Review your own work critically before declaring it done. 1. Re-read your diff as if reviewing a teammate's PR. 2. Check for: unhandled errors, missing edge cases, leftover debug code, broken imports, untested paths. 3. Verify it builds and the relevant tests pass; run them. 4. List anything you are unsure about or that I should double-check. 5. Only then summarize what changed and why. </task>
Adds a critical self-review and verification pass before Cascade reports completion.
Pro tip: A forced self-review turn catches the leftover console.log and the unhandled error path almost every time.
Recover From a Wrong Turn
30/30<context> What went wrong: [WHAT CASCADE DID THAT YOU DIDN'T WANT] What I actually want: [CORRECT GOAL] Stack: [YOUR CODEBASE/STACK] </context> <task> Get us back on track without making it worse. 1. Summarize the current state of the code versus where we should be. 2. List exactly what needs to be undone or changed to reach the correct goal. 3. Make the corrections in small, reviewable steps. 4. Do not introduce new changes beyond the correction. 5. Confirm the codebase now matches the intended goal and builds cleanly. </task>
Steers Cascade back to the intended outcome with a clear, minimal correction plan.
Pro tip: Describe the desired end state, not just the mistake — Cascade corrects far more accurately with a target.
Frequently Asked Questions
Prompts are the starting line. Tutorials are the finish.
A growing library of 300+ hands-on tutorials on ChatGPT, Claude, Midjourney, and 50+ AI tools. New tutorials added every week.
7-day free trial. Cancel anytime.