Pętla lokalnego agenta kodującego: Aider, Ollama, drzewa prac Git oraz proste odwracanie zmian.

Zacznij od drogi powrotnej, a model wybierz później. Lokalny agent kodujący zasługuje na swoje miejsce, gdy potrafi zakończyć jeden mały, ograniczony pętlę: zlokalizować błąd, wprowadzić niewielką zmianę, uruchomić odpowiednią weryfikację i pozostawić różnicę, którą można zapisać lub usunąć.

Konserwatywny zestaw narzędzi dla tej pętli zakłada repozytorium już zarządzane przez Git z precyzyjnym poleceniem testowym:

• Agent: Aider
• Czas działania modelu: Ollama, serwujący model na lokalnym komputerze
• Izolacja: drzewo robocze Git
• Poszukiwanie: rg, uruchamiane z korzenia repozytorium
• Walidacja: dowolne precyzyjne polecenie testowe już istniejące w repozytorium
• Odbudowa: git diff, a następnie albo zapisanie zmian, albo git restore

Tylko agent i lokalny środowisko wykonawcze są nowe. Wszystko inne to zwykłe narzędzia do zarządzania repozytorium, a konfiguracja nie powinna przerodzić się w drugą platformę rozwojową.

Rolę są proste. Ollama serwuje model. Aider działa wewnątrz repozytorium Git. Worktree umożliwia wyodrębnienie zadania, zwykle na dedykowanej gałęzi, a git restore pozwala przywrócić niezapisane zmiany do określonych plików. Ten model jest celowo ograniczony i przeznaczony do pracy z repozytorium, która musi pozostać poddawalna recenzji i możliwa do odwrócenia. Nie jest to żaden standard oceny, ani nie twierdzi się, że te narzędzia przewyższają alternatywy we wszystkich przypadkach. Polecenia, nazwy modeli oraz zachowanie zatwierdzania zmieniają się również w zależności od zainstalowanych wersji i lokalnej konfiguracji.

Pętla, którą można przejrzeć

Wynik działania agenta powinien stanowić małą jednostkę postępu, którą programista może sprawdzić. Szeroki, niekontrolowany dostęp do maszyny jest jego przeciwieństwem.

Sekwencja:

1. Stwórz izolowany drzewo robocze.
2. Znajdź implementację oraz istniejący test dla niej.
3. Zdefiniuj jeden wynik i jego granice.
4. Zapytaj o plan przed jakąkolwiek modyfikacją.
5. Zatwierdź plan lub go dostosuj.
6. Przeczytaj różnice.
7. Zrób sprawdzenie projektu.
8. Zapisz zmiany lub przywróć stan poprzedni.

Bramy kontrolne są proceduralne: nic nie jest edytowane przed zatwierdzeniem planu, a żadna zmiana nie zostaje zachowana przed przeczytaniem różnic i testu. Nazywaj je kontrolami technicznymi tylko wtedy, gdy zainstalowany agent i konfiguracja hosta faktycznie mogą je egzekwować. Szybkość ma znaczenie tylko wtedy, gdy wyniki są łatwe do weryfikacji i cofnięcia.

Przykład: puste nazwy wyświetlania

Załóżmy usługę typu TypeScript, która akceptuje puste nazwy wyświetlania, mimo że API powinno je odrzucić. W repozytorium znajduje się specjalny plik testowy oraz skrypty npm do weryfikacji.

Zadanie nie polega na czyszczeniu walidacji. Brzmi ono następująco:

Odrzucać nazwy wyświetlania składające się wyłącznie z przerw, aktualizować istniejący plik testowy, zachować publiczną API bez zmian i uruchomić wybrany test.

To określa dla agenta zachowanie, granice i warunki sprawdzania.

Nadaj zmianie własny proces weryfikacji

Z głównego procesu weryfikacji:

git worktree add -b fix/display-name-validation ../service-display-name-fix
cd ../service-display-name-fix

Worktree to drugi katalog roboczy przypisany do tego samego repozytorium. Powyższe polecenie tworzy ../service-display-name-fix na gałęzi fix/display-name-validation, pozostawiając główny katalog wolny do innych zadań.

Odtąd edycje, wyniki testów oraz niezrealizowane różnice pozostają z dala od głównego katalogu. Jeśli eksperyment okaże się bezcelowy, jego pliki można przywrócić lub usunąć worktree po sprawdzeniu jego statusu.

Najpierw znajdź kod i testy

