A concise AGENTS.md template for AI agents working on Python 3.10+ FastAPI backend services, covering essential rules for safe testing, code style, database access, and Kafka event handling in production-oriented environments.

AGENTS.md

AGENTS.md

Mandatory technical reference for AI agents. Focus on commands and imperative rules. For engineering principles and architecture, see CONTRIBUTING.md.

---

1. Project Context

• Type: Backend API (FastAPI v0.127)
• Stack: Python 3.10, PostgreSQL, SQLAlchemy (Sync), uv
• Testing: pytest (Isolate via make test-unit)
• Quality: pre-commit, Ruff (via make cs)

---

2. Critical Safety Rules

• Testing: NEVER run pytest directly. ALWAYS use make test-unit.
• Production: Assume any DB access is production. No destructive operations without explicit approval.
• Dependencies: Use uv add <package>. No global installs.

---

3. Database & ORM

Imperative Rules:

• Sessions: Always use SessionLocal() in a context manager.
• Cleanup: Ensure sessions are closed (handled by context manager).
• Queries: Prefer select() over deprecated ORM patterns.

Etalon Example (DB Session):

from app.orm.database import SessionLocal
from sqlalchemy import select
from app.orm.models import Task

def get_tasks():
    with SessionLocal() as session:
        query = select(Task).where(Task.status == "pending")
        return session.execute(query).scalars().all()

Reference: app/services/tasks/initializer.py:_check_cleanup_tasks

---

4. API & Error Handling

Imperative Rules:

• Exceptions: Use ApiException (or its subclasses) from app.api.errors.
• Validation: Rely on Pydantic models for request/response.
• Logic: Keep business logic in services, not routers.

Etalon Example (Error Handling):

from app.api.errors import ApiException
from fastapi import status

def validate_data(data: dict):
    if "important_key" not in data:
        raise ApiException(
            status_code=status.HTTP_400_BAD_REQUEST,
            error_code="MISSING_DATA",
            message="Required key is missing"
        )

Reference: app/api/errors.py

---

5. Development Workflow

Imperative Rules:

1. Test Database Availability: Tests MAY fail if the test database does not exist. This can happen if the database container was fully removed. IF tests fail due to missing test database, the agent MUST recreate it by running: make test-setup. After that, the agent MUST rerun: make test-unit
2. Implement: Focused, minimal changes.
3. Test: make test-unit (Mandatory).
4. Lint: make cs AND pre-commit run --all-files (Mandatory).
5. Docs: Update docstrings if logic changes.