Przepisy na Python

Przepisy na backend w Pythonie dla agentów AI to prompty i bramki weryfikacyjne, dzięki którym Claude Code, Codex i Cursor tworzą produkcyjne usługi FastAPI i Django: walidowaną konfigurację, schematy Pydantic v2, asynchroniczne SQLAlchemy 2.1 odporne na współbieżność, idempotentne zadania Celery, odporne klienty HTTP i logi z redakcją sekretów. Kod przyjmujesz na podstawie wyników bramek, a nie lektury linijka po linijce.

Twoja usługa FastAPI przechodzi wszystkie testy napisane przez agenta. Potem pierwszy test obciążeniowy zamraża pętlę zdarzeń, bo handler wywołuje requests.get(), zapytanie asynchroniczne rzuca MissingGreenlet na relacji, której nikt nie załadował, a ponowione zadanie Celery obciąża klienta dwa razy. Kod wyglądał idiomatycznie, a testy działały na SQLite z mockami, więc nie miały szansy niczego z tego wyłapać.

Ta strona jest dla programistów, którzy budują backendy w Pythonie z agentem i chcą przestać przeglądać każdy handler wzrokiem. Produkcyjne szczegóły trafiają do promptów, a dowód dostarcza maszyna.

Co dają ci te przepisy na Pythona

• Blok reguł AGENTS.md dla typowanego, asynchronicznego Pythona, którego przestrzegają wszystkie trzy narzędzia, oraz bramkę make check, którą agent uruchamia, zanim powie „gotowe”
• Osiem promptów do skopiowania: szkielet FastAPI z lifespanem i konfiguracją, walidacja Pydantic v2, asynchroniczne repozytorium SQLAlchemy, które nie sprzeda więcej, niż ma na stanie, idempotentne zadania Celery, klient httpx z timeoutami i ponowieniami, structlog z redakcją, API w Django REST Framework z izolacją tenantów oraz sprzątanie przestarzałych idiomów
• Tabelę weryfikacji, która mówi, która bramka łapie który błąd, więc czytasz wynik bramek zamiast diffa
• Kroki naprawcze dla siedmiu najczęstszych awarii Pythona napisanego przez agenta

Przygotuj konwencje Pythona i bramkę, którą agent musi przejść

Większość pracy wykonują dwa artefakty: plik reguł, który agent czyta przy każdym zadaniu, i jedno polecenie, które kończy się błędem, gdy kod nie jest gotowy. Przygotuj oba, zanim poprosisz o jakikolwiek kod.

1. Przypnij interpreter i narzędzia. Aktualną stabilną linią jest Python 3.14, a PEP 790 planuje wydanie Pythona 3.15.0 na 2026-10-01. Zostań przy 3.14, dopóki twoje zależności nie zadeklarują wsparcia dla 3.15. Z uv (terminal):

   uv python pin 3.14
   uv add fastapi "pydantic-settings" "sqlalchemy[postgresql-asyncpg]" alembic structlog httpx
   uv add --dev pytest pytest-asyncio pytest-cov "testcontainers[postgres]" respx ruff mypy

   Aktualne wydania na PyPI 2026-09-26: fastapi 0.141.1, pydantic 2.13.5, pydantic-settings 2.15.0, sqlalchemy 2.1.1, alembic 1.20.0, pytest 9.1.1, pytest-asyncio 1.4.0, ruff 0.16.9, mypy 2.3.1, testcontainers 4.15.0, celery 5.6.3, django 6.1.1. Dodatek [postgresql-asyncpg] ma znaczenie: SQLAlchemy 2.1 nie instaluje już domyślnie greenlet, a rozszerzenie asynchroniczne bez niego nie działa.

2. Skonfiguruj narzędzia w pyproject.toml. Najwięcej łapią dwa ustawienia: reguły ASYNC wskazują blokujące wywołania wewnątrz async def, a filterwarnings = ["error"] zamienia każde ostrzeżenie o deprecjacji, w tym idiomy z Pydantic v1, w nieudany test.

   [tool.ruff]
   target-version = "py314"
   
   [tool.ruff.lint]
   select = ["E", "F", "I", "B", "UP", "ASYNC", "S", "RUF"]
   
   [tool.ruff.lint.per-file-ignores]
   "tests/**" = ["S101"]
   
   [tool.mypy]
   strict = true
   plugins = ["pydantic.mypy"]
   
   [tool.pytest.ini_options]
   asyncio_mode = "auto"
   asyncio_default_fixture_loop_scope = "function"
   filterwarnings = ["error"]

