Windsurf Rules Examples You Can Copy and Paste

# Project rules for Windsurf

## Role
You are a careful senior engineer working in this repository. Prefer small, correct changes over large, clever ones.

## Before you write code
- Read the files you are about to change. Do not guess at their contents.
- If a needed file, symbol, or config is not shown to you, say so and ask before assuming it exists.
- Match the existing style, folder layout, and naming already in this repo.

## When you write code
- Change only what the task asks for. Do not reformat or refactor unrelated lines.
- Keep functions small and named for what they do.
- Add or update comments only where the intent is not obvious from the code.
- Never invent library names, APIs, or file paths. If unsure, check package manifests first.

## After you write code
- Summarize what you changed and why, in 3 lines or less.
- List any commands the human should run (install, migrate, test).
- Call out anything you were unsure about instead of hiding it.

## Communication
- Be direct. No filler, no apologies, no marketing language.
- If the request is ambiguous, ask one focused question before generating code.

A safe default that works in any language. It stops the two most common failure modes: touching unrelated code and inventing APIs that do not exist.

# Git and commit rules

## Commits
- Use Conventional Commits: feat, fix, chore, docs, refactor, test, perf.
- One logical change per commit. Do not bundle unrelated edits.
- Subject line <= 72 characters, imperative mood, no trailing period.
- Explain the why in the body when the change is not obvious.

## Branches
- Never commit directly to main or master.
- Branch names: type/short-description, for example fix/login-redirect.

## Safety
- Never commit secrets, .env files, API keys, or credentials.
- Never run destructive Git commands (reset --hard, push --force, clean -fd) without explaining the effect first and getting confirmation.
- Do not rewrite published history.

## Pull requests
- PR description states what changed, why, and how it was tested.
- Keep PRs small enough to review in one sitting.

Keeps the AI from making messy or dangerous Git moves. Force-push and reset --hard are the edits developers most regret letting an agent run unsupervised.

# Security rules

## Secrets
- Never hardcode passwords, tokens, or keys in source. Read them from environment variables or a secrets manager.
- Never print, log, or echo secret values.
- If you find a committed secret, flag it and recommend rotation. Do not silently remove it.

## Input and data
- Treat all external input as untrusted. Validate and sanitize before use.
- Use parameterized queries. Never build SQL by string concatenation.
- Escape output rendered into HTML to prevent XSS.

## Dependencies
- Prefer the standard library before adding a dependency.
- Do not add a package without naming it and its purpose in your summary.
- Pin versions the way the rest of the project does.

## Auth
- Never weaken authentication or disable checks to make something pass.
- Do not log full request bodies that may contain personal data.

A short, universal security baseline. It catches the classic AI mistakes: hardcoded keys, string-built SQL, and quietly disabling a check to make a test go green.

# React / Next.js / TypeScript rules

## Stack
- Next.js App Router, React function components, TypeScript strict mode.
- Styling with Tailwind CSS. Do not introduce a second styling system.
- Package manager: match the lockfile in the repo (pnpm, npm, or yarn). Do not switch it.

## TypeScript
- No any. If a type is truly unknown use unknown and narrow it.
- Type props and return values explicitly on exported functions.
- Prefer type aliases for props, interfaces for public object shapes. Be consistent with the file.

## Components
- Function components with hooks only. No class components.
- Keep components small and single-purpose. Extract when a file passes ~150 lines.
- Server Components by default. Add "use client" only when the component needs state, effects, or browser APIs.
- Never call hooks conditionally or inside loops.

## Data and state
- Fetch in Server Components or route handlers where possible.
- Do not add a global state library unless the task calls for it. Prefer props and local state first.
- Handle loading and error states for every async view.

## Quality
- Every interactive element must be keyboard accessible and have an accessible label.
- Run type-check and lint mentally before finishing. Do not ship code that would fail tsc.
- Do not disable ESLint rules with inline comments to silence a warning. Fix the cause.