Użyj własnej terminologii repozytorium, aby określić zakres pracy:

rg -n "displayName|display name" src test

Niech wyniki wyszukiwania będą następujące:

src/users/validateProfile.ts
test/users/validateProfile.test.ts

Granica jest teraz określona konkretnie. Agent potrzebuje tych dwóch plików oraz polecenia, które je waliduje, a niejasne zaproszenie do przeglądania całego repozytorium nic nie dodaje.

Rozpoczęcie działania Aider na lokalnym modelu Ollama

Zanim przejdziesz do tego kroku, upewnij się, że zainstalowane są Git, Aider, Ollama oraz rg, a także że środowisko działania Ollama jest dostępne na tym komputerze. Wybrany model musi również działać z zainstalowanymi wersjami Aider i Ollama. Aider dokumentuje dostawców modeli Ollama – upewnij się, że wybrany model istnieje w Ollama, a następnie uruchom Aider z katalogu roboczego, używając przedrostka ollama_chat/ w nazwie modelu.

ollama pull <installed-model>
aider --model ollama_chat/<installed-model>

Zamień <installed-model> na tag, który faktycznie posiada Ollama. Ten sam tag pojawia się w obu poleceniach, ponieważ Ollama serwuje ten model, a Aider wybiera go po nazwie.

Aider może śledzić swoje zmiany za pomocą Git. Uruchom go w worktree, przeczytaj różnice po każdej edycji i pozostaw decyzję o zapisaniu zmian w rękach człowieka.

Dostępne są również polecenia wewnątrz czatu, mapa repozytorium, opcje konfiguracji oraz kontrolery limitu kontekstu. Pomagają one w nawigacji, ale żadne z nich nie określa zakresu ani nie potwierdza poprawności patcha.

Zrób z pierwszej próby plan

Ogranicz kontekst agenta do odpowiednich plików, używając procedury dodawania plików opisanej dla zainstalowanej wersji Aider, a nie etapowania w Git. Następnie podaj prompt z wynikiem, dozwolonymi ścieżkami oraz poleceniem walidacji:

Task: Fix whitespace-only display names being accepted.

Files in scope:
- src/users/validateProfile.ts
- test/users/validateProfile.test.tsConstraints:
- Preserve the public API.
- Do not edit generated files, lockfiles, deployment configuration, or unrelated tests.
- First, explain the current behavior, name the files you would change, and propose the smallest fix.
- Do not edit files until I approve the plan. Treat this as a required review step, and use any available approval controls in your local agent configuration to enforce it where possible.Validation:
- Run: npm test -- validateProfile
- Report the exact command run, files changed, test result, and any unresolved assumption.

Taki prompt zapobiega kilku powszechnym problemom: zadańom, które się rozrastają, edycjom poza wyznaczonymi ścieżkami oraz poprawkom, które nie zawierają jasnego sposobu ich weryfikacji.

Odrzuć rozbudowane plany już na wstępie

Dobra pierwsza odpowiedź wygląda tak:

1. Inspect src/users/validateProfile.ts to confirm how displayName is validated.
2. Inspect test/users/validateProfile.test.ts for the existing validation-test pattern.
3. Add a failing test for a whitespace-only displayName.
4. Make the smallest validation change required to reject that input.
5. Run npm test -- validateProfile.

Zanim zatwierdzisz jakąkolwiek zmianę, zadaj sobie następujące pytania:

• Czy plan określa zamierzoną implementację i testy?
• Czy dotyczy on tylko jednego zachowania?
• Czy wskazuje, jaką zmianę w walidacji proponuje?

Zatrzymaj się, jeśli wspomina o migracji schematu, instalacji zależności, aktualizacji pliku blokującego lub zmianach w niepowiązanych punktach końcowych. Lepiej skup się na zawężeniu zadań, zamiast zatwierdzać rozszerzenia, które wydają się jedynie rozsądne.

Różnica oraz wynik testu to ostateczny produkt

Gdy plan zostanie zatwierdzony, za każdym razem powtarzaj tę samą sekwencję przeglądania.

Rozglądaj się tylko w umówionych plikach

git diff -- src/users/validateProfile.ts test/users/validateProfile.test.ts

Tutaj oczekiwany wynik to pojedynczy nowy test dla pustego wprowadzenia wraz z jedną modyfikacją implementacji, która go spełnia. Wygląd tej modyfikacji zależy od istniejącego kontraktu walidacyjnego repozytorium, więc sprawdź, czy odrzucane są tylko te dane, które po wycięciu pozostają puste, oraz czy ważne nazwy wyświetlania przechodzą bez zmian.