3. Dodaj bramkę. To definicja „gotowe” dla każdego promptu na tej stronie. W pliku Makefile (linie receptury zaczynają się od tabulatora):

   check:
     uv run ruff format --check .
     uv run ruff check .
     uv run mypy app
     uv run pytest --cov=app --cov-fail-under=80
     uv export --locked --no-dev --no-emit-project --format requirements.txt -o .audit.txt
     uvx pip-audit --disable-pip -r .audit.txt

   Dwie ostatnie linie audytują zablokowane zależności runtime bez ich instalowania. Dodaj .audit.txt do .gitignore.

4. Zapisz reguły Pythona w AGENTS.md w katalogu głównym repozytorium. Codex czyta AGENTS.md natywnie; zakładki niżej pokazują, jak ten sam tekst trafia do Claude Code i Cursora.

   ## Python conventions
   - Python 3.14, uv, fully typed. mypy --strict must pass; no bare `Any`,
     no `# type: ignore` without a reason in the same comment.
   - Pydantic v2 only: model_config = ConfigDict(...), @field_validator,
     @model_validator, model_dump(). Never class Config, @validator, or .dict().
   - Settings come from one pydantic-settings class in app/core/config.py.
     No os.getenv or os.environ anywhere else.
   - Inside async def: no requests, no time.sleep, no sync SQLAlchemy sessions,
     no blocking file I/O. Use httpx.AsyncClient, asyncio.sleep, AsyncSession.
   - SQLAlchemy 2.x style: select(), Mapped[], mapped_column(). Relationships
     use lazy="raise"; load them explicitly with selectinload().
   - Every outbound HTTP call has an explicit timeout.
   - Tests: pytest with pytest-asyncio in auto mode. Database tests use
     Testcontainers Postgres, not SQLite and not mocks.
   - Never edit an existing test assertion, add pytest.mark.skip or xfail, or
     loosen filterwarnings to make a test pass. If a test looks wrong, stop and
     say why.
   - Done means `make check` passes. Paste its last 20 lines in your final message.

Najważniejsze są dwie ostatnie reguły. Pierwsza nie pozwala agentowi osłabiać testów, żeby dojść do zielonego wyniku; strona chroń wyrocznię wyjaśnia, dlaczego to najczęstszy sposób, w jaki praca agenta udaje sukces. Druga zamienia „chyba działa” w dowód, który przeczytasz w dziesięć sekund.

Podłącz reguły i bramkę w każdym narzędziu

Reguły i prompty są identyczne we wszystkich narzędziach. Różni się to, jak każde narzędzie wczytuje reguły, formatuje zmiany i recenzuje wynik.

Claude Code

Claude Code czyta najpierw CLAUDE.md, więc utwórz plik, który importuje wspólne reguły. Składnia @path wstawia zawartość pliku do kontekstu przy starcie:

@AGENTS.md

Formatuj i automatycznie poprawiaj każdy plik Pythona edytowany przez agenta hookiem PostToolUse w .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -E '\\.py$' | xargs -r sh -c 'uv run ruff format \"$@\" && uv run ruff check --fix \"$@\"' _"
          }
        ]
      }
    ]
  }
}

Przejście do definicji i diagnostykę typów daje agentowi wtyczka pyright-lsp z oficjalnego marketplace’u Anthropic. Wtyczka rejestruje tylko serwer, więc najpierw zainstaluj Pyright (terminal):

uv tool install pyright
claude plugin install pyright-lsp@claude-plugins-official

Zanim otworzysz pull request, uruchom w sesji /code-review, żeby dostać drugą opinię o diffie.

Codex

Codex czyta AGENTS.md bezpośrednio, więc żaden dodatkowy plik nie jest potrzebny. Uruchom zadanie z zapisem w obszarze roboczym i pytaniem o zgodę na wszystko szersze (terminal):

codex -s workspace-write -a on-request "Implement POST /api/v1/orders as described in docs/tasks/orders.md. Done means make check passes."

Przed wypchnięciem zrecenzuj gałąź względem main:

codex review --base main

Cursor

Utwórz regułę projektu w ustawieniach Rules Cursora z tą samą listą, ograniczoną do plików *.py, żeby agent wczytywał ją przy każdej pracy z Pythonem. Przy wieloplikowych promptach z tej strony używaj Plan Mode, żeby zatwierdzić listę plików, zanim powstanie jakikolwiek kod. Niezależne przepisy uruchamiaj w Worktrees, a pull request daj do recenzji Bugbotowi.

