# Receptury Ruby on Rails

URL: https://developertoolkit.ai/pl/cookbook/backend-recipes/ruby-rails-patterns/
Description: Receptury dla agentów w Rails 8.1 — generatory zamiast ręcznych plików, pętle RSpec, bin/ci jako definicja ukończenia, bezpieczne migracje i wykrywanie N+1.

Receptury Ruby on Rails dla agentów AI to konfiguracja i prompty, dzięki którym Claude Code, Codex i Cursor dostarczają godne zaufania zmiany w Rails 8.1: generatory zamiast ręcznie pisanego boilerplate'u, specyfikacje RSpec pisane przed kodem, `bin/ci` jako definicja ukończenia, migracje sprawdzane pod kątem odwracalności i blokad oraz zapytania N+1, które wywracają spec.

Ta strona jest dla programistów Rails, za których większość funkcji pisze już agent, oraz dla tech leadów, którzy chcą, żeby w CI cały zespół podlegał tym samym bramkom. Sytuacja, którą rozwiązuje: pull request od agenta jest zielony, tyle że agent ręcznie napisał migrację ze znacznikiem czasu z zeszłego roku, poprawił `db/schema.rb` bezpośrednio, wyrenderował listę z `order.customer.name` w pętli, a padający spec „naprawił”, zmieniając oczekiwaną wartość. Poniższe receptury sprawiają, że agent w każdej turze zderza się z konwencjami, generatorami i lokalnym runnerem CI z Rails, więc przeglądasz dowody, a nie diffy.

## Co zyskujesz dzięki tym recepturom Rails

- `config/ci.rb`, który zamienia `bin/ci` w bramkę, przez którą agent musi przejść: RuboCop, Brakeman, RSpec i krok sprawdzający odwracalność migracji.
- `AGENTS.md` dla aplikacji Rails, podpięty do Claude Code, Codex i Cursora.
- Prompt „najpierw generator”, który nie pozwala agentowi ręcznie pisać migracji, modeli i specyfikacji.
- Pętlę spec-first dla endpointu Rails: od kryteriów akceptacji, przez padające request specs, do implementacji.
- Hook `Stop` w Claude Code, który nie pozwala ogłosić „gotowe”, dopóki RuboCop i RSpec nie przejdą, oraz job CI, który jest mechaniczną bramką dla Codex i Cursora.
- Wykrywanie N+1, które wywraca specyfikacje, z wyborem między Bullet, Prosopite i `strict_loading` przetestowanym na Rails 8.1.4.
- Recepturę na migracje ze `strong_migrations`, kontrolą rozjazdu schematu i ludzką akceptacją zmian niszczących dane.
- Testy mutacyjne z `mutant`, które pokazują, czy specyfikacje agenta złapałyby błąd.

## Jakie wersje Ruby, Rails i gemów zakładają te receptury?

Agenci mieszają API z Rails 5, 6, 7 i 8, bo tak wyglądają ich dane treningowe. Podaj agentowi wersje i przypnij je w repozytorium (`.ruby-version`, `Gemfile.lock`), żeby nie mógł dryfować. Te wersje były aktualne 2026-09-26:

| Komponent | Wersja | Źródło (sprawdzone 2026-09-26) |
| --- | --- | --- |
| Ruby | 4.0.7 (2026-09-15) | wydania na ruby-lang.org |
| Rails | 8.1.4 (2026-09-24); wymaga Ruby 3.2 lub nowszego | rubygems.org |
| `rspec-rails` / `factory_bot_rails` | 8.0.4 / 6.5.1 | rubygems.org |
| `rubocop` / `rubocop-rails` / `rubocop-rails-omakase` | 1.91.0 / 2.38.0 / 1.1.0 | rubygems.org |
| `brakeman` | 8.0.6 | rubygems.org |
| `bullet` / `prosopite` | 8.2.0 / 2.2.0 | rubygems.org |
| `strong_migrations` | 2.8.0 | rubygems.org |
| `mutant` / `mutant-rspec` | 0.17.0 | rubygems.org |
| `ruby-lsp` | 0.26.11 | rubygems.org |

Wyniki dla Rails, RSpec, Bullet, Prosopite, `strict_loading` i `mutant` pochodzą ze świeżej aplikacji Rails 8.1.4 (Ruby 3.3.6, SQLite, `rspec-rails` 8.0.4) z 2026-09-26. Rails 8.1.4 wymaga Ruby 3.2.0 lub nowszego, więc instaluje się na Ruby 4.0, ale receptur nie uruchamialiśmy ponownie na 4.0.7. Workflow z PostgreSQL i kroki ze `strong_migrations` opierają się na dokumentacji tych gemów.

Zostań przy domyślnym modelu swojego narzędzia i najpierw podnieś poziom wysiłku (effort), a dopiero potem zmieniaj model. Aktualne modele domyślne i ceny znajdziesz w [centrum modeli AI](/pl/ecosystem/models/).

## Jak przygotować aplikację Rails do pracy z agentem?

