Triage halucynacji i analiza przyczyny źródłowej

1. Przegląd koncepcji i problem systemowy

Gdy agent wywołuje nieistniejącą metodę lub korzysta z biblioteki, której nie ma w projekcie, typową reakcją niedoświadczonego „vibe-coder” jest gniew i emocjonalne okrzyki na czacie: „Jesteś głupi?! Mówiłem, żeby używać Drizzle, a nie Prisma!”.

• Prowadzi to do zaśmiecania kontekstu czatu emocjonalnym szumem.
• Model zaczyna przepraszać, ale nadal popełnia błędy, ponieważ przyczyna źródłowa nie została usunięta.

Hallucination Triage to chłodne, inżynierskie podejście: traktowanie halucynacji modelu nie jako „głupoty AI”, lecz jako defektu systemu dostarczania kontekstu (Context Delivery Bug), który podlega klasyfikacji i systematycznej naprawie.

2. Taksonomia architektoniczna i model mentalny

┌─────────────────────────────────────────────────────────────┐
│                 MATRYCA TRIAGE HALUCYNACJI                  │
├─────────────────────────────────────────────────────────────┤
│ 1. DETEKCJA: Model wygenerował wymyśloną metodę lub typ     │
│    • Przykład: `db.user.findFirstOrThrow()` w Drizzle ORM   │
├─────────────────────────────────────────────────────────────┤
│                          │                                  │
│                          ▼ DIAGNOSTYKA PRZYCZYŃ GŁÓWNYCH    │
│    ┌───────────────────────────────────────────────────┐    │
│    │ Typ A: Brak pliku? ➔ Model nie widział schemy     │    │
│    │ Typ B: Konflikt reguł? ➔ W regułach wspomniano Prisma│ │
│    │ Typ C: Przestarzałe dane treningowe? ➔ Wiedza modelu z 2023 r. │ │
│    └───────────────────────────────────────────────────┘    │
│                          │                                  │
│                          ▼ SYSTEMOWA NAPRAWA                │
│ 1. Dodać dokładny plik typów do promptu                    │
│ 2. Ustalić zakaz w regułach: "NEVER use Prisma syntax"     │
│ 3. Dodać walidację kompilatorem `tsc --noEmit`             │
└─────────────────────────────────────────────────────────────┘

3. Praktyczne scenariusze inżynierskie w środowisku produkcyjnym

01. Eliminacja halucynacji poprzez pliki deklaracji

Agent stale wymyślał propsy dla wewnętrznego komponentu przycisku. Zamiast tłumaczyć sytuację, programista utworzył plik src/components/ui/button.d.ts z precyzyjnymi typami TypeScript i dodał go do listy automatycznego kontekstu. Błędy zniknęły w 100%.

02. Protokół „Post-Mortem dla błędów AI”

Po rozwiązaniu złożonego buga inżynier poświęca 2 minuty na aktualizację pliku .agents/rules/learnings.md: „W tym projekcie router Next.js wykorzystuje Server Actions bez ręcznych wywołań fetch. Nie generuj zbędnych handlerów routingu dla prostych mutacji”.

4. Pułapki, typowe błędy i bezpieczeństwo

• Over-Correction (Nadkompensacja): Próbując naprawić jedną drobną halucynację, inżynier pisze gigantyczną regułę liczącą 50 linii wielkimi literami, która zabrania modelowi korzystania z przydatnych wzorców powiązanych. Reguły muszą być chirurgicznie precyzyjne.
• Ignorowanie wersji modeli: Jeśli model ma zbyt niską zdolność rozumowania (np. przestarzały model 3B), żaden triage nie pomoże mu rozwiązać złożonych zadań. Czasem jedynym lekarstwem jest zmiana modelu na bardziej zaawansowany.

5. Strategiczny wniosek dla inżyniera roku 2026

Halucynacja to lustro jakości Waszej dokumentacji inżynierskiej. Jeśli model halucynuje, oznacza to, że Wasz system był niewystarczająco deterministyczny. Systematyczny triage zamienia każdy błąd w cegiełkę fundamentu niezawodności Waszego repozytorium.