Encodes the decisions teams argue about most in Next.js: Server vs Client Components, strict typing, one styling system, and no any. It keeps generated code idiomatic for the App Router.

# Frontend testing rules

## Framework
- Use Vitest with React Testing Library. Match the setup already in the repo.
- Test files live next to the code as name.test.ts or name.test.tsx.

## What to test
- Test behavior a user can observe, not implementation details.
- Query by role and accessible name, not by test id, unless there is no other option.
- Cover the happy path plus at least one error or empty state.

## Rules
- Do not delete or weaken an existing test to make a new change pass. Fix the code instead.
- No snapshot tests for large trees. They hide real regressions.
- Mock network calls at the boundary (fetch or the API client), not deep internals.
- Every new exported function or component gets at least one test.

## When done
- State which tests you added and what they cover.
- If you could not test something, say why.

Testing is where AIs cheat most, by deleting a failing assertion or writing snapshot tests that assert nothing. This block forbids both and pushes toward user-facing behavior tests.

# Performance and accessibility rules

## Performance
- Do not import a whole library for one function. Import the single export or use a lighter option.
- Use next/image for images and next/font for fonts.
- Memoize only when there is a measured need. Do not sprinkle useMemo and useCallback everywhere.
- Avoid client-side data fetching waterfalls. Fetch in parallel or on the server.

## Accessibility
- Every image has meaningful alt text, or alt="" if purely decorative.
- Form inputs have associated labels. Buttons have discernible text.
- Color is never the only way information is conveyed.
- Maintain visible focus states. Do not remove outlines without a replacement.
- Respect prefers-reduced-motion for animations.

## Rule
- If a change could hurt Core Web Vitals or accessibility, mention it in your summary.

Two things AI code silently drops: bundle size and accessibility. This turns them into explicit, checkable rules instead of afterthoughts.

# Python rules

## Environment
- Target Python 3.11 or newer. Match the version in pyproject.toml.
- Use the project's tool set: ruff for lint and format, mypy for types, pytest for tests. Do not introduce black if ruff format is in use.
- Manage dependencies through the existing tool (uv, poetry, or pip). Do not switch it.

## Style
- Follow PEP 8 as enforced by ruff. Do not hand-format against the formatter.
- Type-annotate all function signatures. Use built-in generics (list, dict) not typing.List.
- Prefer pathlib over os.path. Prefer f-strings over percent or format.
- Use dataclasses or pydantic models for structured data, not bare dicts passed around.

## Structure
- Keep functions short and pure where possible. Push side effects to the edges.
- Raise specific exceptions, not bare Exception. Never use a bare except.
- Use logging, not print, for anything beyond a quick script.
- Guard scripts with if __name__ == "__main__".

## Dependencies
- Prefer the standard library first.
- Do not add a package without naming it and why in your summary.

## Done means
- Code passes ruff and mypy cleanly.
- Public functions have a one-line docstring stating what they do.

A modern Python baseline: typed signatures, ruff and mypy clean, pathlib over os.path, specific exceptions. It stops the AI from mixing formatters or reaching for a dependency it does not need.

# Python testing rules

## Framework
- Use pytest. Tests live in tests/ mirroring the package layout.
- Name tests test_<behavior>, one clear assertion focus per test.

## What to test
- Arrange, act, assert. Keep each test readable top to bottom.
- Use fixtures for shared setup. Use parametrize for the same logic over many inputs.
- Cover the happy path, a boundary case, and at least one failure case.

## Rules
- Do not modify or delete an existing test to make new code pass. Fix the code.
- Do not assert on internal calls when you can assert on the returned value or observable effect.
- Mock external systems (network, filesystem, clock) at their boundary. Keep pure logic unmocked.
- No test may depend on another test's order or leftover state.

## When done
- List the tests you added and what each verifies.
- Report anything left untested and why.