Zacznij w każdym narzędziu od domyślnego modelu i najpierw zwiększ ustawienie effort, a dopiero potem zmień model; aktualne domyślne modele znajdziesz w hubie modeli.

Daj agentowi aktualną dokumentację bibliotek

Stos Pythona z tej strony zmienił się szybciej niż większość danych treningowych: FastAPI porzuciło wsparcie pydantic.v1 w wersji 0.128.0 (2025-12-27), pytest-asyncio 1.0 usunęło fixture event_loop, a SQLAlchemy 2.1 zmieniło sposób instalacji wsparcia async. Serwer MCP Context7 dostarcza agentowi dokumentację dla konkretnych wersji. Klucz API jest opcjonalny, więc wystarczy sam zdalny URL (terminal):

Claude Code

claude mcp add --transport http context7 https://mcp.context7.com/mcp

Codex

codex mcp add context7 --url https://mcp.context7.com/mcp

Cursor

Dodaj serwer o nazwie context7 z adresem https://mcp.context7.com/mcp w .cursor/mcp.json albo w ustawieniach MCP Cursora.

Potem zakończ prompt słowami „use context7 for SQLAlchemy 2.1 and pytest-asyncio 1.x”. Każdy serwer MCP dokłada do kontekstu definicje swoich narzędzi, więc podłączaj go w projektach, które go potrzebują, a nie globalnie.

Zbuduj produkcyjną usługę FastAPI z agentem, krok po kroku

Każdy krok to jeden prompt i sprawdzenie, które go dowodzi. Wykonuj je po kolei: późniejsze prompty zakładają, że szkielet, moduł konfiguracji i moduł bazy danych już istnieją.

Jak postawić usługę FastAPI, która czysto startuje i się zamyka?

Najczęstsze braki w pierwszym podejściu to walidacja przy starcie i zamykanie. Agent czyta zmienne środowiskowe tam, gdzie ich potrzebuje, i tworzy silnik bazy danych przy imporcie, więc brakująca zmienna wychodzi jako 500 przy pierwszym żądaniu, a silnik nigdy nie jest zwalniany.

Prompt do skopiowania: szkielet FastAPI z konfiguracją i lifespanem

Create a FastAPI service in app/ (Python 3.14, uv). app/core/config.py: a
pydantic-settings Settings class with DATABASE_URL (PostgresDsn), REDIS_URL,
SECRET_KEY (SecretStr, min 32 chars), ENV (Literal development/staging/production),
ALLOWED_ORIGINS (list[str]), and a get_settings() cached with functools.cache.
app/main.py: create_app() builds the app with a lifespan context manager that
creates the async engine and session factory on startup, stores them on
app.state, and awaits engine.dispose() on shutdown. No module-level engine and no
@app.on_event. Add GET /healthz (no DB) and GET /readyz (runs SELECT 1). Mount
routers under /api/v1. Exception handlers return
{"error": {"code": ..., "message": ...}} and never include a traceback when ENV is
production. Tests with httpx.AsyncClient(transport=ASGITransport(app=app)) inside
asgi_lifespan.LifespanManager: /readyz returns 200 against Testcontainers Postgres,
create_app() fails at startup with a message naming SECRET_KEY when it is missing,
and a production-mode 500 body contains no traceback. Done means make check passes.

Dobra odpowiedź ma taki rdzeń:

@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    settings = get_settings()
    engine = create_async_engine(str(settings.DATABASE_URL), pool_pre_ping=True)
    app.state.sessionmaker = async_sessionmaker(engine, expire_on_commit=False)
    yield
    await engine.dispose()

Sam ASGITransport nie uruchamia lifespanu, dlatego prompt wymienia LifespanManager (pakiet asgi-lifespan na PyPI). Bez niego testy mogą przechodzić, choć nigdy nie utworzyły silnika, który rzekomo sprawdzają.

Jak dostać walidację Pydantic v2, która precyzyjnie odrzuca złe dane?

Agenci wytrenowani na latach kodu z Pydantic v1 wciąż piszą class Config, @validator i .dict(). Ustawienie filterwarnings = ["error"] zamienia każdy z tych idiomów w nieudany test, bo Pydantic v2 emituje dla nich ostrzeżenie o deprecjacji.

