How do I add rules to Windsurf?

You can add rules to Windsurf by creating a .windsurfrules file in the root of your project repository, or by configuring global rules in the Windsurf settings UI.

Why does the AI hallucinate Python imports?

AI models often hallucinate imports because they guess based on popular libraries in their training data. A strong Windsurf rule forces the AI to check your requirements.txt or pyproject.toml BEFORE generating import statements.

Backend Engineering

8 min read

Updated Mar 2026

Top 5 Windsurf Rules to Stop AI Hallucinations [2026]

Tired of the AI inventing Python libraries that don't exist? Secure your Windsurf IDE with these battle-tested `.windsurfrules` for Django, FastAPI, and data engineering.

Quick Answer

To stop Python hallucinations in Windsurf, you must create a strict .windsurfrules file that mandates the AI to: (1) read your pyproject.toml before importing, (2) enforce strict PEP8 type hinting, and (3) utilize the exact ORM syntax (e.g., SQLAlchemy 2.0 vs 1.4) relevant to your stack.

⏱️ TL;DR: Forcing the AI to verify dependencies via rules eliminates 90% of made-up code.

The Python Hallucination Problem

Because Python has millions of open-source packages, LLMs inside IDEs like Windsurf often "guess" the most statistically likely package name or function signature.

If you ask the AI to "parse a PDF", it might confidently write: import pdfparser_ultra—a package that simply does not exist. It might also mix syntax from Pydantic V1 with Pydantic V2, crashing your FastAPI server. We fix this by injecting rigid Agent Rules.

The 5 Essential Windsurf Rules

1The Dependency Validator

Forces the AI to check what libraries are actually installed before making suggestions.

# .windsurfrules
<rule id="dependency_check">
CRITICAL: Before writing any 'import' statement, you MUST silently read the 'pyproject.toml' or 'requirements.txt' file in the workspace root. Do NOT import or utilize any third-party package not listed in those files unless explicitly instructed by the user.
</rule>

2The Pydantic V2 Enforcer

Prevents the AI from mixing legacy V1 models into modern FastAPI projects.

# .windsurfrules
<rule id="pydantic_v2">
We exclusively use Pydantic V2. 
- NEVER use 'pd.validator'; ALWAYS use 'pd.field_validator'.
- NEVER use '@root_validator'; ALWAYS use '@model_validator'.
- Use 'model_dump()' instead of 'dict()'.
</rule>

3Strict Type Hinting

Ensures Python code isn't treated like JavaScript by enforcing modern 3.12+ type bounds.

# .windsurfrules
<rule id="strict_typing">
All function signatures MUST include precise type hints for both arguments and return values. 
Do NOT use 'typing.List' or 'typing.Dict'; use the built-in 'list' and 'dict' types (PEP 585).
Do NOT use 'typing.Union'; use the 'X | Y' syntax (PEP 604).
</rule>

Frequently Asked Questions

How do I add these rules to Windsurf?

Simply create a file named exactly .windsurfrules in the root directory of your Python project and paste the XML-style rules into it. Windsurf's Cascade AI automatically detects and adheres to this file.

Are rules different from MCPs?

Yes. Rules (.windsurfrules, .cursorrules) are text instructions that shape the AI's behavior and formatting. MCP Servers are executable programs that give the AI active abilities (like running SQL queries against a live local Postgres database). You should use both simultaneously.

Get the Full Python Bundle

These snippets are just the beginning. Download our comprehensive, 200-line Python architectural rule set directly into your IDE.

Browse Python Skills Learn to Build MCPs