ai-agents-workspace-starter: Skill for Claude Code

Skill: Backend Patterns

Core guidelines and fundamental rules for implementing backend functionality in Python.

1. Architecture and Layers (Hexagonal)

• Domain: Contains entities (Pydantic/Dataclasses) independent of FastAPI/SQLAlchemy and Port definitions (interfaces via ABC).
• Application (Services): Contains the business logic (Use Cases). Services accept repositories (Ports) via Dependency Injection (DI). Ignorant of HTTP or the database.
• Infrastructure (Adapters): Repository implementations using SQLAlchemy, 3rd party API clients, background workers.
• Interfaces (API/Web): FastAPI routers. Always lightweight, devoid of business logic; they only decode requests and return HTTP responses.

Layer Prohibitions

2. API and FastAPI Routers

• Inject services using FastAPI's Depends().
• A router endpoint should invoke exactly ONE service method.
• Use explicit Pydantic models for requests (*Create, *Update) and responses (*Response). Always define response_model in the decorator.
• Use appropriate status codes (e.g., 201 CREATED for POST, 204 NO CONTENT for DELETE).
• Endpoint method: max 10-15 lines (ideal), 25 lines (absolute max). If longer, extract logic to service.
• One router per resource/domain (e.g., users.py, orders.py). Router file max 200 lines.
• NEVER use request.json() directly - always Pydantic schema as parameter.
• NEVER create service instances in endpoint - use Dependency Injection.
• NEVER use try/except in endpoints - use centralized exception handlers.