Notatki praktyczne: Twój agent kodujący nie potrzebuje lepszego promptu

Poniższe notatki przedstawiają praktyczne rozwiązanie dotyczące tematu „Twój agent do programowania nie potrzebuje lepszego promptu”. Nacisk kładziony jest na umowy, sprawdzania oraz miejsca zastępcze dla kodu, a nie na motywacyjne aspekty.

Potrzebuje lepszych warunków pracy

Gdy przechodzisz przez etap „Potrzebuje lepszych warunków pracy”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Zachowuj w pamięci podręcznej stabilne instrukcje systemowe oraz schematy narzędzi. Ponowne wysyłanie identycznego tekstu wprowadzającego jest częstą przyczyną marnotrawstwa zasobów.

Pętla curl

Gdy przechodzisz przez etap pętli curl, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Zachowuj w pamięci podręcznej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego preambułu jest częstą przyczyną marnotrawstwa zasobów.

search for artifact
      ↓
try dependency
      ↓
Maven failure
      ↓
search web
      ↓
curl documentation
      ↓
download JAR
      ↓
inspect classes
      ↓
try another version
      ↓
search again

Iteracja 1: Naprawa środowiska

Gdy pracujesz nad etapem Naprawa 1 w ramach iteracji, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki od rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zachowuj w pamięci tymczasowej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu to częsty powód marnotrawstwa zasobów.

LLM + prompt

Model
  + instructions
  + repository
  + build
  + tools
  + runtime
  + available evidence
  + project knowledge
  + feedback loops

Iteracja 2: Daj agentowi narzędzia nawigacyjne, których już używają inżynierowie

Gdy przechodzisz przez drugą iterację, na tym etapie najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć możliwość cichego, częściowego ukończenia zadania. Zachowuj w pamięci tymczasowej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego nagłówka jest częstą przyczyną marnotrawstwa zasobów.

shell + filesystem + internet

interface
   ↓
implementation
   ↓
usage
   ↓
test

Iteracja 3: Czasami najlepszym kontekstem jest osoba wskazująca właściwy plik

Gdy pracujesz nad etapem Iteracji 3 Sometimes the stage, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych. Zachowuj w pamięci podręcznej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu to częsty powód marnotrawstwa zasobów. Gdy pracujesz nad etapem Iteracji 3 Sometimes the stage, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później.

AllMiniLmL6V2EmbeddingModel
        ↓
AbstractInProcessEmbeddingModel
        ↓
OnnxBertBiEncoder

Hugging Face tokenizer
        ↓
ONNX Runtime
        ↓
token representations
        ↓
pooling
        ↓
normalization
        ↓
embedding

Iteracja 4: Dlaczego decydujemy, czego agent musi się nauczyć?

Faza „Dlaczego w iteracji 4?” działa najlepiej, gdy traktuje się ją jako mierzalną powierzchnię. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Określ budżet tokenów na jeden ruch i na jedną sesję. Narzędzia agentowe intensywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki.

Niewielki eksperyment z Integrallis Vectors

Niewielki eksperyment na tym etapie działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden udany wynik, jeden przypadek niepowodzenia oraz notatkę o cofnięciu działań, zanim rozszerzysz zakres pracy. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Przydziel budżet tokenów na każdy ruch i sesję. Narzędzia agenta agresywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki.

../vectors/

Initial working model
        ↓
low confidence recognized
        ↓
specific evidence requested
        ↓
source inspected
        ↓
previous hypothesis falsified
        ↓
new working model
        ↓
better engineering recommendation

Tak, agent się nauczył…

Faza „Yes, the agent learned” funkcjonuje najlepiej, gdy traktowana jest jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Zapisuj czasy wykonywania zadań oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy przechodzi się z środowiska demonstracyjnego do współdzielonych środowisk. Przydziel budżet tokenów na jeden ruch i na jedną sesję. Narzędzia agenta agresywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki. Faza „Yes, the agent learned” funkcjonuje najlepiej, gdy traktowana jest jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Zdokumentuj zarówno optymalną ścieżkę działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrola przez człowieka oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później.

Nauka agenta powinna przetrwać dłużej niż sam agent.

W fazie uczenia się agenta należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinno to wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. W przypadku, gdy następnym krokiem jest kod lub wywołanie narzędzia, lepsze są ustrukturyzowane wyniki z walidacją schematu niż tekst w formie swobodnej.

docs/engineering/

docs/knowledge/

docs/knowledge/vector-backends/
    onnx-embedding-pipeline.md
    integrallis-vectors.md
    candidate-assessment.md

Local embedding baseline:
- all-MiniLM-L6-v2
- 384 dimensions
- ONNX Runtime
- DJL HuggingFaceTokenizer
- mean pooling
- L2 normalization

Long inputs:
- partitioned before inference
- embeddings combined using token-count weightingLangChain4j:
- useful as a verified reference implementation
- not required by the runtime designUpstream source:
- available locally for deeper verification

