# Receptury inżynierii danych

URL: https://developertoolkit.ai/pl/cookbook/data-recipes/
Description: Gotowe receptury na modele dbt, potoki SQL, notatniki i testy danych w Claude Code, Codeksie i Cursorze, każda udowodniona przez dbt build na targecie dev.

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](#zbuduj-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](#zrefaktoryzuj-model-dbt-bez-zmiany-liczb) | Porównanie `audit_helper` z produkcją: zero zmienionych wierszy |
| Uporządkowanie notatnika Jupyter lub przeniesienie go na produkcję | [Notatniki czytelne i uruchamialne](#utrzymuj-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](/pl/cookbook/database-recipes/sql-patterns/) i [wzorce migracji](/pl/cookbook/database-recipes/migration-patterns/) | 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](/pl/cookbook/backend-recipes/python-patterns/). Resztę kolekcji znajdziesz w [książce kucharskiej dla deweloperów AI](/pl/cookbook/).

## 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:

```markdown
## 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.
```

**Claude Code**

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`.

**Codex**

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).

**Cursor**

Zapisz ten sam tekst jako regułę projektu. [Dokumentacja Rules w Cursorze](https://cursor.com/docs/rules) pokazuje, gdzie leżą reguły projektu i jak sprawić, żeby reguła działała przy każdym zapytaniu.

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:

**Claude Code**

```bash
# Terminal, from the dbt project root. Requires uv and dbt on PATH (or set DBT_PATH).
claude mcp add dbt -e DBT_PROJECT_DIR="$PWD" -e DISABLE_TOOLS=run,build,test,clone,docs -- uvx dbt-mcp

# In the Claude Code prompt: install the skills as a plugin
/plugin marketplace add dbt-labs/dbt-agent-skills
/plugin install dbt@dbt-agent-marketplace
```

**Codex**

```bash
# Terminal, from the dbt project root. Requires uv and dbt on PATH (or set 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
```

**Cursor**

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

```json
{
  "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](/pl/ecosystem/mcp/database-mcp/).

## 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)](/pl/method/principles/test-driven-development/) zastosowana do SQL.

**Prompt do skopiowania: nowy model dbt, najpierw test**

```text
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.

**Prompt do skopiowania: refaktoryzacja z dowodem na poziomie wierszy**

```text
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.

**Prompt do skopiowania: uporządkuj notatnik, zanim stanie się potokiem**

```text
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:

```bash
#!/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`:

```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](/pl/workflows/ship/evidence-bundle/) pull requesta. Żeby uruchamiać bramki bez nadzoru, zapisz ten prompt „naprawiaj, aż przejdzie” jako `prompts/dbt-gates.txt`:

**Prompt do skopiowania: prompts/dbt-gates.txt**

```text
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.
```

**Claude Code**

```bash
# Terminal, on a trusted branch. Edits allowed; shell limited to the gate
# script; dbt MCP tools allowed (run/build/test/clone/docs are disabled on the server).
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
```

**Codex**

```bash
# Terminal. dbt deps runs outside the sandbox; -o saves the final summary.
dbt deps

# Local DuckDB target: the permission profile (beta) keeps writes in the workspace.
codex exec -c default_permissions=":workspace" -o dbt-gates.md "$(cat prompts/dbt-gates.txt)"

# Cloud warehouse, only where the agent's credentials reach dev schemas alone.
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`.

**Cursor**

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

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

**Awarie receptur danych i jak z nich wyjść**

- **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](/pl/workflows/test/protect-the-oracle/).
- **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](/pl/workflows/harness/permissions-and-sandboxing/).
- **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](/pl/workflows/test/test-data-management/).

## Dokąd dalej z inżynierią danych

- [Przepisy bazodanowe](/pl/cookbook/database-recipes/) — Migracje, kod ORM i strojenie SQL po stronie transakcyjnej.
- [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) — Trzymaj testy danych poza zasięgiem agenta, żeby zielony build nadal coś znaczył.
- [Projektowanie baz danych i zapytania](/pl/workflows/build/database-development/) — Pełny przepływ pracy wokół zmian schematu.
- [Instalowanie, udostępnianie i przypinanie skilli](/pl/ecosystem/skills/installing-managing/) — Jak skille się ładują i aktualizują we wszystkich trzech narzędziach.
- [Pakiet dowodów](/pl/workflows/ship/evidence-bundle/) — Co zawiera pull request, żeby recenzent sprawdzał wyniki, a nie linie.