Umieść bramki w plikach, o których agent nie może zapomnieć. Rails 8.1 generuje większość z nich sam: `rails new` tworzy `.rubocop.yml` (dziedziczący z `rubocop-rails-omakase`), `bin/brakeman`, `bin/bundler-audit` i lokalny runner CI `bin/ci`, który czyta kroki z `config/ci.rb` i kończy się niezerowym kodem, gdy którykolwiek krok padnie. Dodaj dwa kroki, które agent pomija najczęściej:

```ruby title="config/ci.rb"
# Run using bin/ci
CI.run do
  step "Setup", "bin/setup --skip-server"
  step "Style: Ruby", "bin/rubocop"
  step "Security: Gem audit", "bin/bundler-audit"
  step "Security: Brakeman code analysis", "bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error"
  step "Tests: RSpec", "bin/rspec"
  step "Migrations: reversible", "bin/rails db:migrate:redo STEP=1"
end
```

Ostatni krok wycofuje najnowszą migrację i stosuje ją ponownie. W aplikacji testowej napisane przez agenta `remove_column :orders, :total_cents` bez typu kolumny rzuciło w tym kroku `ActiveRecord::IrreversibleMigration`, a `bin/ci` zakończył się kodem 1. Binstub `bin/rspec` utworzysz komendą `bundle binstubs rspec-core`.

Domyślnym frameworkiem testowym Rails jest Minitest. Jeśli używasz RSpec, dodaj `rspec-rails` do grupy `:development, :test`, uruchom `bin/rails generate rspec:install` i powiedz generatorom, jakich specyfikacji chcesz, żeby `bin/rails generate` przestał tworzyć specyfikacje widoków i helperów, których nikt nie utrzymuje:

```ruby title="config/application.rb"
config.generators do |g|
  g.test_framework :rspec, view_specs: false, helper_specs: false, routing_specs: false
  g.helper false
end
```

Z tym blokiem `bin/rails generate scaffold Invoice number:string order:references` tworzy tylko spec modelu i request spec. Na koniec odkomentuj `config.example_status_persistence_file_path = "spec/examples.txt"` w `spec/spec_helper.rb` (wygenerowany plik ma tę linię w bloku `=begin`). Bez niej `bin/rspec --only-failures` nie ma czego przeczytać, a agent w każdej iteracji uruchamia cały zestaw.

## Co wpisać do AGENTS.md w aplikacji Rails?

Zapisz komendy, które agent ma uruchamiać, w kolejności, w jakiej ma to robić, oraz kilka reguł, które generyczny model źle stosuje w twoim kodzie. Pomiń wszystko, co już wymusza RuboCop albo `config/ci.rb`.