Prompt do skopiowania: schematy Pydantic v2 z regułami między polami

In app/schemas/product.py create Pydantic v2 models. ProductCreate: name (2-200
chars, stripped), price (Decimal, gt 0, max 2 decimal places), compare_at_price
(Decimal | None, must be greater than price: use @model_validator(mode="after")),
category_id (UUID), tags (list[str], max 10 items, each 1-50 chars, deduplicated),
variants (list[VariantCreate], min 1). VariantCreate: sku matching ^[A-Z0-9-]+$,
size (StrEnum), stock (int, ge 0). ProductRead adds id, slug, created_at, and uses
model_config = ConfigDict(from_attributes=True). Page[T] is a generic paginated
response with items, total, page, page_size. Pydantic v2 APIs only. Tests: one
parametrized case per invalid field asserting the exact loc and type in
exc.errors(), the cross-field failure, and a round trip from an ORM object through
ProductRead.model_validate(). List the test cases before the code.

Asercje na loc i type zamiast na treści komunikatu sprawiają, że testy są stabilne między wydaniami Pydantic, a mimo to padają, gdy zniknie jakaś reguła.

Jak dostać asynchroniczne zapytania SQLAlchemy, które wytrzymają równoległe zamówienia?

Pierwsze podejście agenta do „sprawdź stan, potem zmniejsz” ładuje produkt, porównuje wartości w Pythonie i zapisuje wynik. Dwa równoległe zamówienia czytają stock = 1 i oba się udają. SQLite z jednym połączeniem nie pokaże tego błędu; pokaże go tylko Postgres z równoległymi sesjami.

Prompt do skopiowania: serwis zamówień, który nie sprzeda więcej, niż ma

Implement create_order(session, user_id, items: list[OrderItemIn]) in
app/services/orders.py with SQLAlchemy 2.1 async (Mapped[], mapped_column(),
select()). Relationships use lazy="raise". Inside one session.begin() block, for
each item execute update(Product).where(Product.id == item.product_id,
Product.stock >= item.quantity).values(stock=Product.stock - item.quantity)
.returning(Product.price) and raise OutOfStockError if no row comes back, so the
check and the decrement are one statement. Then insert the Order and OrderItems
with unit_price from the returned price, totals as Decimal. Generate the Alembic
migration with autogenerate and review it for server defaults and indexes.
Integration test with PostgresContainer from testcontainers.community.postgres
(driver="asyncpg"): run the migrations, set a product's stock to 1, run 10
create_order calls concurrently with asyncio.gather(return_exceptions=True), each
with its own session, and assert exactly one succeeds, nine raise
OutOfStockError, and stock is 0.

lazy="raise" zamienia klasyczny błąd async, czyli niejawne leniwe ładowanie, które na produkcji kończy się MissingGreenlet, w natychmiastowy błąd w pierwszym teście, który dotknie relacji. Liczy się też ścieżka importu: w testcontainers 4.15.0 stary moduł testcontainers.postgres emituje ostrzeżenie o deprecjacji, które twoje ustawienie filterwarnings zamienia w porażkę.

Żeby agent czytał prawdziwy schemat zamiast zgadywać nazwy kolumn, podłącz bazodanowy serwer MCP do deweloperskiej bazy przez rolę tylko do odczytu. Przewodnik po bazodanowych serwerach MCP porównuje serwery i ich przełączniki trybu tylko do odczytu. O bezpiecznych migracjach dużych tabel przeczytasz we wzorcach migracji baz danych.

Jak przenieść wolną pracę do Celery bez zdublowanych efektów ubocznych?

Ponowienia w Celery są bezpieczne tylko wtedy, gdy zadanie jest idempotentne. Przy acks_late awaria workera albo zadanie, które trwa dłużej niż visibility timeout brokera Redis, zostaje dostarczone ponownie, a drugie wykonanie powtarza każdy efekt uboczny.

Prompt do skopiowania: idempotentne zadanie Celery z testami na prawdziwym workerze

