Receptury inżynierii danych

Receptury inżynierii danych to gotowe prompty dla Claude Code, Codeksa i Cursora obejmujące modele dbt, potoki SQL, notatniki i testy danych. Każda receptura trzyma się jednej zasady: agent czyta prawdziwy projekt przez serwer MCP dbt, uruchamia dbt wyłącznie na targecie deweloperskim i oddaje wynik dbt build oraz porównanie wiersz po wierszu zamiast SQL do przeczytania.

Ta strona jest dla programistów i inżynierów analityki, którzy oddają agentowi zmiany w potoku danych. Chroni przed takim scenariuszem: model się kompiluje, a tydzień później dashboard przychodów pokazuje inne liczby, bo złączenie po cichu zwielokrotniło wiersze.

Która receptura inżynierii danych pasuje do twojego zadania?

Twoje zadanie	Receptura	Bramka, która to udowadnia
Dodanie lub zmiana modelu dbt	Model dbt, zaczynając od testu	Testy jednostkowe napisane przed SQL; `dbt build` na modelu i wszystkim, co od niego zależy
Refaktoryzacja modelu bez zmiany liczb	Refaktoryzacja z porównaniem wierszy	Porównanie `audit_helper` z produkcją: zero zmienionych wierszy
Uporządkowanie notatnika Jupyter lub przeniesienie go na produkcję	Notatniki czytelne i uruchamialne	Diff sparowanego pliku `.py` plus `pytest --nbval-lax` na czystym kernelu
Strojenie wolnego zapytania w hurtowni lub zmiana schematu	Optymalizacja SQL i wzorce migracji	Plan zapytania i czas przed zmianą i po niej; up, down, up na kopii

Do serwisów w Pythonie wokół potoku (zadania ingestii, API) użyj receptur dla Pythona. Resztę kolekcji znajdziesz w książce kucharskiej dla deweloperów AI.

Daj agentowi reguły pracy z danymi, zanim użyjesz receptury

Bez reguł agent uruchamia dbt run na tym targecie, który profiles.yml ustawia jako domyślny, a nieprzechodzący test „naprawia” przez jego usunięcie. Zapisz reguły raz, tam, gdzie każde narzędzie wczytuje je automatycznie:

## Data rules
- Never run dbt against the prod target. Use --target dev; the default target in profiles.yml is dev.
- Select only what changed: --select state:modified+ --defer --state prod-artifacts
- Never delete, disable, or loosen a data test (severity, where:, error_if) to make a build pass.
  Report the failure and stop.
- Never SELECT raw columns tagged pii; profile them with counts and null rates only.
- After any change, run scripts/verify-dbt.sh and paste the full output in your summary.

Dodaj blok do CLAUDE.md w katalogu głównym repozytorium. Claude Code wczytuje go w każdej sesji, także w trybie bezobsługowym claude -p.

Dodaj blok do AGENTS.md w katalogu głównym repozytorium. Niezaufany projekt nie dostarcza swojego projektowego AGENTS.md (Codex 0.150.0 i nowsze), więc oznacz repozytorium jako zaufane: dopisz do ~/.codex/config.toml sekcję [projects."/abs/path/to/repo"] z trust_level = "trusted" (klucz sprawdzony w kodzie Codeksa 0.157.1).

Katalog prod-artifacts/ zawiera ostatni produkcyjny manifest.json, więc budują się tylko twoje zmiany. Przed każdym uruchomieniem pobierz ten manifest.json z artefaktów CI ostatniego produkcyjnego przebiegu do prod-artifacts/; bez niego state:modified i --defer kończą się błędem.

Podłącz serwer MCP dbt i skille agenta dbt

Serwer MCP dbt od dbt Labs (PyPI dbt-mcp, wymaga Pythona 3.12 lub 3.13) daje agentowi lineage, szczegóły węzłów, dbt list, compile i show. Skille agenta dbt (dbt-labs/dbt-agent-skills) uczą konwencji dbt, na przykład pisania testów jednostkowych. Poniższe polecenia wyłączają narzędzia serwera run, build, test, clone i docs, więc każde budowanie przechodzi przez skrypt bramek:

# Terminal, w katalogu głównym projektu dbt. Wymaga uv i dbt w PATH (albo ustaw DBT_PATH).
claude mcp add dbt -e DBT_PROJECT_DIR="$PWD" -e DISABLE_TOOLS=run,build,test,clone,docs -- uvx dbt-mcp

# W prompcie Claude Code: zainstaluj skille jako plugin
/plugin marketplace add dbt-labs/dbt-agent-skills
/plugin install dbt@dbt-agent-marketplace

