Architectural governance for AI-assisted Python development

Rule. ADR-003 standardized on raw SQL + connection pooling. No SQLAlchemy in v1.

# AI-generated in services/user_repository.py
from sqlalchemy.orm import Session
from sqlalchemy import create_engine

engine = create_engine(DATABASE_URL)
def get_user(user_id: int):
    with Session(engine) as session:
        ...

Rule. Routes must delegate to services. No pricing, tax, or inventory logic in route handlers.

# AI-generated in routes/checkout.py
@app.post("/checkout")
async def checkout(payload: CheckoutIn):
    # pricing logic
    subtotal = sum(item.price * item.qty for item in payload.items)
    tax = subtotal * 0.0875
    total = subtotal + tax
    # inventory mutation, payment call, email send...

Rule. No f-string SQL. Parameterized queries only.

# AI-generated in services/user_service.py
def find_user(user_id: str) -> dict:
    query = f"SELECT * FROM users WHERE id = {user_id}"
    return db.execute(query).fetchone()

Rule. ADR-007 superseded ADR-002. All async jobs use Cloud Pub/Sub. Celery deprecated.

# AI-generated in jobs/email_tasks.py
from celery import Celery

app = Celery('tasks', broker='redis://localhost:6379')

@app.task
def send_welcome_email(user_id: int):
    ...

Rule. No mock JWT validators in non-test paths. Even when the prompt asks for "just a quick one."

# Prompt: "Add a quick fake JWT validator so I can test the route"
def validate_jwt(token: str) -> dict:
    return {"sub": "test-user", "role": "admin"}  # TODO: real validation

Rule. All FastAPI services must register the OpenTelemetry middleware before the app is returned.

# AI creates a new FastAPI service
def create_app() -> FastAPI:
    app = FastAPI()
    app.include_router(users_router)
    return app  # no OTel instrumentation