Jak sprawiłem, że AI przestało halucynować w naszej bazie kodu
Narzędzia AI do kodowania zawodzą w prawdziwych projektach produkcyjnych. Dobrze radzą sobie z nowym kodem, ale rozkładają się na starym kodzie z historią.
Nasz projekt fintech ma trzyletnią historię. Posiada dwa frontendy w React, panel administracyjny oraz backend w FastAPI. Baza danych jest złożona, z wieloma tabelami i ciężkimi złączeniami.
Próbowaliśmy wykorzystać AI, aby przyspieszyć pracę. To się nie udało.
Poprosiłem AI o stworzenie tabeli kontaktów. Stworzyło nowe kolumny dla imion i adresów e-mail. Nie zauważyło, że mamy je już w tabeli użytkowników. Zduplikowało dane zamiast użyć klucza obcego.
AI nie było głupie. Nie miało kontekstu. Podjęło decyzję na podstawie niepełnych informacji.
Przestałem pytać, jak uzyskać lepszy kod. Zacząłem pytać, jakiego kontekstu AI potrzebuje, aby podejmować dobre decyzje.
Zbudowaliśmy ustrukturyzowany przepływ pracy. AI jest tak dobre, jak kontekst, który mu dostarczysz. Sprawiliśmy, że ten kontekst stał się jawny.
Oto nasza konfiguracja:
- Katalog ADR: Stworzyliśmy folder na Architecture Decision Records. Pliki te wyjaśniają, dlaczego podejmujemy konkretne decyzje. Jeden z plików instruuje AI, aby przed tworzeniem nowych tabel sprawdzało już istniejące. Zabrania on duplikowania danych użytkowników.
- context.md: Ten plik wyjaśnia nasze specyficzne terminy. Informuje AI, jak nasze unikalne pojęcia odnoszą się do siebie nawzajem.
- plot.md: Zapewnia wysokopoziomową mapę projektu i pokazuje, jak poszczególne elementy są ze sobą połączone.
- Obowiązkowe testy: Każda nowa trasa API wymaga przypadków testowych.
To zmieniło wszystko. Raz AI zmieniło wspólną funkcję pomocniczą. Zmiana ta zepsuła osiem innych części systemu. Zestaw testów natychmiast to wykrył. AI zobaczyło błąd i naprawiło własną pomyłkę, tworząc wersję obsługującą zarówno stare, jak i nowe wymagania.
Bez testów ten błąd trafiłby na produkcję.
Traktuj AI jak nowego programistę. Nie obwiniasz nowego pracownika za to, że nie zna twojej bazy kodu. Zapewniasz mu dokumentację i onboarding. Zrobiliśmy to samo dla AI.
Nasza struktura:
- docs/context.md: Terminy projektowe i powiązania.
- docs/plot.md: Wysokopoziomowa mapa bazy kodu.
- docs/adr/: Konkretne reguły, takie jak tworzenie tabel i struktura API.
Trzy zasady dla twojego zespołu:
- Bądź konkretny w ADR-ach. Używaj jasnych instrukcji zamiast ogólnikowych porad.
- Spraw, aby dokumentacja była wiążąca. Powiedz AI, że te reguły mają pierwszeństwo.
- Zamieniaj błędy w reguły. Za każdym razem, gdy AI zawiedzie, napisz nowy ADR.
Ten system nie czyni AI doskonałym. Sprawia, że AI staje się przewidywalne. Chcemy bazy kodu, w której AI jest spójne, dzięki czemu zespół może pracować szybciej.