# Terminal, w katalogu głównym projektu dbt. Wymaga uv i dbt w PATH (albo ustaw DBT_PATH).
codex mcp add dbt --env DBT_PROJECT_DIR="$PWD" --env DISABLE_TOOLS=run,build,test,clone,docs -- uvx dbt-mcp
npx skills add dbt-labs/dbt-agent-skills --skill using-dbt-for-analytics-engineering --skill adding-dbt-unit-test -a codex

Dodaj serwer do .cursor/mcp.json, z bezwzględną ścieżką do projektu dbt:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/Users/you/code/analytics",
        "DISABLE_TOOLS": "run,build,test,clone,docs"
      }
    }
  }
}

Potem zainstaluj skille: npx skills add dbt-labs/dbt-agent-skills --skill using-dbt-for-analytics-engineering --skill adding-dbt-unit-test -a cursor.

Narzędzie show serwera nadal wykonuje SQL przez twój profiles.yml, więc domyślnym targetem musi być dev. Dostęp do hurtowni poza dbt opisuje strona serwery MCP dla baz danych.

Zbuduj model dbt, zaczynając od testu

Oczekiwane wiersze zapisz przed SQL. Testy jednostkowe dbt (klucz unit_tests:, dbt Core 1.8 i nowsze) przyjmują ustalone wiersze wejściowe i sprawdzają wynik, więc agent nie przejdzie ich zgadywaniem. To pętla TDD (test-driven development) zastosowana do SQL.

I need a model fct_daily_revenue: one row per order_date and currency, summing
net revenue from stg_orders (exclude status = 'cancelled') and refunds from
stg_refunds, converted to EUR with stg_fx_rates on the order date.

1. Use the dbt MCP server to read the lineage and columns of every input.
   Print the grain and primary key of each input as a table.
2. Before writing SQL, add a unit test in models/marts/_fct_daily_revenue.yml
   with fixed input rows covering: a cancelled order, a partial refund, a
   missing FX rate, and two currencies on one day. Show me the expected rows.
3. Write the model. Add a dbt_utils.unique_combination_of_columns test on
   (order_date, currency) and not_null tests on both columns. dbt_utils must
   already be in packages.yml; if it is not, stop and ask me.
4. Run scripts/verify-dbt.sh and paste the full output.
Stop and ask me if an input's grain makes the join fan out.

Zrefaktoryzuj model dbt bez zmiany liczb

Refaktoryzację udowadniają dane, a nie czytanie diffu. Pakiet audit_helper (dbt Hub dbt-labs/audit_helper) porównuje twoją deweloperską wersję modelu z relacją produkcyjną wiersz po wierszu i klasyfikuje każdą różnicę. Prompt agreguje wynik, bo dbt show domyślnie wypisuje tylko pięć wierszy, a makro zwraca najwyżej 20 przykładowych wierszy na status.

Refactor models/marts/fct_orders.sql: replace the three nested subqueries with
CTEs and move the currency logic into int_orders_converted. The output must not
change.

1. Add dbt-labs/audit_helper to packages.yml if it is missing, then run dbt deps.
2. Build the refactored model with --target dev.
3. Write analyses/compare_fct_orders.sql using
   audit_helper.compare_and_classify_relation_rows to compare the dev relation
   with the production relation on primary key order_id. Wrap it as
   select dbt_audit_row_status, max(dbt_audit_num_rows_in_status)
   from (...) group by 1
   and run dbt show --select compare_fct_orders --limit -1.
4. Report the row count of each relation and the row count per status.
Done means the only status is identical and both row counts are equal. If
not, show five examples and stop; do not edit tests or the comparison.

Utrzymuj notatniki czytelne i uruchamialne

Agenci słabo edytują JSON pliku .ipynb. Sparuj każdy notatnik ze zwykłym skryptem przez Jupytext (jupytext --set-formats ipynb,py:percent notebook.ipynb), każ agentowi edytować plik .py, a wynik udowodnij przez nbval, który wykonuje notatnik od zera na czystym kernelu.

Work on notebooks/churn_analysis.py (the Jupytext pair of the .ipynb), never
the .ipynb JSON. Make it run top to bottom on a fresh kernel: remove cells
that depend on execution order, replace hard-coded file paths with a
DATA_DIR variable, and move the feature-engineering cells into
src/features/churn.py with pytest tests. Then run
jupytext --sync notebooks/churn_analysis.py and
pytest --nbval-lax notebooks/churn_analysis.ipynb, and paste both outputs.
List any cell whose output changed and why.

Jak zweryfikować zmiany w danych od agenta bez czytania każdej linii?

Zbierz bramki w jednym skrypcie, który uruchamia każde narzędzie, każdy człowiek i CI. Skrypt odmawia pracy na targecie prod i przed właściwym budowaniem buduje z zerową liczbą wierszy:

