Gdy zaczynasz nowy projekt od zera, programowanie z AI wydaje się czystą magią. Wpisujesz prompt, a model bez wahania generuje czysty komponent albo działający endpoint backendu.
Jednak wraz ze wzrostem bazy kodu przychodzi twarde otrzeźwienie.
Około 100 000 linii kodu zwykła AI zaczyna wyraźnie tracić oddech. Próbuje zgadywać, przeszukuje repozytorium po omacku i halucynuje nieistniejące funkcje. Około 300 000 linii samodzielny osąd modelu praktycznie się załamuje: okno kontekstu nie wystarcza, klasyczne grepowanie całego projektu spala tysiące tokenów, a rozwój zamienia się w niekończący się cykl naprawiania zepsutego kodu.
Właśnie w tym miejscu stery przejmują kontrakty systemowe.
Czym jest kontrakt w AITM?
Kontrakt to nie zwykły komentarz w kodzie ani linijka w zapomnianym README.md, która po dwóch sprintach przestaje być prawdą.
To zachowanie systemu odpytywalne maszynowo.
Dokładnie opisuje, co ma robić dana część aplikacji, i wskazuje konkretne pliki źródłowe, testy oraz elementy interfejsu. Zamiast błądzić i czytać dziesiątki plików, agent zadaje systemowi bezpośrednie pytanie: "Gdzie i jak jest zaimplementowane to zachowanie?" i od razu dostaje precyzyjną odpowiedź.
Każdy kontrakt w AITM opiera się na trzech kluczowych filarach:
- behavior: Jednolinijkowa esencja tego, co robi kod. Najważniejsze ze wszystkich pól. Agent porównuje tę regułę z faktyczną implementacją w pliku. Jeśli pojawi się sprzeczność, system od razu wie, że chodzi albo o błąd, albo o nieaktualny kontrakt.
- confidence: Miara wiarygodności informacji. Mówi, jak niezawodny jest opis względem pozostałych danych w systemie (np. czy zachowanie zostało zweryfikowane prawdziwymi testami).
- variables: Powiązanie ze wspólnym językiem komunikacji systemu (np.
BL.PIPELINE). Działa jak most między logiką biznesową we frontendzie i backendzie, dzięki czemu kontrakty można błyskawicznie filtrować według konkretnej części interfejsu lub warstwy danych.
Prawdziwy przykład z produkcji
W AITM kontrakt jest ustrukturyzowany i od razu dostępny przez API GraphQL:
contractsForFile(path: "src/pipeline/MergeQueueService.ts", projectId: "ctm-dashboard") {
id # "GM-057"
module # "Git/Merge"
behavior # "Restart po self-merge jest ręczny: po merge dev-watch nadal serwuje kod sprzed merge, dopóki użytkownik nie kliknie Restart w menu albo Settings.selfMergeRestartMode nie ma wartości 'auto'."
confidence # "tested"
}
To zasadnicza różnica w porównaniu ze statyczną dokumentacją. Agent żąda kontraktu, zanim w ogóle otworzy lub napisze choćby jedną linijkę kodu. Nie działa na ślepo, nie marnuje kontekstu i dokładnie wie, jaką wagę przypisać regule.
Oszczędzamy tokeny i czas obliczeń: Claude Sonnet na niskim lub średnim effort
Jedną z największych korzyści precyzyjnego prowadzenia przez kontrakty jest wydajność samego modelu AI.
W AITM nasi agenci pracują na modelu Claude Sonnet z ustawieniem effort (thinking) od niskiego do średniego. Gdy model ma do dyspozycji precyzyjny kontrakt, nie potrzebuje minut "myślenia", spekulowania o architekturze całego repozytorium ani spalania ogromnego budżetu reasoningu na trywialne poszukiwania.
Dzięki kontraktowi model dostaje do ręki gotową mapę:
- Wie dokładnie, do którego pliku iść.
- Zna oczekiwane zachowanie (
behavior). - Wie, na ile ufać informacji (
confidence).
Nawet przy niższym effort Claude Sonnet wykonuje więc w pełni deterministyczną i czystą pracę, bo nie musi polegać na własnym "domyśle", lecz ściśle trzyma się zadanej specyfikacji.
Wynik na 500K linii kodu
Prawdziwa siła tego podejścia nie ujawnia się w pierwszych dniach projektu, lecz wtedy, gdy baza kodu osiąga rozmiary enterprise.
W naszym własnym systemie, liczącym ponad 500 000 linii kodu, działa dziś niezawodnie około 3 500 kontraktów:
- Koniec ze ślepym grepowaniem: Agent nie przeszukuje setek plików, tylko idzie prosto do pewnego miejsca.
- Radykalna redukcja tokenów i halucynacji: Okno kontekstu pozostaje czyste, a model nie cierpi z powodu przeładowania informacjami.
- Spójne wyniki: Nawet w projekcie liczącym pół miliona linii AI osiąga taką samą szybkość i dokładność jak przy pierwszym prompcie w pustym repozytorium.