```markdown title="AGENTS.md"
# Shop (Rails 8.1, Ruby 4.0, PostgreSQL, RSpec, Hotwire)

## Commands (run from the repo root)
- One spec file or example: `bin/rspec spec/requests/orders_spec.rb:12`
- Failures from the last run: `bin/rspec --only-failures`
- Lint with safe autocorrect: `bin/rubocop -a`
- Full gate: `bin/ci` (RuboCop, Brakeman, bundler-audit, RSpec, migration redo)
- Preview a generator: add `--pretend` to any `bin/rails generate` command

## Definition of done
`bin/ci` passes. Report the command you ran and its last lines.

## Rules
- Create models, migrations, controllers, jobs and mailers with `bin/rails generate`, never by hand.
- Never edit db/schema.rb or an existing migration. Add a new migration and run `bin/rails db:migrate`.
- Specs are the specification. If a spec fails, fix app/, not spec/. Ask before changing an expectation.
- Request specs, not controller specs. Use FactoryBot factories from spec/factories.
- Any action that renders a collection uses `includes` or `preload`; the N+1 detector fails the spec otherwise.
- Never add `# rubocop:disable`, a Brakeman ignore entry or `safety_assured` without asking.
- Money is integer cents (`*_cents`), never Float.
```

Każde narzędzie wczytuje ten sam plik inaczej:

**Claude Code**

    Utwórz `CLAUDE.md`, którego pierwsza linia importuje wspólny plik, a poniżej dopisz ewentualne linie tylko dla Claude:

    ```markdown title="CLAUDE.md"
    @AGENTS.md
    ```

    Claude Code 2.1.277 i nowsze czytają `AGENTS.md` także bezpośrednio, gdy projekt nie ma `CLAUDE.md` (sesje bezpośrednio u Anthropic, czyli first-party; v2.1.281 na Bedrock, Google Cloud, Foundry i bramkach LLM; oba kanały wydań, stan na 2026-10-12). Import działa w każdej wersji i na każdym kanale.

**Codex**

    Codex czyta `AGENTS.md`, zanim zacznie pracę. Uruchom `/init` w TUI, żeby wygenerować szkic, a potem zastąp go plikiem powyżej. Od codex-cli 0.150.0 projekt, któremu Codex nie ufa, nie dostarcza swojego `AGENTS.md`, więc oznacz repozytorium jako zaufane, gdy Codex o to zapyta.

**Cursor**

    Dodaj zawsze stosowaną regułę projektu (format opisuje strona o [regułach projektu w Cursorze](/pl/cursor-ide/quick-start/project-rules/)), która powtarza sekcje Commands i Rules z pliku powyżej. Zatwierdź regułę w repozytorium (commit).

**Prompt do skopiowania: szkic AGENTS.md z istniejącej aplikacji Rails**

```text
Read Gemfile, Gemfile.lock, .ruby-version, config/application.rb, config/ci.rb (if present), .rubocop.yml, spec/rails_helper.rb and spec/spec_helper.rb, and list the directories under app/ and spec/. Write AGENTS.md with: (1) a one-line description naming the Rails and Ruby versions, the database and the test framework; (2) the exact commands for one spec example, failed specs only, lint with safe autocorrect, the full gate and a generator dry run, as they work in THIS repo; (3) a "Definition of done" line; (4) at most eight rules, each one a convention you can see this codebase follows and a generic Rails model would get wrong. Do not restate anything RuboCop already enforces. Run every command you list and tell me which ones failed.
```

Strona o [wspólnych regułach dla agentów](/pl/cto-scorecard-guide/shared-agent-rules/) wyjaśnia, jak utrzymać jedno źródło prawdy, gdy zespół używa wszystkich trzech narzędzi.

## Jak zmusić agenta do używania generatorów Rails zamiast ręcznego pisania plików?

Ręcznie napisana migracja potrafi zepsuć Rails w sposób, którego specyfikacje nie pokażą: znacznik czasu, który sortuje się przed migracjami już obecnymi na produkcji, nadklasa `Migration[7.0]` skopiowana z danych treningowych albo model bez specyfikacji. Generatory tworzą nazwy plików, wersję migracji i szkielety specyfikacji, o które prosi twoja konfiguracja. Flaga `--pretend` pokazuje, co generator by utworzył, niczego nie zapisując, więc to tani krok planowania:

```bash
# terminal: show the plan, write nothing
bin/rails generate model Refund order:references amount_cents:integer reason:string --pretend
```

**Prompt do skopiowania: szkielet funkcji zaczynający się od generatora**

```text
We need a Refund model: belongs to Order, amount_cents integer (not null, > 0), reason string (not null), status string with the values requested, approved and rejected, default requested. First run the bin/rails generate command you intend to use with --pretend and show me its output. Do not write any file by hand that a generator can create. After I approve, run the generator without --pretend, then edit the generated migration to add null: false, the default and a check constraint for amount_cents > 0, and add the model validations and the enum. Run bin/rails db:migrate and bin/rspec spec/models/refund_spec.rb, and show me the diff of db/schema.rb that the migration produced.
```

Ostatnia linia jest ważna: diff `db/schema.rb` to najkrótsze uczciwe podsumowanie tego, co robi migracja. Czytaj jego, a nie kod Ruby.

## Jak prowadzić pętlę spec-first dla endpointu Rails?

Opisz zachowanie, każ agentowi napisać padające request specs, sprawdź, czy padają z właściwego powodu, i dopiero wtedy pozwól mu napisać implementację. Request specs przechodzą przez routing, middleware i bazę danych, więc są wyrocznią najbliższą temu, co widzi użytkownik.

1. **Spisz kryteria akceptacji.** Od trzech do sześciu obserwowalnych zachowań, każde jako zdanie, które spec może sprawdzić. Format pokazuje strona o [kryteriach akceptacji, które agent może zweryfikować](/pl/workflows/plan/acceptance-criteria/).

2. **Poproś wyłącznie o padające specyfikacje.** Użyj pierwszego promptu poniżej. Zatrzymaj agenta, gdy specyfikacje się ładują i padają.

3. **Czytaj błędy, nie kod.** Każdy spec powinien padać na swoim oczekiwaniu (na przykład `expected 201, got 404`), a nie na brakującej fabryce czy błędzie ładowania. Spec, który pada z niewłaściwego powodu, przejdzie też z niewłaściwego powodu.

4. **Poproś o implementację.** Użyj drugiego promptu. Pętla kończy się, gdy przechodzi `bin/ci`, a nie wtedy, gdy agent twierdzi, że skończył.

5. **Sprawdź siłę specyfikacji.** Uruchom `mutant` na zmienionych metodach (zobacz [Skąd wiesz, że specyfikacje agenta złapałyby błąd?](#skąd-wiesz-że-specyfikacje-agenta-złapałyby-błąd)).

**Prompt do skopiowania: padające request specs dla endpointu zwrotów**

```text
We are adding POST /orders/:order_id/refunds (JSON). Acceptance criteria:
1. A valid refund returns 201 with the refund id and status "requested".
2. amount_cents greater than the order's remaining refundable amount returns 422 with an error on amount_cents, and no row is created.
3. A missing or blank reason returns 422 with an error on reason.
4. A refund for another customer's order returns 404, not 403.
5. Listing GET /orders/:order_id/refunds for an order with 5 refunds runs a constant number of queries (the N+1 detector must stay silent).