Zwróć uwagę na to, co podsumowanie sesji może ukrywać:

• publiczną API zmienioną pomimo zakazu
• pliki edytowane poza ustaloną listą
• przeformatowanie, które nie ma związku z błędem
• nowy test, który przechodzi bez żadnego oddziaływania na docelowe zachowanie
• modyfikację walidacyjną, która odrzuca również prawidłowe nazwy

Diff oraz wynik testu stanowią ostateczny produkt. Własne podsumowanie agenta służy jako przewodnik przy czytaniu i nie dowodzi niczego co do poprawności.

Zrób skupioną weryfikację

<repository-focused-test-command>

Zastąp miejsce zastępcze składnią poleceń i wyboru plików, które rzeczywiście jest używane w repozytorium.

Aider może automatycznie sprawdzać kod pod kątem błędów i testować go po zmianach. Może to skrócić cykle zwrotu informacji, jednak autorytetem pozostają własne polecenia repozytorium.

Celowo zachowaj lub usuń zmianę

Jeśli różnice i wynik testu wyglądają prawidłowo:

git status
git add src/users/validateProfile.ts test/users/validateProfile.test.ts
git commit -m "Reject whitespace-only display names"

Jeśli tego nie zrobią:

git restore src/users/validateProfile.ts test/users/validateProfile.test.ts

Ponieważ nie podano źródła, git restore przywraca dwa nazwane pliki z HEAD, odrzucając jedynie niezapisane edycje tych plików. Sprawdź git status, aby zobaczyć zmiany przygotowane do zapisu, pliki niesledzone lub modyfikacje w innych miejscach, zanim uznasz eksperyment za odrzucony.

Gdy cała gałąź może zostać usunięta, usuń worktree po sprawdzeniu jej stanu i zapisaniu wszystkiego, co warto zachować:

git worktree remove ../service-display-name-fix

Git zarządza powiązanymi katalogami roboczymi za pomocą poleceń worktree. Odzyskiwanie stanu to normalna procedura, która sprawia, że eksperymenty z małymi agentami można bezpiecznie powtarzać.

Grenice: system plików, uprawnienia, kontekst

Rozpoczęcie działania od korzenia repozytorium

Agent należy uruchomić w katalogu projektu lub w dedykowanym dla niego worktree. Uruchamianie go z katalogu domowego w nadziei, że interfejs narzuci odpowiednie granice, nie działa.

Katalog roboczy dostarcza domyślnego zakresu działania, ale nie narzuca żadnych ograniczeń. To, do czego agent faktycznie może dotrzeć, jest określane przez uprawnienia systemu operacyjnego, ustawienia narzędzia oraz dostępną przestrzeń bezpieczeństwa.

Celowane zatwierdzanie efektów ubocznych

Zapisy plików, instalacja zależności, dostęp do danych uwierzytelniających, korzystanie z sieci oraz zmiany w infrastrukturze powinny wymagać świadomej aprobaty. W przypadkach, gdy agent lub host nie mogą tego zagwarantować, należy potraktować to jako krok manualnej weryfikacji i nie przedstawiać tego jako kontroli technicznej. Sprawdź, jakie kontrole istnieją, zanim od nich będziesz polegać.

OWASP wymienia wstrzykiwanie poleceń jako zagrożenie, które może skłonić aplikację wykorzystującą LLM do podejmowania niezamierzonych działań lub ujawniania informacji.

Praktyczne wytyczne podstawowe:

• Zezwalaj na czytanie plików w przeznaczonym repozytorium.
• Wymagaj aprobaty przed zapisem danych.
• Wymagaj aprobaty przed wykonywaniem poleceń w shellu, które mają skutki uboczne.
• Uczyń dostęp do sieci dobrowolnym.
• Zachowuj tajne dane poza zwykłym kontekstem agenta.

To pomaga kontrolować zasięg skutków. Nie ocenia to, czy agent jest godny zaufania.

Zachowuj konfigurację prostą i widoczną

Aider czyta konfiguracje w formacie YAML, pliki środowiskowe oraz ustawienia kluczy API. Konfiguracja projektu współdzielonego powinna być widoczna, minimalistyczna i oddzielona od tajemnic, a dane uwierzytelniające nigdy nie powinny znajdować się w pliku z instrukcjami repozytorium. Najlepiej unikać zbiorów globalnych ustawień domyślnych, których nikt później nie może przejrzeć ani wyjaśnić.