#!/usr/bin/env bash
# scripts/verify-dbt.sh: dev target only. Delete the lines your project does not use.
set -euo pipefail
TARGET="${DBT_TARGET:-dev}"
if [ "$TARGET" = "prod" ]; then echo "refusing to run against prod"; exit 1; fi
SEL=(--select state:modified+ --defer --state prod-artifacts --target "$TARGET")
[ -d dbt_packages ] || dbt deps   # needs network; skipped once packages are installed
dbt parse --warn-error --target "$TARGET"
dbt build "${SEL[@]}" --empty
dbt build "${SEL[@]}"
sqlfluff lint models/
pytest --nbval-lax notebooks/
echo "PASS all data gates"

Raz nadaj skryptowi prawo wykonania, żeby reguły zezwoleń poniżej mogły go wywołać bez prefiksu bash:

chmod +x scripts/verify-dbt.sh

Człowiek zatwierdza tylko dwie rzeczy: porównanie wierszy przy każdej zmianie modelu, który zasila dashboard lub eksport, oraz każde --full-refresh modelu inkrementalnego. Oba trafiają do pakietu dowodów pull requesta. Żeby uruchamiać bramki bez nadzoru, zapisz ten prompt „naprawiaj, aż przejdzie” jako prompts/dbt-gates.txt:

Run scripts/verify-dbt.sh exactly as written, with no ./ or bash prefix.
If it fails, fix only the model SQL. Never edit tests, test YAML,
packages.yml, profiles.yml, or scripts/verify-dbt.sh.
Rerun until it prints PASS all data gates, or stop after 3 failed attempts.
Then paste the final output of the script and list every file you changed.

# Terminal, na zaufanej gałęzi. Edycje dozwolone; powłoka ograniczona do skryptu
# bramek; narzędzia MCP dbt dozwolone (run/build/test/clone/docs wyłączone na serwerze).
claude -p "$(cat prompts/dbt-gates.txt)" \
  --allowedTools "Read,Grep,Glob,Edit,Bash(scripts/verify-dbt.sh),Bash(./scripts/verify-dbt.sh),mcp__dbt" \
  --output-format json > dbt-gates.json

# Terminal. dbt deps działa poza piaskownicą; -o zapisuje końcowe podsumowanie.
dbt deps

# Lokalny target DuckDB: profil uprawnień (beta) ogranicza zapis do workspace.
codex exec -c default_permissions=":workspace" -o dbt-gates.md "$(cat prompts/dbt-gates.txt)"

# Hurtownia w chmurze, tylko gdy poświadczenia agenta sięgają wyłącznie schematów dev.
codex exec --sandbox workspace-write -c sandbox_workspace_write.network_access=true \
  -o dbt-gates.md "$(cat prompts/dbt-gates.txt)"

Piaskownica domyślnie blokuje ruch wychodzący (workspace-write ma network_access = false, sprawdzone w kodzie źródłowym Codeksa 0.157.1), więc pakiety instalujesz wcześniej, a skrypt pomija dbt deps. Wariant chmurowy dodaje nadpisanie sieci, bo dbt musi połączyć się z hurtownią. Tych dwóch mechanizmów nie łącz w jednym wywołaniu — nie współpracują ze sobą; wybierz profil uprawnień albo starszą piaskownicę --sandbox.

Wklej prompt do agenta i zaakceptuj diff dopiero po linii PASS.

Co się psuje, gdy agenci piszą potoki danych?

Złączenie, które mnoży wiersze. Złączenie jeden do wielu podwaja przychód. Naprawa: test unique na ziarnistości modelu.
Zielony build, bo test został osłabiony (severity: warn, filtr where:, usunięty test). Naprawa: cofnij zmianę i wymagaj zatwierdzenia właściciela kodu dla YAML-a testów; zobacz ochronę wyroczni.
Agent zbudował model na produkcji. Naprawa: domyślny target dev, budowanie przez skrypt bramek i brak prawa zapisu do schematów produkcyjnych dla poświadczeń agenta; zobacz uprawnienia i piaskownice.
Model inkrementalny rozjeżdża się z pełną przebudową (gałąź is_incremental() nie została zmieniona). Naprawa: --full-refresh na dev i porównanie recepturą refaktoryzacji.
Testy przechodzą na zabawkowych danych. Naprawa: realistyczne, zamaskowane dane testowe; zobacz zarządzanie danymi testowymi.

Dokąd dalej z inżynierią danych

Przepisy bazodanowe Migracje, kod ORM i strojenie SQL po stronie transakcyjnej.

Ochrona wyroczni Trzymaj testy danych poza zasięgiem agenta, żeby zielony build nadal coś znaczył.

Projektowanie baz danych i zapytania Pełny przepływ pracy wokół zmian schematu.

Instalowanie, udostępnianie i przypinanie skilli Jak skille się ładują i aktualizują we wszystkich trzech narzędziach.

Pakiet dowodów Co zawiera pull request, żeby recenzent sprawdzał wyniki, a nie linie.