Move report generation out of the request into Celery 5.6 with a Redis broker.
app/worker/celery_app.py: JSON serializer only, task_acks_late=True,
task_reject_on_worker_lost=True, worker_prefetch_multiplier=1, soft time limit
300 s, hard limit 360 s. generate_report(report_id: str) takes only IDs, never ORM
objects. It claims the report row with UPDATE ... WHERE status = 'pending'
RETURNING id and exits quietly if no row comes back, so a redelivered task does
nothing. Retry on httpx.TransportError with autoretry_for, retry_backoff=True,
max_retries=5. POST /api/v1/reports returns 202 with the report id; GET
/api/v1/reports/{id} returns its status. Tests: add
pytest_plugins = ("celery.contrib.pytest",) to tests/conftest.py and use the
celery_app and celery_worker fixtures with a Testcontainers Redis. Assert a task
delivered twice produces one report, a task that fails twice then succeeds
completes, and passing a non-JSON-serializable argument fails in the test.

Agent zwykle pomija dwa szczegóły. celery.contrib.pytest nie rejestruje się jako wtyczka pytest automatycznie, więc jego fixture’y nie istnieją, dopóki conftest.py go nie wskaże. A task_always_eager uruchamia zadanie w procesie testu, więc nie pokaże ponownego dostarczenia przez broker ani utraty workera; tryb eager zostaw wyłącznie do testów jednostkowych samej treści zadania. W Django 6 wbudowany framework django.tasks definiuje i kolejkuje zadania, ale do ich wykonania w tle nadal potrzebny jest zewnętrzny backend z workerem; wbudowane backendy wykonują zadania tylko natychmiast albo je odrzucają.

Jak wołać zewnętrzne API bez zamrażania pętli zdarzeń?

Klienty pisane przez agenta psują się na trzy sposoby: synchroniczne wywołanie requests wewnątrz async def, brak timeoutu albo pętla ponowień, która w nieskończoność ponawia 400. Pierwszy przypadek łapią w bramce reguły ASYNC Ruffa; dwa pozostałe załatwia prompt.

Prompt do skopiowania: klient httpx z timeoutami, ponowieniami i testami respx

Create app/clients/base.py with a BaseClient wrapping one shared
httpx.AsyncClient created in the lifespan and closed on shutdown. Timeouts:
httpx.Timeout(10.0, connect=3.0). Retry with tenacity: up to 3 attempts,
exponential backoff with jitter, only on httpx.TransportError and 502/503/504,
never on other 4xx or on POST without an Idempotency-Key header. Raise typed
exceptions (UpstreamTimeout, UpstreamRejected with status and body excerpt) and
log each attempt with the upstream name and duration, never the request body.
Build PaymentsClient.create_refund(payment_id, amount) on it, sending an
Idempotency-Key. Tests with respx: a 503 then 200 succeeds on attempt 2, a 400 is
not retried, a POST without a key is not retried, a timeout raises
UpstreamTimeout, and no test performs a real network call.

Najważniejsze są przypadki „bez ponowienia”. Implementacja, która ponawia wszystko, przechodzi każdy test ścieżki sukcesu, a na produkcji mnoży zwroty pieniędzy.

Jak dostać ustrukturyzowane logi, które nigdy nie ujawniają sekretów?

Prompt do skopiowania: structlog z identyfikatorami żądań i redakcją

Configure structlog in app/core/logging.py: JSON renderer in every environment
except development, which uses ConsoleRenderer. Add a pure ASGI middleware that
reads X-Request-Id or generates uuid4, binds it with
structlog.contextvars.bind_contextvars, echoes it in the response header, and
clears contextvars when the request ends. Add a processor that replaces the value
of any key named password, token, secret, authorization, cookie, or api_key with
"[REDACTED]", including inside nested dicts. Log each unhandled exception once, in
the exception handler. Tests with structlog.testing.capture_logs: a login request
logs no password or token value, nested secrets are redacted, and every event from
one request carries the same request_id while two concurrent requests keep
different ones.

Asercja z dwoma równoległymi żądaniami dowodzi, że zmienne kontekstowe są czyszczone i przypisane do jednego żądania. Nieprzetestowany procesor redakcji psuje się po cichu, gdy nazwy kluczy się rozjadą.

Jak utrzymać izolację tenantów w API Django REST Framework?

W wielodostępnej aplikacji Django groźny błąd to jeden viewset, który zapomina filtrować po organizacji. Przechodzi każdy test pisany z perspektywy właściciela.

Prompt do skopiowania: viewsety DRF z izolacją tenantów i macierzą uprawnień