Zostaw kontekst niezbędny do wykonania zadania

Mapa repozytorium pomaga Aiderowi zrozumieć strukturę bazy kodu, natomiast kontekst ogranicza ilość informacji, które mogą zmieścić się w jednej prośbie. Aby szybko naprawić problem, podaj zadanie, odpowiednie pliki, polecenie walidacji oraz wszystkie zasady projektu dotyczące tej zmiany. Dodawanie plików wygenerowanych, dokumentów lub starych, niepowiązanych z tematem komitetów przeważnie tylko powoduje bałagan.

Umowa projektowa dla prac powtarzalnych

Jeśli ten sam proces pracy pojawia się wielokrotnie, przechowaj zapisany plik z instrukcjami, użyteczny szablon lub wzór zadania obok kodu:

Project contract

Goal:
- [Describe one bounded outcome.]Scope:
- You may edit: [paths]
- Do not edit: [paths, generated files, secrets, deployment configuration]Conventions:
- Follow: [formatter, naming, architecture rules]
- Preserve: [public APIs, compatibility constraints]Validation:
- Run: [exact test, lint, type-check, or build command]
- Report: commands run, files changed, failures, and unresolved assumptionsDefinition of done:
- The requested behavior is implemented.
- Relevant checks have run, or the reason they could not run is stated.
- The final response summarizes the diff and any follow-up work.

Format nie ma znaczenia. Ważne jest to, aby ograniczenia były widoczne.

Tryby awarii i kolejne małe kroki

Zbyt szerokie wyszukiwanie. Przestań, skróć listę plików i rozpocznij od nowa, używając ścieżek lub symboli uzyskanych z ręcznego wyszukiwania.

Zbyt obszerna propozycja refaktoryzacji. Podziel żądanie w miejscu, które można przetestować. Jeden nieprzechodzący test, jedno zachowanie lub jedna granica refaktoryzacji są lepsze niż wymóg architektoniczny.

Modyfikacje poza zakresem. Odrzuć patch, przywróć niepowiązane pliki i podaj nazwy zabronionych ścieżek w następnym zapytaniu.

Żądanie niebezpiecznej komendy. Zapytaj, co ona zmienia i dlaczego jest potrzebna, zanim ją zatwierdzisz.

Nieprzechodząca kontrola. Poproś o diagnozę, zanim pozwolisz na dalsze modyfikacje, i zażądaj informacji o awarii, jej prawdopodobnej przyczynie oraz najprostszego kolejnego eksperymentu.

Wolne lokalne wnioskowanie. Najpierw zmniejsz zakres zadania i kontekstu. Ocena innego modelu lub ustawień czasu wykonywania powinna nastąpić dopiero później. Nie przeprowadza się tu żadnych porównań wydajności, a wszelkie późniejsze powinny odnotowywać zmierzoną opóźnioność, model, czas wykonywania oraz sprzęt.

Szybszy agent, który generuje większe, trudniejsze do przeanalizowania różnice, nie poprawił przepływu pracy.

Dostosowuj po jednej rzeczy na raz

Gdy funkcje wyszukiwania, planowania, porównywania, testowania i przywracania zachowują się przewidywalnie, reguluj jedną zmienną na rundę. Zmień model, jeśli problemem jest jakość wyników. Zmień strategię kontekstu, jeśli istotny kod nadal jest pomijany. Ułatw zasady zatwierdzania tylko wtedy, gdy kilka małych, określonych zadań pokaże, że prompt w ogóle nic nie chronił, a nawet wtedy zachowaj dostępne różnice, testy i możliwość cofnięcia. Dodawaj automatyzację na końcu, gdy komenda walidacji będzie godna zaufania.

Konfiguracja Aidera jest wrażliwa na wersję, dlatego warto sprawdzić jego strony konfiguracji oraz historii wydań przed ponownym użyciem. Porównaj każdą komendę, identyfikator modelu oraz opcję konfiguracyjną z wersjami Aidera i Ollamy faktycznie zainstalowanymi na danym komputerze.

Zasada decyzyjna jest prosta: zachowaj narzędzie lub ustawienie tylko wtedy, gdy poprawia ono realizację zadań, możliwość sprawdzania wyników lub proces odzyskiwania danych.