Menu
FastAPI best practices and conventions. Use when writing or refactoring FastAPI endpoints, routers, dependencies, or Pydantic models.
Audit and update Claude memory files after PRs or architecture changes. Use after merging PRs, deleting files, or changing architecture.
GraphRAG implementation patterns for hybrid search, Text2Cypher, and agentic retrieval. Use when implementing RAG workflows with Neo4j.
| name | fastapi-conventions |
| description | FastAPI best practices and conventions. Use when writing or refactoring FastAPI endpoints, routers, dependencies, or Pydantic models. |
| allowed-tools | Read, Grep, Glob, Edit, Write |
Official FastAPI best practices sourced from the bundled Agent Skill at:
backend/.venv/lib/python3.13/site-packages/fastapi/.agents/skills/fastapi/SKILL.md
When this skill is invoked, read that file for the full canonical reference. Below is a project-specific summary tailored to this codebase.
Always use Annotated for parameter and dependency declarations:
from typing import Annotated
from fastapi import Depends, Query
# Parameters
async def read_item(q: Annotated[str | None, Query(max_length=50)] = None): ...
# Dependencies — create reusable type aliases
CurrentUserDep = Annotated[dict, Depends(get_current_user)]
Never use the default-value style (q: str = Query(...)) — it breaks function signatures in other contexts.
Every endpoint MUST have a typed return. This project already enforces this (all 15 endpoints have response_model).
response_model= on the decorator when filtering fields (e.g., hiding internal data)# Preferred — return type annotation
@app.get("/items/")
async def get_item() -> Item: ...
# When filtering — response_model on decorator
@app.get("/items/", response_model=PublicItem)
async def get_item() -> Any: ...
Set prefix, tags, and dependencies on APIRouter(), not in include_router():
router = APIRouter(prefix="/items", tags=["items"], dependencies=[Depends(auth)])
app.include_router(router) # Clean — no config duplication
async def only when all internal calls are await-compatibledef when calling blocking code or when in doubt (runs in threadpool)async def — damages event loop performanceThis project's endpoints are async def because they call async Neo4j driver and LangChain operations.
ORJSONResponse / UJSONResponse — deprecated since 0.131.0, use standard JSONResponse...) as default for required fields — just omit the defaultRootModel — use Annotated with Field insteadapi_route() with multiple methods — one HTTP operation per functionDepends() — prefer function dependencies returning instancesFastAPI now validates Content-Type: application/json on JSON requests by default.
Disable per-app with FastAPI(strict_content_type=False) if needed.
This project already follows the recommended stack: uv, ruff, ty.