In the projects app (Django 6.1, Django REST Framework), create a TenantScopedMixin
whose get_queryset() filters by request.user's organization and whose
perform_create() sets it, and make ProjectViewSet and TaskViewSet use it. Owners
can do everything, members can read and update tasks, everyone else gets 404, not
403, so IDs from other tenants are not revealed. Task status transitions are
validated in the serializer: done cannot go back to todo. Use cursor pagination
for tasks and django-filter for status, assignee, and due-date range. Add a test
that iterates over every registered route in the API router and fails if its
viewset does not use TenantScopedMixin. With pytest-django, write a parametrized
matrix of role (owner, member, other-tenant, anonymous) x action (list, retrieve,
create, update, destroy) with the expected status for each cell.

Test przechodzący po wszystkich trasach to bramka, która się skaluje: gdy agent za miesiąc doda nowy viewset i zapomni o mixinie, zestaw testów padnie, zanim ktokolwiek przeczyta nowy plik.

Jak posprzątać przestarzałe idiomy Pythona, które agent wciąż przywraca?

Uruchom ten prompt raz na istniejącym kodzie, zanim zaczniesz przepisy, i ponownie za każdym razem, gdy bramka deprecjacji zrobi się czerwona po aktualizacji zależności.

Prompt do skopiowania: migracja przestarzałych idiomów bez zmiany zachowania

Run make check and fix only what it reports, without changing behaviour:
Pydantic v1 idioms (class Config, @validator, .dict(), .parse_obj()) become their
v2 equivalents; any custom event_loop fixture is removed and loop scope is set
with loop_scope or asyncio_default_fixture_loop_scope (pytest-asyncio 1.x);
imports from testcontainers.postgres move to testcontainers.community.postgres;
@app.on_event handlers move into the lifespan; blocking calls flagged by ruff
ASYNC rules become async equivalents. Do not edit test assertions, do not add
skips, and do not change filterwarnings. Report each change grouped by rule.

Jak zweryfikować Python napisany przez agenta bez czytania każdej linii?

Czytaj wynik bramek i listy przypadków testowych, nie diff. Każda bramka poniżej łapie klasę błędów, która w recenzji wygląda dobrze.

Bramka	Polecenie	Co łapie
Format i lint	ruff format --check, ruff check z ASYNC, S, B, UP	Blokujące wywołania w async def, zaszyte sekrety, SQL sklejany ze stringów, przestarzałą składnię
Typy	mypy --strict z wtyczką Pydantic	Niezgodne kształty danych między warstwami, nieobsłużone None, brakujące await na typowanych korutynach
Deprecjacje	filterwarnings = ["error"]	Idiomy Pydantic v1, usunięte wzorce pytest-asyncio, przestarzałe importy
Testy jednostkowe i HTTP	pytest z httpx.AsyncClient i respx	Kody statusu, treść błędów, walidację, ponowienia, redakcję
Testy integracyjne	Testcontainers z Postgresem i Redisem	Wyścigi, np. sprzedaż ponad stan, brakujące ograniczenia, ponownie dostarczone zadania Celery, wycieki między tenantami
Próg pokrycia	pytest --cov-fail-under=80	Całe moduły, których agent nie przetestował
Zależności	pip-audit na wyeksportowanym lockfile’u	Znane podatności w zależnościach runtime
Agent recenzujący	/code-review (Claude Code), codex review --base main (Codex), Bugbot (Cursor)	Błędy logiczne i brakujące przypadki, których bramki nie wyrażą

Pokrycie dowodzi, że linie się wykonały, a nie że asercje są mocne. Mocniejszy dowód jakości samych testów opisuje strona o testach mutacyjnych i sile wyroczni.

Uruchamiaj bramkę w CI przy każdym pull requeście; plik workflow znajdziesz we wzorcach potoków CI/CD. Inżynier odpowiedzialny za usługę zatwierdza trzy rzeczy: listy przypadków testowych, które agent napisał przed kodem, zieloną bramkę oraz wyniki testów współbieżności i macierzy uprawnień. Ludzka lektura trafia do fragmentów wskazanych przez agenta recenzującego i do kodu, który dotyka uwierzytelniania, pieniędzy albo granic między tenantami. Jak podzielić tę pracę w zespole, opisuje recenzja PR-ów agenta, a bramki bezpieczeństwa dla agentów dodają niezależnego recenzenta bezpieczeństwa.

Kiedy Python napisany przez agenta psuje się na produkcji

Każda z poniższych awarii przechodzi zestaw testów happy path. Każda ma objaw, który da się wykryć, i sposób naprawy.

