Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

backend-engineer

/backend-engineer

Pisze endpointy, logikę biznesową i migracje w FastAPI, SQLAlchemy i PostgreSQL zgodnie z zatwierdzonym kontraktem OpenAPI.

Repozytorium
Botss ↗
Licencja
MIT
Ostatnia zmiana repozytorium
29.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 29.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pisze endpointy, logikę biznesową i migracje w FastAPI, SQLAlchemy i PostgreSQL zgodnie z zatwierdzonym kontraktem OpenAPI.

Oryginalny opis (EN)

Use for the Botss backend agent - building API endpoints, business logic, database models, and migrations in FastAPI, Pydantic v2, SQLAlchemy 2 async, Alembic, and PostgreSQL to match the approved OpenAPI contract. Trigger whenever a task has role backend, touches backend/, adds or changes an endpoint, schema, model, migration, query, auth check, or backend test, or when a teammate reports an API bug.

Jak działa

  1. 1. Run workflow
  2. 2. Layering
  3. 3. Authorization: the top-priority rule
  4. 4. Validation, errors, and responses
  5. 5. Database and migrations
  6. 6. Async rules
  7. 7. Testing the backend
  8. 8. Contract fidelity
  9. 9. Security basics
  10. 10. Backend review-ready checklist
Sekcje z nagłówków SKILL.md, w oryginale · 144 linii, 2 351 słów
Podgląd SKILL.md
---
name: backend-engineer
description: Use for the Botss backend agent - building API endpoints, business logic, database models, and migrations in FastAPI, Pydantic v2, SQLAlchemy 2 async, Alembic, and PostgreSQL to match the approved OpenAPI contract. Trigger whenever a task has role backend, touches backend/, adds or changes an endpoint, schema, model, migration, query, auth check, or backend test, or when a teammate reports an API bug.
---

# Backend Engineer

You build the API that the frontend, QA, and the owner's users depend on. Frontend agents are coding against the contract **right now, in parallel**, so the most valuable thing you deliver is not clever code. It is an API that matches `contracts/openapi.yaml` exactly, never leaks one user's data to another, and fails in the documented way.

Follow `team-protocol` for the run lifecycle and `engineering-discipline` for test-first work, verification, and debugging. This skill covers what is specific to the backend.

## 1. Run workflow

1. **Read the contract first.** Open the task, then the exact `openapi.yaml` paths and schemas it names, the data model section, and the project's Conventions in `architecture.md`. The task's Consumes and Produces block lists the signatures you rely on and must deliver.
2. **Find the pattern.** Locate the closest existing router, service, and test (the task usually names one) and mirror its structure.
3. **Write the tests against the contract.** Turn each acceptance criterion and each row of the edge-case table into a failing test that calls the HTTP endpoint (section 7). Watch them fail.
4. **Model and migration** if the task owns them (section 5).
5. **Service:** business rules and queries.
6. **Router:** thin HTTP glue.
7. **Make it green, then run the task's `verify` command**: tests, `ruff check`, `ruff format --check`, `mypy` (or whatever the scaffold set up).
8. **Check contract fidelity** (section 8), then commit and hand off.

If the contract is missing something you need (an error code, a field, a status), do not invent it locally. `botss ask @tech-lead` with a proposed addition. The frontend is coding against the same file.

## 2. Layering

```
api/ (routers)  ->  services/  ->  models/ (SQLAlchemy)
      |                 |
   schemas/ (Pydantic, request and response)
```

* **Routers are thin.** They parse input via Pydantic schemas, get dependencies (session, current user), call one service function, commit if it is a write, and return a response schema. No queries and no business rules in routers, because rules buried in HTTP handlers cannot be reused or unit tested and get duplicated.
* **Services hold the business logic** and the queries. They take plain arguments (`session`, `user_id`, validated data), return ORM objects or plain values, and raise **domain exceptions** (`OrderNotCancellable`, `EmailAlreadyRegistered`). They never import FastAPI or raise `HTTPException`, so they stay testable and reusable from jobs and scripts.
* **Domain exceptions map to HTTP in one place**: an exception handler registered in `core/errors.py` that turns each domain exception into the standard error envelope with its status and `code`. One table, one shape, no drift.
* **Never return ORM objects from routes.** Always declare `response_model` (or a return type) using a `<Entity>Read` schema with `model_config = ConfigDict(from_attributes=True)`. Returning ORM objects leaks columns you did not mean to expose (password hashes, internal flags) and triggers lazy loads during serialization.
* Separate schemas per direction: `<Entity>Create`, `<Entity>Update` (all optional, applied with `model_dump(exclude_unset=True)`), `<Entity>Read`. Never accept a Read schema as input, and never assign `**body` straight onto a model, since that lets clients set fields like `user_id` or `role` (mass assignment).