Write ONLY specs, in spec/requests/refunds_spec.rb, with FactoryBot factories in spec/factories (create any that are missing). Do not create or change anything under app/, config/ or db/. Then run bin/rspec spec/requests/refunds_spec.rb and show me each failure message. Stop there.
```

**Prompt do skopiowania: implementuj, aż bin/ci będzie zielony**

```text
Implement the refunds endpoints so every example in spec/requests/refunds_spec.rb passes. Use bin/rails generate for any new controller or migration. Scope the order lookup through the current customer so criterion 4 holds. Do not modify any file under spec/. Iterate with bin/rspec --only-failures. When you think you are done, run bin/ci and paste its last 20 lines. If a spec still fails, tell me which acceptance criterion the code violates instead of changing the spec.
```

Strona o [ochronie wyroczni](/pl/workflows/test/protect-the-oracle/) wyjaśnia, dlaczego instrukcja „nie zmieniaj spec/” potrzebuje też mechanicznego zabezpieczenia, które dodaje następna sekcja.

## Jak powstrzymać agenta przed ogłoszeniem „gotowe”, zanim specyfikacje przejdą?

Instrukcja w `AGENTS.md` to rada. Hook albo kontrola w CI to bramka. Claude Code dostaje lokalną bramkę z hooka `Stop` poniżej. Codex i Cursor też mają hooki, ale konfiguracje poniżej używają promptu i reguły projektu, więc dla nich bramką pozostaje job CI pod zakładkami.

**Claude Code**

    Hook `Stop` uruchamia się, gdy Claude kończy odpowiedź. Kod wyjścia 2 blokuje zakończenie i pokazuje Claude'owi stderr hooka, więc Claude pracuje dalej. Uruchamiaj tu szybką część bramki, a pełne `bin/ci` (które audytuje też gemy przez sieć) zostaw na koniec zadania i dla CI:

    ```bash title=".claude/hooks/rails-gate.sh"
    #!/usr/bin/env bash
    # Refuse "done" until RuboCop and RSpec pass.
    input=$(cat)
    # Already continuing because of a stop hook: stop and report instead of looping.
    [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ] && exit 0
    cd "$CLAUDE_PROJECT_DIR" || exit 0
    # No changes to code, specs or schema since the branch left main: nothing to check.
    base=$(git merge-base HEAD origin/main 2>/dev/null || echo HEAD)
    [ -z "$(git status --porcelain -- app spec db config lib)" ] &&
      git diff --quiet "$base" -- app spec db config lib && exit 0
    if ! out=$(bin/rubocop 2>&1); then
      echo "RuboCop failed. Fix the code; run bin/rubocop -a for safe fixes; never add rubocop:disable:" >&2
      echo "$out" | grep -E "^[^ ].+:[0-9]+:[0-9]+: " | head -30 >&2
      exit 2
    fi
    if ! out=$(bin/rspec 2>&1); then
      echo "RSpec failed. Fix app/, never spec/. Re-run with bin/rspec --only-failures:" >&2
      echo "$out" | tail -40 >&2
      exit 2
    fi
    exit 0
    ```

    Skrypt potrzebuje `jq`. Ponieważ kończy się kodem 0, gdy `stop_hook_active` ma wartość `true`, nieudana bramka wymusza jedną ponowną próbę, a potem Claude kończy i raportuje, zamiast krążyć w pętli nad specem, który nie może przejść. Warunek pomija przebieg, gdy nic w `app`, `spec`, `db`, `config` ani `lib` nie różni się od `origin/main`, niezależnie od tego, czy zmiana jest niezatwierdzona, czy już zatwierdzona w commicie; jeśli domyślna gałąź nazywa się inaczej, zmień `origin/main`. Strona o [automatyzacji hookami](/pl/claude-code/automate/hooks-automation/) wyjaśnia, jak liczyć próby, jeśli chcesz więcej niż jedną, i opisuje pozostałe zdarzenia.

    Zarejestruj go w ustawieniach projektu i nadaj skryptowi prawo wykonania (`chmod +x`):

    ```json title=".claude/settings.json"
    {
      "hooks": {
        "Stop": [
          {
            "hooks": [
              { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/rails-gate.sh", "timeout": 600 }
            ]
          }
        ]
      }
    }
    ```

    Przy dużym zestawie zastąp `bin/rspec` plikami specyfikacji odpowiadającymi zmienionym plikom, a pełny przebieg zostaw w CI.

**Codex**

    `bundle install` potrzebuje sieci, a sandbox `workspace-write` nie ma dostępu do sieci, dopóki go nie włączysz. Zainstaluj gemy wcześniej, poza agentem, a potem uruchom pętlę bez sieci:

    ```bash
    bundle install
    codex exec --sandbox workspace-write "Implement the refunds endpoints so every example in spec/requests/refunds_spec.rb passes. Do not modify spec/. Finish only when 'bin/rubocop' and 'bin/rspec' both pass; print the last lines of each."
    ```

    Testowa baza SQLite to plik w katalogu roboczym, więc działa w sandboksie. Jeśli specyfikacje potrzebują serwera PostgreSQL, a sandbox blokuje połączenie, uruchamiaj specyfikacje bazodanowe w CI, a lokalnej pętli daj tylko specyfikacje modeli. Jeśli zadaniem jest dodanie gemu, włącz sieć tylko dla tego jednego przebiegu przez `-c sandbox_workspace_write.network_access=true`.

    Prompt to nadal instrukcja: nic nie przeszkodzi przebiegowi skończyć się z czerwonymi specyfikacjami. Jeśli chcesz lokalnej bramki, uruchamiaj te same kontrole RuboCop i RSpec z hooka `Stop` w Codex (`hooks` to stabilna funkcja w 0.157.1; sprawdzisz ją przez `/hooks`, a hooki wymagają utrwalonego zaufania). W przeciwnym razie mechaniczną bramką dla Codex jest job CI poniżej.

**Cursor**

    Wklej prompt implementacyjny do agenta, najpierw w Plan Mode, jeśli zmiana dotyka jednocześnie modeli, kontrolerów i migracji. Umieść definicję ukończenia w regule projektu, żeby agent uruchomił `bin/ci`, zanim zgłosi wynik. Mechaniczna bramka dla Cursora działa po otwarciu pull requesta: to job CI poniżej plus Bugbot, jeśli twój zespół używa go do review.

Niezależnie od tego, co działa lokalnie, decyduje bramka w CI. Uruchom tam te same kontrole z tokenem tylko do odczytu i jednorazową usługą PostgreSQL:

```yaml title=".github/workflows/rails-gates.yml"
name: rails-gates
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
permissions:
  contents: read
jobs:
  gates:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_HOST_AUTH_METHOD: trust  # disposable CI database, no credential
        ports: ["5432:5432"]
        options: --health-cmd="pg_isready" --health-interval=10s --health-timeout=5s --health-retries=3
    env:
      RAILS_ENV: test
      DATABASE_URL: postgres://postgres@localhost:5432/shop_test
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
          fetch-depth: 2   # the PR merge commit and its base parent
      - name: Existing specs unchanged
        if: ${{ !contains(github.event.pull_request.labels.*.name, 'spec-change-approved') }}
        run: |
          changed=$(git diff --name-only --diff-filter=MDR HEAD^1 HEAD -- spec/)
          if [ -n "$changed" ]; then
            echo "Existing specs modified, moved or deleted; a reviewer must add the spec-change-approved label:"
            echo "$changed"
            exit 1
          fi
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - run: bin/rubocop
      - run: bin/bundler-audit
      - run: bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error
      - run: bin/rails db:create db:migrate
      - run: git diff --exit-code db/schema.rb   # migrations and schema.rb agree
      - run: bin/rails db:migrate:redo STEP=1     # newest migration is reversible
      - run: bin/rspec
```

Krok „Existing specs unchanged” pada, gdy pull request modyfikuje, przenosi lub usuwa plik, który już istnieje w `spec/`, więc agent nie przesunie po cichu oczekiwanej wartości ani nie usunie padającego speca; nowe pliki specyfikacji przechodzą. Po przejrzeniu zmiany w specyfikacji człowiek dodaje etykietę `spec-change-approved`, co uruchamia nowy przebieg pomijający ten krok (ponowne uruchomienie starego joba nie zadziała, bo korzysta z pierwotnego zdarzenia i nie widzi etykiety). Krok jest bramką tylko wtedy, gdy pull request nie może go usunąć: GitHub uruchamia plik workflow z samego pull requesta, więc obejmij `/.github/` regułą `CODEOWNERS` i wymuś tę recenzję przez ochronę gałęzi lub ruleset. Krok z `git diff` pada, gdy agent poprawił `db/schema.rb` ręcznie albo zacommitował migrację bez schematu, który ona tworzy.

## Jak wyłapać zapytania N+1 w kodzie Rails pisanym przez agenta?

Agenci łatwo piszą pętlę N+1, bo `@orders.each { |o| o.customer.name }` to poprawny Ruby, a każdy spec z jednym rekordem przechodzi. Rozwiązaniem jest detektor, który zamienia ten wzorzec w padający spec. Każdy wiersz poniżej przetestowaliśmy na Rails 8.1.4 2026-09-26:

| Detektor | Konfiguracja | Co złapał w naszym teście | Wybierz go, gdy |
| --- | --- | --- | --- |
| Bullet 8.2.0 | `Bullet.enable`, `Bullet.raise = true` w `config/environments/test.rb` | Pętlę `order.customer` w request specu, na SQLite, z poprawką w komunikacie: `Add to your query: .includes([:customer])` | Dowolna baza, także domyślne w Rails 8 SQLite. Request specs działają przez jego middleware Rack; specyfikacje modeli wymagają `Bullet.start_request` i `Bullet.end_request` wokół każdego przykładu |
| Prosopite 2.2.0 | `Prosopite.raise = true`, `Prosopite.scan` i `Prosopite.finish` wokół każdego przykładu oraz gem `pg_query`, chyba że używasz MySQL lub MariaDB | Tę samą pętlę na SQLite, ale jako `PgQuery::ParseError: syntax error at or near "LIMIT"` zamiast raportu N+1 | PostgreSQL lub MySQL. Wykrywa powtarzające się identyczne zapytania, więc łapie też N+1, które nie idą przez asocjację |
| `strict_loading` (wbudowany) | `Order.strict_loading` na relacji albo `self.strict_loading_by_default = true` w modelu | Pętlę, jako `ActiveRecord::StrictLoadingViolationError`, gdy ustawiony na relacji. Przy `strict_loading_by_default = true` i `strict_loading_mode = :n_plus_one_only` nie zgłosił żadnej z pętli, które sprawdziliśmy | Nowe modele i gorące zapytania, w których każde leniwe ładowanie to błąd, także dla pojedynczego rekordu |

Dla większości zespołów pierwszą bramką jest Bullet w środowisku testowym, a `strict_loading` na relacjach stojących za najbardziej obciążonymi stronami:

```ruby title="config/environments/test.rb"
Rails.application.configure do
  config.after_initialize do
    Bullet.enable = true
    Bullet.bullet_logger = true
    Bullet.raise = true # an N+1 in any request spec fails that spec
  end
  # ...
end
```

Detektor reaguje tylko wtedy, gdy spec ładuje więcej niż jeden rekord, więc do każdej akcji index dodaj przykład z kolekcją. Kryterium 5 w prompcie o zwrotach to właśnie taki przykład.

**Prompt do skopiowania: znajdź i napraw N+1 w akcjach index**

```text
Bullet raises on N+1 queries in the test environment. For every controller action under app/controllers that renders a collection (index actions, and any view that iterates over an association), check spec/requests for an example that creates at least three records with the associations the view touches. Add the missing examples first and run them: each N+1 must fail with Bullet::Notification::UnoptimizedQueryError. Then fix each one with includes, preload or eager_load, choosing the one Bullet suggests unless the view filters on the association. Do not set Bullet.raise to false, do not add Bullet safelist entries, and do not change the new examples to create fewer records. Show me the Bullet messages before and the bin/rspec result after.
```

Bazodanową stronę tego samego problemu, w tym plany `EXPLAIN` i indeksy, opisują strony o [wzorcach SQL](/pl/cookbook/database-recipes/sql-patterns/) i [wzorcach ORM](/pl/cookbook/database-recipes/orm-patterns/).

## Jak obsługiwać migracje Rails z agentem?

Zielony zestaw specyfikacji to za mało dowodów dla migracji. Agent może napisać migrację, która czysto przechodzi na pustej bazie testowej, a mimo to blokuje dużą tabelę albo psuje działającą aplikację w trakcie wdrożenia. Klasyczny przypadek: agent zmienia nazwę kolumny przez `rename_column`, specyfikacje przechodzą, a serwery aplikacji z jeszcze starym kodem rzucają błędy przy każdym zapytaniu używającym starej nazwy, dopóki wdrożenie się nie skończy.

`strong_migrations` zamienia takie przypadki w błąd podczas `bin/rails db:migrate`, z bezpieczną alternatywą w komunikacie. Obsługuje PostgreSQL, MySQL i MariaDB (nie SQLite). Zainstaluj go przez `bundle add strong_migrations` i `bin/rails generate strong_migrations:install`. Usunięcie kolumny na przykład kończy się błędem z instrukcją: dodaj kolumnę do `self.ignored_columns`, wdróż, a dopiero potem usuń ją wewnątrz `safety_assured { ... }`.

Resztę pracy podziel między bramki i człowieka:

| Kontrola | Jak | Kto decyduje |
| --- | --- | --- |
| Niebezpieczna operacja | `strong_migrations` rzuca błąd przy migracji | CI, a agent czyta komunikat |
| Schemat i migracje się zgadzają | `bin/rails db:migrate` na świeżej bazie, potem `git diff --exit-code db/schema.rb` | CI |
| Najnowsza migracja jest odwracalna | `bin/rails db:migrate:redo STEP=1` | CI (`bin/ci` i workflow powyżej) |
| Zmiana jest tym, czego oczekujesz | Diff `db/schema.rb` dołączony do pull requesta | Człowiek czyta diff schematu, nie kod Ruby |
| `safety_assured`, migracje niszczące dane lub uzupełniające dane | `CODEOWNERS` na `db/migrate/` | Człowiek |

**Prompt do skopiowania: zmiana nazwy kolumny bez przestoju**

```text
Rename orders.notes to orders.customer_notes without downtime, as an expand-and-contract change in separate pull requests. In THIS pull request do only the expand step: generate a migration that adds customer_notes, write to both columns from the model, backfill existing rows in batches with in_batches in a separate migration, and read from customer_notes with a fallback to notes. Do not remove or rename notes and do not use safety_assured. Run bin/rails db:migrate, bin/rails db:migrate:redo STEP=1 and bin/rspec. Show me the db/schema.rb diff and list every statement that could lock the orders table, or say "none". Then write the steps for the contract pull request as a checklist in the PR description.
```

Szersze zasady zmian expand-and-contract i wycofywania opisuje strona o [wzorcach migracji baz danych](/pl/cookbook/database-recipes/migration-patterns/).

## Skąd wiesz, że specyfikacje agenta złapałyby błąd?

Zielony przebieg nie mówi, czy specyfikacje padłyby, gdyby kod był błędny, a specyfikacje napisane przez tego samego agenta, który napisał kod, najczęściej mają te same ślepe punkty. Na to pytanie odpowiadają testy mutacyjne: `mutant` wprowadza drobne zmiany w testowanym kodzie i zgłasza każdą, której specyfikacje nie zauważyły.

W aplikacji testowej jeden spec dla `Order#large?` (`total_cents >= 10_000`) przechodził, a `mutant` zgłosił 7 przeżywających mutacji na 18, czyli pokrycie 61,11%. Pierwszą ocalałą była granica: `total_cents > 10000`. Żaden spec nie sprawdzał zamówienia na dokładnie 10 000 centów.

```bash
# terminal: mutation-test only the subjects changed since main
bundle exec mutant run --integration rspec --usage opensource \
  --require ./config/environment --since main -- 'Order*'
```

Dodaj `mutant-rspec` do grupy `:development, :test` z `require: false`. `mutant` jest darmowy dla projektów open source (`--usage opensource`); prywatny, komercyjny kod wymaga płatnej subskrypcji i `--usage commercial`. Uruchamiaj go na zmienionych elementach, a nie na całej aplikacji, bo każda mutacja ponownie uruchamia wybrane specyfikacje. Strona o [sile wyroczni](/pl/workflows/test/oracle-strength/) wyjaśnia, jak zamienić ocalałe mutacje w brakujące przykłady.

**Prompt do skopiowania: zamień ocalałe mutacje w brakujące specyfikacje**

```text
Run: bundle exec mutant run --integration rspec --usage opensource --require ./config/environment --since main -- 'Refund*' 'RefundsController*'
For each surviving mutation, decide: (A) the mutated code is equally correct and the original is redundant, or (B) a spec is missing. For every B, add one example to the existing spec file that fails against the mutated code and passes against the original. Do not change anything under app/. Re-run mutant and show me the before and after Alive counts, and list any A cases for me to decide.
```

## Jak dać agentowi nawigację po kodzie, która rozumie Rails?

Wyszukiwanie tekstowe znajdzie `def total`, ale nie każde użycie asocjacji, scope'a czy helpera ścieżki. W Rails najbardziej pomagają dwa dodatki: serwer językowy, który rozumie Ruby, i serwer MCP, który czyta trasy, schemat i relacje modeli.

**Ruby LSP.** Serwer językowy Shopify (gem `ruby-lsp`, 0.26.11) automatycznie dołącza swój dodatek dla Rails, gdy wykryje aplikację Rails. W Claude Code rejestruje go plugin `ruby-lsp` z oficjalnego marketplace'u; plugin nie zawiera samego programu. Pluginy LSP nie dodają stałego kontekstu, bo serwer działa w osobnym procesie.

**Rails MCP Server.** Gem `rails-mcp-server` (2.0.0) udostępnia trzy narzędzia — `switch_project`, `search_tools` i `execute_tool` — a za nimi analizatory takie jak `get_routes`, `get_schema` i `analyze_models`. Z flagą `--single-project` obsługuje bieżący katalog bez pliku `projects.yml`. Popularność: 261 700 pobrań łącznie na rubygems.org (odczyt 2026-09-26). To projekt społecznościowy, więc przeczytaj jego kod, zanim dasz mu dostęp do produkcyjnej bazy. Stały koszt definicji narzędzi w kontekście jest niewielki; analizatory ładują się dopiero wtedy, gdy wywołasz je przez `execute_tool`.

**Claude Code**

    ```bash
    # terminal
    gem install ruby-lsp
    claude plugin install ruby-lsp@claude-plugins-official
    gem install rails-mcp-server
    claude mcp add rails -- rails-mcp-server --single-project
    ```

**Codex**

    ```bash
    # terminal, from the app's root
    gem install rails-mcp-server
    codex mcp add rails -- rails-mcp-server --single-project
    ```

**Cursor**

    Dodaj serwer MCP do `.cursor/mcp.json` w katalogu głównym aplikacji:

    ```json
    { "mcpServers": { "rails": { "command": "rails-mcp-server", "args": ["--single-project"] } } }
    ```

Bez nich agent szuka grepem `has_many :refunds` i pomija scope zdefiniowany w concernie. Z nimi jeden prompt wyznacza zasięg zmiany, zanim cokolwiek zostanie edytowane:

**Prompt do skopiowania: zmapuj zmianę przed edycją**

```text
Using the rails MCP server and the language server, find every route, controller action, model scope, job and view that reads or writes orders.status. Show the list with file and line, and mark which ones have a spec that exercises them. Do not change files.
```

Strona o [serwerach MCP do analizy kodu](/pl/ecosystem/mcp/code-intelligence-mcp/) porównuje rozwiązania oparte na serwerach językowych i na indeksach dla większych baz kodu.

## Co się psuje, gdy agenci piszą kod Rails?

**Prosopite zgłasza PgQuery::ParseError na SQLite**

Objaw: spec pada z `PgQuery::ParseError: syntax error at or near "LIMIT"` z wnętrza Prosopite. Przyczyna: Prosopite rozpoznaje zapytania parserem PostgreSQL `pg_query`, a placeholdery `?` z SQLite się nie parsują; to zamaskowane N+1 (Prosopite 2.2.0, pg_query 6.2.3, sprawdzone 2026-09-26). Wyjście: na SQLite używaj Bullet, a na Prosopite przejdź, gdy aplikacja działa na PostgreSQL lub MySQL.

**strict_loading jest włączony i nic nie zgłasza**

Objaw: ustawione jest `config.active_record.strict_loading_mode = :n_plus_one_only`, a oczywista pętla N+1 nadal przechodzi. Przyczyna: przy włączonym strict loading ten tryb zgłasza tylko część zagnieżdżonych leniwych ładowań; na Rails 8.1.4 nie zgłosił żadnej z pętli najwyższego poziomu, które sprawdziliśmy. Wyjście: wywołaj `strict_loading` na relacji (`Order.strict_loading.includes(...)`) albo zostaw domyślny tryb `:all` w modelach, w których każde leniwe ładowanie to błąd, a resztę pilnuj Bulletem.

**Agent edytuje db/schema.rb albo starą migrację**

Objaw: na gałęzi schemat wygląda dobrze, a na produkcji brakuje kolumny albo baza kolegi rozjeżdża się z kodem. Przyczyna: agent poprawił wygenerowany plik, zamiast dodać migrację. Wyjście: łapie to krok `git diff --exit-code db/schema.rb` w CI; ponów prompt: „Revert your edits to db/schema.rb and db/migrate/*, generate a new migration for the change, run bin/rails db:migrate and commit the schema it produces.”

**Migracja przechodzi lokalnie i pada na redo**

Objaw: `bin/ci` pada na kroku odwracalności z `ActiveRecord::IrreversibleMigration`. Przyczyna: `remove_column` bez typu, `change_column` albo `execute` wewnątrz `change`. Wyjście: „Rewrite the migration with separate up and down methods, or pass the column type to remove_column so change can reverse it. Run bin/rails db:migrate:redo STEP=1 until it passes.”

**Spec zmieniony tak, by pasował do błędu**

Objaw: diff dotyka `spec/` w tym samym commicie, który poprawia `app/`, a oczekiwana wartość się przesunęła. Przyczyna: agent optymalizował pod zielony wynik. Wyjście: obejmij `spec/` regułą `CODEOWNERS`, trzymaj linię „nie zmieniaj spec/” w każdym prompcie implementacyjnym i zostaw w jobie CI powyżej krok „Existing specs unchanged”. Pozostałe mechaniczne opcje opisuje strona o [ochronie wyroczni](/pl/workflows/test/protect-the-oracle/).

**Wyciszenia zamiast poprawek**

Objaw: bramki są zielone, a diff dodaje `# rubocop:disable`, wpis w `config/brakeman.ignore`, wpis na liście wyjątków Bulleta albo `safety_assured`. Wyjście: przypisz tym plikom i wzorcom właściciela-człowieka w `CODEOWNERS` i ponów prompt: „Remove the suppression you added and fix the underlying offense. If it is a false positive, explain why in the pull request instead.”

## Dokąd dalej z Rails i agentami

- [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) — Jak nie dać agentom edytować specyfikacji, które ich oceniają.
- [Wzorce migracji baz danych](/pl/cookbook/database-recipes/migration-patterns/) — Zmiany expand-and-contract i wycofywanie dla migracji z tej strony.
- [Wzorce tworzenia API](/pl/cookbook/backend-recipes/api-patterns/) — Klucze idempotencji, paginacja i kontrakty dla budowanych endpointów.
- [Receptury dla Pythona](/pl/cookbook/backend-recipes/python-patterns/) — Te same bramki i pętle dla Django i FastAPI.
- [Pakiet dowodów](/pl/workflows/ship/evidence-bundle/) — Dołącz wyniki bramek i diff schematu, żeby recenzent sprawdzał dowody, a nie kod.
- [Kod gotowy na agentów](/pl/workflows/harness/agent-ready-codebase/) — Cechy repozytorium, które czynią każdego agenta bardziej niezawodnym.
