agentic-codemod-pipeline/docs/adr/0002-podzial-na-krok-deterministyczny-i-model.md

ADR-0002: Deterministycznie tyle, ile się da; model tylko na resztę

• Status: przyjęty
• Data: 2026-08-28

Kontekst

Migracja SDK to w większości mechaniczne podmiany. Powierzenie ich modelowi kosztuje tokeny, wydłuża przebieg i wprowadza wariancję tam, gdzie wariancja jest czystą stratą - nikt nie chce, żeby dwa uruchomienia dawały inny diff dla tej samej zmiany nazwy metody.

Decyzja

Dzielimy pracę wzdłuż linii "czy da się to zrobić kodem":

1. Wykrycie ekosystemu, plików zależności i komendy testowej - adapter (adapters/).
2. Podbicie deklaracji wersji - adapter.
3. Migracja objęta regułami - silnik reguł czytający *.codemod.yaml z pakietu APM.
4. Reszta - agent coder z LLM.
5. Ocena wyniku - agent reviewer oraz niezależna kontrola mechaniczna.

Reguły codemod są częścią pakietu APM (leżą obok notatki migracyjnej), więc podlegają temu samemu przeglądowi i wersjonowaniu co wiedza dla modelu.

Konsekwencje

Pozytywne

• Powstaje tryb --offline: ta sama topologia bez modelu. Smoke test całego pipeline'u na każdym MR, bez GPU i bez internetu.
• Punkt odniesienia: widać, ile przypadków model faktycznie dołożył ponad reguły.
• Mniejszy koszt i krótszy przebieg dla typowych migracji.

Negatywne

• Dwie ścieżki do utrzymania (RuleBrain, LlmBrain) i wspólny kontrakt między nimi.
• Reguły regexowe mają znane ograniczenia (zmiany strukturalne, wieloliniowe konteksty). Świadomie nie budujemy własnego silnika AST - od tego są narzędzia dziedzinowe (OpenRewrite, jscodeshift), które można podpiąć jako kolejny adapter.