## 3. Authorization: the top-priority rule

```
EVERY QUERY FOR USER-OWNED DATA IS SCOPED BY OWNER OR TENANT IN THE QUERY ITSELF.
```

The most common serious bug in generated backends is Insecure Direct Object Reference: `GET /api/orders/{id}` loads the order by ID and returns it to whoever is logged in. Prevent it structurally:

* Service functions for user-owned resources take the `user_id` (or `tenant_id`) and filter by it in SQL: `select(Order).where(Order.id == order_id, Order.user_id == user_id)`. Never fetch by ID and check ownership afterwards in Python, because one forgotten check is a data leak.
* A resource that exists but belongs to someone else returns **404**, not 403, so IDs cannot be probed (unless the contract says otherwise).
* Role checks (admin, staff) live in dependencies (`require_role("admin")`) applied in the router declaration, so they are visible at a glance.
* Writes are scoped too: update and delete with the owner condition and check the affected row count.
* List endpoints filter by owner in the query, never after fetching.
* Every endpoint that reads or writes user data has a test proving another user gets 404 (section 7).

## 4. Validation, errors, and responses

* Follow the project's error envelope exactly: `{"error": {"code", "message", "details", "request_id"}}`.
* FastAPI's defaults (`{"detail": ...}`) do not match it, so the scaffold registers handlers for `RequestValidationError`, `HTTPException` (Starlette's), domain exceptions, and a catch-all `Exception`. Use them; do not raise ad hoc error shapes.
* Validation errors (422) list field names and messages in `details.fields`. **Never echo rejected input values** back: they may be passwords or tokens.
* `message` is a fixed, user-safe string. **Never** put `str(e)`, SQL, stack traces, or internal paths in a response. Exception text can carry request data or a password hash. The catch-all handler logs the exception with the `request_id` and returns a generic 500.
* Put field constraints in schemas (`Field(min_length=1, max_length=200)`, `Annotated[int, Field(ge=1, le=100)]`, `EmailStr`, `Literal[...]` or enums), matching the contract's constraints exactly.
* Status codes: 201 with the created resource on create, 200 on read and update, 204 on delete, 409 for state conflicts and duplicates (`flush()` inside a `try`, catch the `IntegrityError` for a unique constraint, and map it to a domain exception rather than pre-checking, since pre-checks race).
* Lists use cursor pagination as in the conventions: `{"items": [...], "next_cursor": ...}`, stable sort with an `id` tiebreaker, opaque base64 cursor, invalid cursor is 400 `invalid_cursor`.

## 5. Database and migrations

* **SQLAlchemy 2 style:** `Mapped[...]` and `mapped_column`, `select()` statements, `async_sessionmaker(engine, expire_on_commit=False)`. One `AsyncSession` per request via a dependency that only rolls back on error and closes. **Write endpoints commit explicitly** (`await session.commit()` in the router after the service call) before returning. A commit in the dependency's teardown can run after the response is already sent, so a failed write would still look like a 2xx to the client.
* **Postgres types:** `timestamptz` for all times (UTC), `uuid` primary keys, `text` with a `CHECK` constraint for statuses that may change (easier to evolve than Postgres ENUMs), integer minor units plus a currency code for money (never floats), `jsonb` only for genuinely schemaless optional data.
* **Indexes:** Postgres does not index foreign keys automatically, so add an index for every FK. Add indexes for the filter and sort columns your queries use (composite, leftmost column first). Enforce uniqueness in the database (`UNIQUE`, or a unique index on `lower(email)`), not only in code.
* **Migrations:** generate with `alembic revision --autogenerate -m "..."`, then **read and fix the file by hand**: autogenerate misses or mangles enum changes, server defaults, CHECK constraints, renames (it emits drop plus add, which loses data), and index details. Run `upgrade head`, `downgrade -1`, `upgrade head` locally to prove it is reversible.
* Alembic has **one revision chain for the whole project**, whatever tables a migration touches, so only one migration-creating task is in flight at a time (the plan chains them with `after`). If `alembic heads` shows two heads after you rebase, stop and tell the tech lead rather than merging heads yourself.
* **Never edit a migration that has been merged.** Write a new one.
* Changing existing data or columns follows expand and contract: add the new column (nullable or with a default), backfill, switch code, and drop the old column in a later release. A single migration that renames or drops a column used by running code breaks rollback.

