Python FastAPI & Pydantic v2 Windsurf Cascade Rules

Production-grade architectural rulebook for Python FastAPI & Pydantic v2. Engineered to eliminate LLM hallucinations, enforce strict deterministic conventions, and prevent architectural drift across Cursor IDE, Claude Code CLI, and autonomous multi-agent pipelines.

Target Path

.windsurf/rules/fastapi.md

Execution Scope

Project Context

Specification Format

Markdown / Config

AI Tool Support

Universal AI Assistants

02 / DRIFT ANALYSIS & VALUE PROPOSITION

Failure Patterns Prevented for Python FastAPI & Pydantic v2

Without This Rule (Default LLM Behavior)Vulnerable

FastAPI with Pydantic v2 requires `model_validator` instead of `@root_validator`, Field annotations, and strict async I/O. Without rules, AI models blend outdated Pydantic v1 syntax and synchronous database calls inside async handlers.

Hallucination Symptoms

Invokes deprecated or removed APIs from older model training weights
Generates conflicting configuration files and invalid imports
Silently drops type-safety, boundaries, or transaction isolation

With This Rule (Guaranteed Invariants)Deterministic

Use strict Pydantic v2 BaseModels with Field validation for all input and output schemas.

Use asynchronous route handlers (`async def`) for database operations and external API requests.

Inject dependencies using FastAPI `Depends` pattern; avoid global state.

Type annotate 100% of function signatures with Python 3.12+ type hints.

03 / VERIFIED CODE PATTERNS

Code Standards: Anti-Pattern vs Verified Implementation

Discouraged Anti-Pattern

@app.post("/users")
def make_user(data: dict):
    # Missing types, sync blocking query
    return db.query(data["email"])

Verified Production Standard

from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field

router = APIRouter()

class UserPayload(BaseModel):
    email: str = Field(..., min_length=5)

@router.post("/users")
async def create_user(payload: UserPayload, db = Depends(get_db)):
    return await db.users.create(payload.model_dump())

04 / REPOSITORY PLACEMENT & 3-STEP TERMINAL INSTALLATION

How to Install Python FastAPI & Pydantic v2 Windsurf Cascade Rules via Terminal

Step 1: Open Project Directory & Verify Target Placement

Open your terminal and navigate to your project root folder where the .windsurf/rules/fastapi.md file will reside. Ensure the file is placed at the exact path below relative to your project root so the AI engine automatically loads it:

.windsurf/rules/fastapi.md

Step 2: Fetch Rule File via Terminal Command

Run curl, PowerShell, or wget to stream the rule directly from the DevScratchpad raw API endpoint and write it to .windsurf/rules/fastapi.md:

Terminal One-Liner Install

Run directly in your project root to stream and write this rule file with one command.

Raw API Stream

mkdir -p ".windsurf/rules" && curl -fsSL "https://www.devscratchpad.tech/api/raw/windsurf-rules/fastapi" -o ".windsurf/rules/fastapi.md"

Step 3: Verify and Activate with AI Agent

Launch your AI coding assistant (Universal AI Assistants). The assistant will automatically discover .windsurf/rules/fastapi.md in your repository and apply the architectural guardrails, type constraints, and verification protocols during code generation.

05 / ROUTE DIRECTORY & CROSS-TOOLING

Alternative AI Formats for Python FastAPI & Pydantic v2Cross-Tooling

/ai-skill-studio/claude-skills/fastapiFastAPI Claude Skill

→

/ai-skill-studio/claude-md/fastapiFastAPI CLAUDE.md

→

/ai-skill-studio/agents-md/fastapiFastAPI AGENTS.md

→

Related Windsurf Cascade Rules PresetsSame Directory

Frontend

Next.js 15 App Router

→