40 Best Windsurf AI Prompts (2026)

Using @codebase, give me a map of this repository. Cover: the tech stack and framework versions, the main entry points, how the app boots, the folder structure and what each top-level directory is for, how data flows from request to response, and the build/test/run commands. Then list the 5 files I should read first to become productive. Do not edit anything yet.

[Switch Cascade to Chat/Ask mode.] Without editing any files, explain how authentication works in this app. Trace it from the login route through @codebase: where sessions or tokens are created, where they are validated on each request, and where the user identity is attached. Cite the exact file paths and functions involved.

Explain @file:[path/to/file] in plain language. Walk through it top to bottom: what each function does, the inputs and outputs, any side effects, and the non-obvious edge cases it handles. Point out anything that looks fragile or surprising. Do not change the file.

Analyze @codebase and draft rule files for .windsurf/rules/. Create: (1) a short always-on rule (trigger: Always On) that states the stack, the golden path for adding a feature, and "follow the matching glob rules"; (2) a glob rule for [src/**/*.ts] with our naming, import, and error-handling conventions; (3) a glob rule for [**/*.test.ts] with our testing conventions. Infer conventions from the existing code, keep each file short, and use Markdown with trigger frontmatter. Show me the files before writing them.

Create a memory: In this workspace we use [pnpm], [Vitest] for tests, [Zod] for validation, and colocate tests next to source as *.test.ts. Prefer named exports. Never edit files under [/generated]. Keep this short so it loads every session.

Build [feature name]. Spec: [1-3 sentence description]. Acceptance criteria:
- [criterion 1]
- [criterion 2]
- [criterion 3]
Use @codebase to match existing patterns. Plan the change first and list the files you will touch, then implement it. Write tests for the acceptance criteria and run them. Done when the new tests and the full suite pass. Do not modify anything outside the feature.

Scaffold a new [React] component [ComponentName] in @folder:[src/components] and a matching [POST] endpoint at [/api/resource]. Follow the structure of an existing example: @file:[src/components/Example.tsx] and @file:[src/api/example.ts]. Include the types, a loading and error state on the client, and input validation on the server. Wire the component to call the endpoint. Run the type check when done.

Build a [settings page] that matches this: [paste screenshot or describe the layout, sections, and controls]. Use our existing design system components from @folder:[src/ui] rather than raw HTML, match the spacing and typography already used in @file:[src/pages/Profile.tsx], and make it responsive. Keep it a presentational component with props for the data. Do not add new dependencies.

Using @docs:[library or API name], add a client call to [the X endpoint] in @file:[path]. Follow the documented request shape and auth. Handle non-200 responses, timeouts, and retries per the docs, and type the response. Add one test that mocks the network. If the docs are ambiguous, ask before guessing.

Add a [signup] form to @file:[path] with fields [email, password, name]. Validate on the client and server with [Zod], show inline field errors, disable submit while pending, and surface a top-level error on failure. Match the validation pattern in @file:[src/forms/Example.tsx]. Write tests for valid and invalid submissions and run them.

Design a schema for [feature: e.g. comments with threading]. Review our existing schema in @file:[path to schema/migrations] first so you match conventions (naming, IDs, timestamps, soft deletes). Propose the tables, columns, indexes, and foreign keys, plus a migration file. Then write the query for [the main access pattern] and explain its index usage. Show the plan before creating files.

Before you write any code, produce a plan for [task]. Use @codebase to ground it. List the files you will create or change, the order of steps, the risks, and how you will verify each step (which tests or commands). Wait for my approval before editing.

Implement the approved plan end-to-end in Write mode. Make the edits, run [npm test] and [the type check] after each meaningful step, and fix anything that breaks before moving on. Stop and ask me only if a decision changes the public API or adds a dependency. Report the final diff summary and test results.

Make this change, but only edit files under @folder:[src/feature-x]. Do not modify anything outside that folder, do not touch config, lockfiles, or unrelated files, and do not reformat lines you are not changing. If the change requires touching another path, stop and explain why instead of doing it.

Run [npm test]. Read the @terminal output, fix the failures one at a time, and re-run after each fix. Keep iterating until the suite is green. Do not change test expectations to make them pass unless a test is genuinely wrong; if so, explain why. Summarize what you changed.

Create a workflow file at .windsurf/workflows/[ship-feature].md that I can invoke as /[ship-feature]. Steps: (1) run the linter and fix issues, (2) run the full test suite, (3) run the type check, (4) generate a conventional-commit message from @git, (5) draft a PR description. Write each step as a clear instruction to Cascade. Show me the file before saving.

Look at @terminal. Diagnose the error: what is the root cause, not just the symptom? Trace it to the exact file and line using @codebase, explain why it happens, and propose the smallest fix. Do not change code yet, just give me the diagnosis and the plan.

Bug: [describe the behavior and how to trigger it]. First, write a failing test that reproduces it, and run it to confirm it fails for the right reason. Do not fix anything until we have a red test. Show me the test and the failure output.

Symptom: [what the user sees]. Using @codebase, trace the data from where it enters the system to where the wrong result appears. List every function it passes through with the file and line, and pinpoint where the value first becomes incorrect. Explain the mechanism before proposing a fix.

The test [test name] in @file:[path] is failing. Run it, read the @terminal output, and decide whether the bug is in the code or the test. Fix the correct side, keep the change minimal, and re-run to confirm green. Do not weaken the assertion just to pass.

The build is failing with the type errors in @terminal. Fix them properly by correcting the types and any real mismatches, not by adding [any] or [@ts-ignore]. If a type genuinely needs to change, update it at the source. Re-run the type check until it is clean and summarize the changes.

Refactor @file:[path] for readability with zero behavior change. Improve naming, structure, and control flow; remove dead code. Run the existing tests before and after to prove behavior is unchanged. If there is no coverage, write a couple of characterization tests first. Do not change the public interface.

The function [name] in @file:[path] is too long. Extract cohesive steps into well-named helper functions, keep the public signature identical, and add short doc comments to each new helper. Run the tests to confirm nothing changed. Only edit this file.

Use @codebase to find code duplicated with @file:[path] (the [validation/formatting] logic). List the duplicates with file paths, then propose a single shared helper and where it should live. After I approve, replace the duplicates with the helper and run the tests. Do not over-abstract cases that only look similar.

Add precise types to @file:[path], which is currently [untyped/loosely typed]. Infer types from usage across @codebase, avoid [any], and add a shared type or interface where the same shape recurs. Run the type check and fix real mismatches the new types reveal. Do not change runtime behavior.

Migrate this project from [library]@[old version] to [new version]. Use @docs:[library] and its migration guide for the breaking changes. Find every usage with @codebase, update them, update the dependency, and run the tests and type check. Do it in reviewable steps and pause if a breaking change needs a decision.

Write unit tests for @file:[path] using [our test framework]. Cover the happy path, edge cases, and error conditions, and match the style in @file:[an existing test file]. Run the tests and iterate until they pass and genuinely exercise the logic. No trivial tests that only assert the function exists.

Run the test suite with coverage. Read the @terminal report and, for @folder:[src/feature], list the most important untested branches and edge cases ranked by risk. Then write tests for the top [3] and run them. Focus on logic that would cause real bugs, not line-count padding.

Write an integration test for [the flow: e.g. create-order end to end]. Exercise the real path through @file:[the relevant modules] with the database/services [mocked/using a test instance] as we do in @file:[existing integration test]. Assert the observable outcome and side effects. Run it and fix any wiring issues.

Create reusable test fixtures and mocks for [entity: e.g. User, Order] matching the real types in @file:[types path]. Include a factory that lets me override fields, plus valid and invalid sample records for edge cases. Put them in @folder:[test/fixtures] following the pattern already there. Add no production dependencies.

The tests in @file:[path] repeat the same shape with different inputs. Convert them to a single parametrized/table-driven test with a clear case name per row, covering the existing inputs plus [these missing cases]. Keep coverage equal or better and run them to confirm they pass.

Review my staged changes in @git as a skeptical staff engineer. Flag correctness bugs, edge cases, race conditions, missing error handling, and anything that breaks our conventions in .windsurf/rules. Group findings by severity, cite the file and line, and suggest a concrete fix for each. Do not edit yet, just review.

Do a security review of the diff in @git. Check for injection, missing authz checks, unsafe input handling, secrets in code, unsafe deserialization, and dependency risks. For each issue give the file, line, the exploit scenario, and the fix. Rank by severity. Report only, no edits.

Update the README for [feature/module] based on @file:[the actual code]. Cover what it does, setup, usage with a short runnable example, config options, and gotchas. Keep it accurate to the current code, not aspirational. Fix any existing sections that are now out of date.

Write a Conventional Commits message for the staged changes in @git. One concise subject line under 72 chars, then a body explaining what changed and why (not how). Note any breaking changes with a BREAKING CHANGE footer. Output only the commit message.

Using the diff in @git, draft a pull request description with: a one-paragraph summary, a bullet list of changes, how it was tested, screenshots placeholders if UI changed, and any risks or follow-ups. Reference [ticket ID] if given. Keep it scannable for a reviewer.

I have merge conflicts in @file:[path]. Look at @git for both sides, explain what each branch was trying to do, and resolve the conflict so both intents are preserved. Do not silently drop either side's changes. After resolving, run the tests to confirm nothing broke and summarize your resolution.

Add structured logging and error handling to @file:[path], matching our logger and error patterns in @file:[example]. Log at the right levels, include useful context, wrap external calls with clear error messages, and never swallow errors silently. Do not add logging so noisy it drowns signal. Run the tests after.

Investigate the slow [operation] in @file:[path]. Using @codebase, identify likely bottlenecks (N+1 queries, unnecessary loops, repeated work, missing memoization/indexes). Explain the impact of each, propose the highest-value fix first, and implement it only after I approve. Add a benchmark or test that shows the improvement.

Create a workflow at .windsurf/workflows/[release].md invoked as /[release]. Steps: run tests and type check, bump the version, update the CHANGELOG from @git since the last tag, build the project, and print the git commands to tag and push. Write each step as an instruction to Cascade and pause before any irreversible action. Show me the file before saving.