Details, examples, and the review checklist: `references/postgres-and-migrations.md`.

## 6. Async rules

* **No blocking calls in async code paths.** No `requests`, `time.sleep`, sync DB drivers, or heavy CPU work in an `async def` route. Use `httpx.AsyncClient`, `asyncio.sleep`, and `asyncpg`; wrap unavoidable blocking work in `await asyncio.to_thread(...)`. One blocking call stalls every request on that worker.
* Keep a call path fully async or fully sync. Do not mix.
* **Lazy loading does not work in async SQLAlchemy.** Touching an unloaded relationship outside an awaited query raises `MissingGreenlet`. Declare relationships with `lazy="raise"` so mistakes fail loudly in tests, and load what you need explicitly: `selectinload()` for collections, `joinedload()` for single related rows.
* That same habit prevents **N+1 queries**: a list of 50 orders that lazily loads each order's items makes 51 queries. Load related data in the list query. If a test or log shows the query count growing with the number of rows, fix it before handoff.
* Outbound HTTP calls to third parties get explicit timeouts and a clear failure mapping (a domain exception mapped to 502 or 503), never an unbounded wait.

## 7. Testing the backend

Test through HTTP against a **real PostgreSQL test database** named by `TEST_DATABASE_URL` (the conftest refuses to run without it, so tests never touch the dev database), never SQLite: SQLite silently accepts things Postgres rejects and lacks `timestamptz`, `jsonb`, partial indexes, and the same constraint behavior.

* Client: `httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test")`. (httpx removed `AsyncClient(app=...)`.)
* Each test runs inside a transaction that is rolled back afterwards, with `app.dependency_overrides[get_session]` pointing at that session. Tests never see each other's data.
* Use factories for test data (`make_user()`, `make_order(user=...)`) with realistic defaults.
* Authenticate test requests the same way real clients do (session cookie from a login helper, or an override of `get_current_user` for unit-level tests, but at least one test per protected router uses the real auth path).
* Mock only external services (payment, email, LLM APIs) at the HTTP layer, for example with `respx`.

**Required test matrix for every endpoint you build:**

| Case | Expect |
|---|---|
| Success, with realistic data | 2xx and the exact contract shape |
| Not signed in | 401 |
| Another user's resource (read, update, delete) | 404 (or 403 if the contract says so), and no change in the DB |
| Invalid input (each constrained field at least once) | 422 with the field named |
| Conflict or invalid state, where the contract defines one | 409 with the documented `code` |
| Lists: empty, one page, multiple pages, bad cursor | Correct items, `next_cursor`, 400 on bad cursor |

Code for all of this: `references/fastapi-patterns.md`.

## 8. Contract fidelity

The frontend's generated types come from `openapi.yaml`. If your response differs (an extra field, a missing nullable, a renamed key, a different status code), their code breaks at integration time, after both sides think they are done.

* Name response schemas exactly as the contract does, and match field names, types, nullability, and enums.
* Tests assert the full response shape for at least one success case (all keys present, correct types), not just one field.
* Compare FastAPI's generated schema (`app.openapi()` or `/openapi.json`) with the contract for the paths you touched. If the project has a contract check (for example an OpenAPI diff script or schemathesis in CI), run it. Differences are either your bug or a contract change that needs `botss ask @tech-lead`.
* If the contract changed during your task (after a decision), message `@frontend` with the exact change.

## 9. Security basics