• Pętla zdarzeń staje pod obciążeniem. Objaw: p99 opóźnień skacze dla wszystkich endpointów, gdy wywoływany jest jeden wolny upstream, a CPU pozostaje niskie. Przyczyna: blokujące wywołanie (requests, time.sleep, synchroniczna sesja ORM, open()) wewnątrz async def. Naprawa: włącz reguły ASYNC Ruffa, jeśli są wyłączone, a potem wydaj prompt: „Fix every ASYNC finding with an async equivalent, or move the call to asyncio.to_thread with a comment saying why. Done means make check passes.”
• MissingGreenlet tylko na produkcji. Objaw: sqlalchemy.exc.MissingGreenlet na endpoincie, który w testach działał. Przyczyna: niejawne leniwe ładowanie relacji w kodzie async, często w serializatorze odpowiedzi. Naprawa: ustaw lazy="raise" na każdej relacji, uruchom testy i dodaj selectinload() tam, gdzie teraz coś pada.
• Async SQLAlchemy nie startuje po aktualizacji. Objaw: błąd informujący, że wymagana jest biblioteka greenlet. Przyczyna: SQLAlchemy 2.1 przeniosło greenlet do dodatku [asyncio]. Naprawa: zadeklaruj zależność sqlalchemy[postgresql-asyncpg] (albo sqlalchemy[asyncio]) i zacommituj zaktualizowany uv.lock.
• Sprzedaż ponad stan albo podwójne efekty uboczne. Objaw: ujemny stan magazynu, zdublowane raporty albo zdublowane zwroty po skoku ruchu lub restarcie workera. Przyczyna: logika „odczytaj, a potem zapisz” w Pythonie albo nieidempotentne zadanie dostarczone ponownie. Naprawa: dodaj współbieżny test na Testcontainers z przepisu na zamówienia, a potem wydaj prompt: „Find every place that reads a value, decides in Python, and writes it back. Replace each with a conditional UPDATE or a row lock, and add a concurrent test for each.”
• Zestaw testów pada po aktualizacji pytest-asyncio. Objaw: błędy wspominające fixture event_loop. Przyczyna: agent użył wzorca sprzed wersji 1.0, czyli nadpisania fixture’a event_loop, a pytest-asyncio 1.0 ten fixture usunęło. Naprawa: uruchom prompt sprzątający przestarzałe idiomy; zastępuje ten fixture ustawieniem loop_scope.
• Jeden tenant widzi dane innego. Objaw: zgłoszenie do supportu albo log dostępu z identyfikatorami innej organizacji. Przyczyna: nowy viewset lub zapytanie bez filtra tenanta. Naprawa: dodaj test mixinu przechodzący po wszystkich trasach z przepisu na Django, żeby luka nie wróciła, i przejrzyj logi z okresu, którego dotyczy problem.
• Agent osłabia test, żeby dojść do zielonego wyniku. Objaw: poluzowana asercja, usunięty przypadek, dodany skip lub xfail albo zmienione filterwarnings w tym samym diffie co poprawka. Naprawa: przywróć plik testu, powtórz regułę z AGENTS.md i spraw, żeby CI padało, gdy pull request zmienia istniejący plik test_*.py albo konfigurację pytest bez etykiety test-change.

Uwaga

„Testy przechodzą” to słaby dowód dla asynchronicznego Pythona. Testy na SQLite, zamockowanych repozytoriach czy w trybie eager Celery przechodzą nawet wtedy, gdy kod produkcyjny ma wyścigi, blokuje pętlę albo obciąża klienta dwa razy. Traktuj testy integracyjne na Testcontainers jako część definicji „gotowe”, a nie opcjonalne utwardzanie.

Dokąd dalej z usługami w Pythonie

• Najpierw przygotuj repozytorium dla agenta, jeśli jeszcze nie jest gotowe: kod gotowy dla agenta.
• Zaprojektuj kontrakt API przed handlerami: wzorce tworzenia API.
• Wzmocnij warstwę danych: dobre praktyki ORM i wzorce migracji baz danych.
• Buduj potoki danych i zadania wsadowe w Pythonie: przepisy na inżynierię danych.
• Wdróż usługę: wzorce Dockera oraz wzorce monitoringu i logowania.
• Zdecyduj, co agent może uruchamiać bez nadzoru: uprawnienia i sandboxing.
• Porównaj z innym stosem backendowym: przepisy na Node.js/Express albo wróć do przeglądu przepisów backendowych.