Gives pytest structure the AI can follow: fixtures, parametrize, boundary and failure cases, and a hard ban on editing existing tests to fake a pass.

# FastAPI service rules

## API
- Define request and response models with pydantic. Never accept or return raw dicts on public routes.
- Validate all input at the boundary. Return proper HTTP status codes, not 200 with an error body.
- Keep route handlers thin. Put business logic in service functions that are unit-testable without HTTP.

## Database
- Use parameterized queries or the ORM. Never build SQL with f-strings or concatenation.
- Wrap multi-step writes in a transaction. Roll back on failure.
- Do not run migrations automatically. Generate the migration and let the human apply it.

## Errors and logging
- Catch specific exceptions. Return a clear error shape to the client without leaking internals or stack traces.
- Log with context (request id, operation) using the logging module. Never log secrets or full payloads with personal data.

## Async
- Do not call blocking IO inside async handlers. Use async clients or run blocking work in a thread pool.

## Done means
- New endpoints have request and response models, an error path, and at least one test hitting the route.

Targets the sharp edges of Python web services: SQL injection, blocking calls in async handlers, auto-running migrations, and leaking stack traces to clients.

# Accuracy and verification rules

## Do not invent
- Never invent file paths, function names, imports, config keys, env variables, or API endpoints.
- If you have not seen a file's contents in this session, open and read it before referencing it. Do not guess.
- If a library method might not exist, say you are unsure and how to confirm it, instead of stating it as fact.

## Ground every claim
- When you say a function, type, or field exists, it must come from a file you actually read, not from memory.
- Quote or point to the exact file and symbol you are relying on.
- If the codebase and your assumption disagree, trust the codebase.

## When unsure
- Prefer "I do not know yet, here is how to find out" over a confident guess.
- Ask one focused question rather than generating code on a shaky assumption.
- Mark any assumption you had to make with a clear ASSUMPTION note in your summary.

## No silent failure hiding
- Do not add empty catch blocks, blanket try/except, or // eslint-disable just to make errors disappear.
- Do not weaken or delete a test, type, or check to force a green result. Fix the real cause.

The core anti-hallucination block. It forces the AI to read files before referencing them and to say 'I do not know' instead of confidently inventing a method that does not exist.

# Self-check before finishing

Before you say a task is done, walk this checklist and report the result of each item:

1. Requirements: does every part of the request have a corresponding change? List each requirement and where it was handled.
2. Reality: does every symbol, import, and path you used actually exist in the repo? Confirm you read them.
3. Scope: did you change only what was asked? Revert any unrelated edits.
4. Errors: does the code handle the failure and empty cases, not just the happy path?
5. Build: would this pass the project's type-check, lint, and existing tests? If not, fix it before finishing.
6. Commands: list the exact commands the human should run to verify (install, test, run).

If any item fails, fix it and re-check. Only then report the change as complete.
Do not claim something was tested or verified unless you actually ran it. If you could not run it, say so plainly.

Turns 'done' into a checklist instead of a vibe. The last line is the key one: it bans the AI from claiming it tested code it never ran.

# Plan before large changes

## When to plan
- For any task touching more than 3 files, adding a dependency, changing a public API, or altering data models, write a short plan first and wait for a yes before editing.
- The plan lists: the files you will change, the approach, and any risk or open question.

## Small tasks
- For a one-file, low-risk change, just do it and summarize. Do not turn a quick fix into 10 questions.

## Ambiguity
- If the request could be read two ways, state the two readings and ask which one, in a single question.
- State one assumption clearly rather than generating several wrong directions.

## Irreversible actions
- Before any destructive or hard-to-undo step (deleting files, dropping tables, force-push, mass rename), explain the effect and get explicit confirmation.
- Never disable safety checks, auth, or validation to make progress. Surface the blocker instead.

Balances autonomy and safety. It makes the AI plan before big or irreversible moves, but explicitly tells it not to interrogate you over a trivial one-line fix.