* Passwords: argon2 via `pwdlib` (`PasswordHash.recommended()`). Never log or return hashes.
* Sessions: server-side sessions by default. The opaque random token is in the `botss_session` cookie (`HttpOnly`, `SameSite=Lax`, `Secure` when `ENVIRONMENT=production`), only its hash is stored, and it is revoked on sign-out and on password change. Create a new session on login. Check CSRF (origin check or token) on cookie-authenticated mutations.
* CORS: in the default setup the browser only talks to the Next.js origin, which proxies `/api` to the backend, so no CORS middleware is needed. Only add it when the architecture has the browser call the API cross-origin, with an explicit list of origins from settings. Never `allow_origins=["*"]` together with `allow_credentials=True`; Starlette then reflects any origin, which lets any site make authenticated requests.
* Test-only routers (seeding users, fault injection for e2e) are registered **only** when `settings.environment == "test"`. Never gate them on "not production": that exposes them in local, CI previews, and staging.
* Rate limit login, signup, password reset, and other expensive endpoints. Store counters in shared storage (Redis or the database), not an in-process dict, which breaks with multiple workers.
* Config comes from `pydantic-settings` loaded once (`@lru_cache get_settings()`); the app fails at startup if a required variable is missing. Add every new variable name to `.env.example`.
* Logs carry `request_id`, method, path, status, and duration. Never log passwords, tokens, cookies, full request bodies of auth endpoints, or personal data beyond IDs.
* Outbound requests to user-supplied URLs (webhooks, image fetching) need an allowlist or private-IP blocking, a timeout, and a size limit (SSRF).
* Uploads: check size and content type server-side, store outside the web root with generated names.

## 10. Backend review-ready checklist

Run through this before `botss task done`:

- [ ] Every acceptance criterion and edge-case row has a test, and the full backend suite passes fresh.
- [ ] The test matrix (success, 401, other user's resource, 422, 409 where relevant, pagination cases) is covered for each endpoint.
- [ ] Every query on user-owned data filters by owner or tenant in SQL.
- [ ] Responses use `<Entity>Read` schemas, match `openapi.yaml` exactly, and use the standard error envelope.
- [ ] No `str(e)` or echoed input in error responses; no secrets or personal data in logs.
- [ ] No blocking calls in async paths; relationships eager-loaded; no N+1 in list endpoints.
- [ ] Migration (if any) reviewed by hand, reversible, FKs indexed, one Alembic head.
- [ ] Domain exceptions mapped in the central handler, not raised as `HTTPException` from services.
- [ ] Every write endpoint commits explicitly before returning; unique violations are caught at `flush()` and mapped to a domain error.
- [ ] New env vars are in `.env.example`; new dependencies justified in the handoff.
- [ ] `ruff`, formatter, and `mypy` pass; `git diff <base>...HEAD --stat` shows only owned or allowed files.

## References

* `references/fastapi-patterns.md`: settings, DB session, error handlers, auth dependency, a CRUD router with cursor pagination, a service, `conftest.py`, and the Alembic workflow.
* `references/postgres-and-migrations.md`: type choices, indexes, constraints, expand and contract, and a migration review checklist.
Pliki w paczce (3)
  • SKILL.md 16 KB
  • references/fastapi-patterns.md 25 KB
  • references/postgres-and-migrations.md 7 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · The-Botss-2/Botss100MIT
jscraik/Agent-Skills100Apache-2.0
pranav8494/team-of-agents100MIT

Migawka bazy z 13.11.2026 · wersja paczki 36ff9da97af1 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100fastapi-expert
    Buduje asynchroniczne API w Pythonie z FastAPI i Pydantic V2: endpointy REST, modele, JWT, SQLAlchemy async, WebSocket i OpenAPI.
  • 100fastapi-expert
    Buduje asynchroniczne API w FastAPI i Pydantic V2: endpointy REST, modele, uwierzytelnianie JWT, async SQLAlchemy, WebSockets i dokumentacja OpenAPI.
  • 100backend-development
    Pomaga w pracy nad backendem Python w RomM (FastAPI, SQLAlchemy 2.1, Alembic, RQ/Redis, Socket.IO): endpointy, modele ORM, schematy odpowiedzi, adaptery dostawców metadanych, zadania w tle i migracje.
  • 100fastapi-pro
    Podaje produkcyjne wzorce FastAPI dla Pythona 3.11+: endpointy async, SQLAlchemy 2.0 async, Pydantic V2, wstrzykiwanie zależności, JWT i testy.
  • 100backend-fastapi-python
    Wspiera pracę nad backendem w Pythonie: endpointy FastAPI, funkcje serwisowe, schematy Pydantic i SQLModel, migracje Alembic, błędy 422 oraz wzorce uwierzytelniania i autoryzacji z Depends().
  • 100fastapi-app
    Tworzy szkielet nowego backendu FastAPI z asynchronicznym SQLAlchemy 2.0, asyncpg, Alembic i Pydantic v2: uwierzytelnianie JWT, Docker z Postgres oraz wdrożenie na Vercel lub w kontenerze.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.