retained knowledge
       ↓
task understanding
       ↓
remaining uncertainty
       ↓
targeted evidence
       ↓
new learning
       ↓
updated retained knowledge
       ↓
next agent

Badania są częścią delegowania

Aby badania były częścią danego etapu, należy zdefiniować dane wejściowe, osobę odpowiedzialną za ten krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Przy następnym kroku, który polega na pisaniu kodu lub wywoływaniu narzędzia, preferuj strukturyzowane wyniki z walidacją schematu zamiast tekstów w formie swobodnej.

"Agent, do everything."

"Human specifies every line."

Agent nie jest dżinem w lampie

Dla przypadku, gdy agent nie znajduje się na określonej fazie, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy rejestrować czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. W przypadku, gdy następnym krokiem jest kod lub wywołanie narzędzia, lepiej używać ustrukturyzowanych wyników z walidacją schematu niż prostego tekstu. Dla przypadku, gdy agent nie znajduje się na określonej fazie, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownego wykonania, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później.

Coding Agent
                          │
          ┌───────────────┼───────────────┐
          │               │               │
       Harness         Knowledge        Research
          │               │               │
        tools          project facts     source
        build          decisions         docs
        IDE            constraints       experiments
        runtime        prior learning    external evidence
          │               │               │
          └───────────────┼───────────────┘
                          ↓
                    Clear boundaries
                          ↓
                   Precise delegation
                          ↓
                    Implementation
                          ↓
                     Verification
                          ↓
                  Retained knowledge
                          │
                          └──────→ next agent

Od formułowania zadań do projektowania warunków pracy

Podczas przechodzenia przez etap od formułowania zadań do projektowania, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co się dzieje w przypadku częściowego awarii. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zachowuj w pamięci tymczasowej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu to częsty powód przeciążenia systemu.

better environment
      ↓
cheaper investigation
      ↓
better evidence
      ↓
better decisions
      ↓
retained learning
      ↓
better starting environment
      ↓
next agent

Pochodzenie OSK

Gdy przechodzisz przez etap wyjaśniania pochodzenia OSK, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć przypadkowe, częściowe ukończenie zadań. Zachowuj w pamięci tymczasowej stabilne instrukcje systemowe oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu to częsty powód marnotrawstwa zasobów.

Inny sposób programowania z agentami

Gdy pracujesz nad „Innym sposobem realizacji”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych. Zachowuj w pamięci tymczasowej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego nagłówka jest częstą przyczyną marnotrawstwa zasobów. Gdy pracujesz nad „Innym sposobem realizacji”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, mechanizmy ludzkiej kontroli oraz obsługa wiadomości błędowych są częścią produktu, a nie elementem dodatkowej optymalizacji.

Human request
      ↓
Agent generates code

Human hypothesis
      ↓
discussion
      ↓
agent reconnaissance
      ↓
identify uncertainty
      ↓
targeted research
      ↓
retained evidence
      ↓
human + agent design
      ↓
implementation
      ↓
real-world friction
      ↓
verification
      ↓
revised architecture
      ↓
new retained knowledge

To są hipotezy, a nie prawa

To są hipotezy, a nie gotowe rozwiązania – najlepiej traktować je jako mierzalną powierzchnię do analizy. Zapisz jeden udany przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Określ budżet tokenów na jeden ruch i jedną sesję. Narzędzia typu agentic intensywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki.

Listwa kontrolna operacyjna

Na etapie listwy kontrolnej operacyjnej zdefiniuj dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia pracy przed zmianą kodu. Operatorzy powinni móc ponownie wykonać dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu systemu.

Zachowaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.

Zamiast prozy w formie otwartej, preferuj strukturyzowane wyniki z walidacją schematu, gdy następnym krokiem jest generowanie kodu lub wywołanie narzędzia.

Utwórz punkt kontrolny po kosztownych krokach. System powinien unikać ponownego naliczania opłat za to samo wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.

Zabezpiecz wersje zależności i zapisz hash obrazu, który został użyty do wykonania demonstracji. Reprodukowalność jest ważniejsza od wiedzy przekazywanej ustnie.

Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy plikom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania.

Zanim wdrożysz cały stack, zamroź wersje, utwórz dokładny zapis dla kluczowych etapów realizacji oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności użytkownika oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolimy nudną niezawodność od sprytnych, jednorazowych demonstracji.

Uwaga dotycząca procesu batch dla ddfa012877c8: unikaj przechowywania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy obok plików przygotowawczych do testowania, aby późniejsze zmiany modeli pozostawały porównywalne.

Dla etapu 0 dotyczącego wzmocnienia bezpieczeństwa zdefiniuj wcześniej dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.

Szczegóły wzmocnienia bezpieczeństwa 0/867: zmierz czas działania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie informacji anegdotycznych.