Inżynieria kontekstu dla agentów kodujących

Inżynieria kontekstu polega na określaniu, jakie informacje agent kodujący otrzymuje, zanim zacznie działać. To najistotniejsza dźwignia wpływająca na jakość danych wyjściowych, ponieważ nawet najbardziej zaawansowany model jest tak dobry jak dane, które mu dostarczysz.

W Jirze kontekst potrzebny agentowi jest już integralną częścią zgłoszenia. Zgłoszenie zawiera cel i kryteria akceptacji, a Teamwork Graph łączy je z odpowiednim kodem, decyzjami i dokumentacją, dzięki czemu agent działa na podstawie rzeczywistych zamiarów, a nie pustego promptu. Ten kontekst pozostaje dostępny dla całego zespołu, zamiast tkwić w lokalnych plikach na jednym komputerze.

W tym przewodniku opisujemy, czym jest inżynieria kontekstu, dlaczego okno kontekstu stanowi rzeczywiste ograniczenie dla agentów kodujących i jak projektować kontekst w Jirze, aby agenty otrzymywały potrzebne informacje bez konieczności ręcznego przekazywania ich w każdym prompcie. W praktyce sprowadza się to do kilku działań podejmowanych w ramach już prowadzonych prac:

• Podaj agentowi cel, nie tylko prompt. Przygotuj zgłoszenie w Jirze jako specyfikację, określając kryteria akceptacji, według których oceniany będzie agent.

• Zadbaj, aby wykres dostarczał otaczający kontekst. Wykorzystując zgłoszenie jako punkt wyjścia dla promptu, Teamwork Graph rozbudowuje je o dokumenty, decyzje i powiązany kontekst dotyczący zadania.

• Zapewnij spójność i aktualność standardów. Konwencje przechowywane w Confluence stanowią wspólne źródło dla wszystkich agentów i kolegów z zespołu.

• Przekaż każdemu agentowi tę samą warstwę kontekstu. Ten sam kontekst organizacyjny trafia do każdego agenta kodującego, takiego jak Claude Code, Cursor, Codex, GitHub Copilot, Jira Coding Agent i innych.

Czym jest inżynieria kontekstu?

Inżynieria kontekstu to praktyka polegająca na świadomym decydowaniu, które informacje model otrzymuje na każdym etapie, aby agent kodujący miał wszystkie dane potrzebne do prawidłowego wykonania zadania. Te informacje to nie tylko prompt — to także baza kodu, standardy, zależności, historia Git, definicje narzędzi, cele i kryteria akceptacji. Opracowanie takiego zestawu dla każdego zadania to nowe zadanie.

Inżynieria promptów wymaga samodzielnego wyselekcjonowania informacji i przekazania ich w formie pojedynczej instrukcji. Inżynieria kontekstu polega na tym, że system dostarcza agentowi wszystkie dane potrzebne do realizacji wieloetapowego zadania: co zostaje wprowadzone, co jest pobierane, co jest streszczane i co jest pomijane, umożliwiając agentowi znalezienie pozostałych danych w razie potrzeby.

Warto pamiętać, że obszerniejszy kontekst nie zawsze jest lepszy

• Kontekst o wysokiej wartości informacyjnej to treści, które realnie pomagają w realizacji bieżącego zadania.

• Kontekst o niskiej wartości informacyjnej to treści nieaktualne, nie na temat lub zduplikowane, które model nadal musi przetwarzać.

W miarę jak okno kontekstu zapełnia się tokenami o niskiej wartości informacyjnej, odpowiedzi nadchodzą wolniej i są mniej precyzyjne, mimo że model nie ulega zmianom. To zjawisko nazywa się degradacją kontekstu — stopniowym pogarszaniem się danych wyjściowych w miarę zapełniania okna kontekstu nieaktualnymi, mało istotnymi lub sprzecznymi tokenami. Dobre zarządzanie kontekstem polega nie tylko na dodawaniu właściwych informacji, ale także na usuwaniu nieaktualnych.

Dlaczego okno kontekstu stanowi ograniczenie dla agentów kodujących?

Model kodowania może analizować jedynie to, co mieści się w oknie kontekstu, które jest niewielkie w porównaniu z bazą kodu, dokumentacją i historią zespołu. Nawet doświadczony agent może dostarczyć błędny lub niebezpieczny kod, jeśli konwencje, architektura albo decyzje dotyczące zadania nie zostały uwzględnione w oknie kontekstu.

Gdy agent musi samodzielnie zgromadzić kontekst, pojawia się kilka typowych schematów błędów:

• Agent odchodzi od pierwotnego kierunku w długim zadaniu, ponieważ decyzja podjęta przez niego na początku zostaje wypchnięta z okna kontekstu przez nowsze tokeny o mniejszej wartości informacyjnej.

• Pobiera zbyt wiele danych, wczytując do okna znacznie więcej informacji, niż faktycznie wykorzystuje, i zużywa budżet tokenów na nieistotne działania.

• Nie uwzględnia standardu, którego mu nie przedstawisz, a następnie dostarcza kod, który narusza wzorzec stosowany przez resztę zespołu.

• Działa poprawnie w pojedynkę, ale nie wie, co robi reszta zespołu ani inny agent w tym samym obszarze.

Zapewnienie łatwego dostępu do właściwego kontekstu pozwala agentowi samodzielnie wyszukiwać potrzebne informacje w trakcie działania, dzięki czemu prompty mogą być nadal ogólne, bez konieczności szczegółowego ręcznego opisywania każdej konwencji i decyzji.

Jak tworzyć kontekst dla agentów kodujących w Jirze?

W Jirze to zgłoszenie staje się kontekstem: zamiar jest zapisany w zgłoszeniu, powiązana wiedza jest dostępna dzięki Teamwork Graph, a trwałe standardy i decyzje są pobierane z narzędzi Confluence i Loom, które służą jako wspólne źródło dla wszystkich agentów i kolegów z zespołu. Jira wykracza poza lokalne pliki na pojedynczym komputerze, obejmując cele, bieżące decyzje i rozmowy oraz historię działań w całej pracy. Wszystkie te informacje są udostępniane, dzięki czemu agent zawsze działa w uporządkowanym, aktualnym i spójnym kontekście dla całego zespołu.

Inżynieria kontekstu opiera się na trzech zasadach:

1. Wybór odpowiednich informacji.

2. Zachowanie struktury.

3. Zapewnienie trwałości.

1. Wybór i pobieranie: Napisz zgłoszenie jako specyfikację

Selekcja polega na wybraniu najmniejszego zestawu kontekstu o największej wartości informacyjnej dla zadania, natomiast pobieranie to ściąganie odpowiednich informacji w razie potrzeby, zamiast umieszczania wszystkiego od razu w oknie. W Jirze oba procesy rozpoczynają się od zgłoszenia.

• Jak to działa w Jirze: Podaj cel w opisie, a kryteria akceptacji na liście kontrolnej. Dzięki temu agent otrzymuje zamiar i kryterium oceny, umieszczone w strukturze, którą może odczytać. Następnie przypisz zgłoszenie do połączonego agenta. Proces rozpoczyna się od zgłoszenia i powiązanego z nim kontekstu, a nie od całej bazy kodu. Doprecyzowanie specyfikacji poprzez współpracę z agentem jest częścią procesu: agent błyskawicznie analizuje obszerne materiały i pomaga wychwycić luki jeszcze przed rozpoczęciem działania.

• Już wkrótce: Planer Jiry przekształca pomysły w gotowe do realizacji plany i zgłoszenia z dołączonym już kontekstem. Dołącz do listy oczekujących.

2. Wspólny kontekst: Powiązanie zamiast wklejania

Struktura i formatowanie są kluczowe — tak ukształtuj kontekst, aby agent mógł się w nim swobodnie poruszać, i połącz odpowiednie informacje zamiast je kopiować. Teamwork Graph umożliwia dostęp do otaczającego kontekstu, dzięki czemu nie musisz za każdym razem samodzielnie go zestawiać.

• Jak to działa w Jirze: Powiąż zgłoszenie z pokrewnymi zgłoszeniami, kodem i stronami Confluence zawierającymi specyfikację, RFC lub rejestr decyzji. Agent dziedziczy kontekst związany z zadaniem, a nie tylko treść zgłoszenia. Przewodnik Loom również jest istotny: nagranie z odtworzeniem błędu lub uzasadnieniem projektu przenosi transkrypcję i podsumowanie do wykresu, dzięki czemu wyjaśnienie, które musiałoby zostać przekazane koledze z zespołu, staje się kontekstem możliwym do odczytania przez agenta. To zapewnia „właściwe pobrane fakty” bezpośrednio z rzeczywistej pracy, a nie z oddzielnego magazynu wektorowego, który trzeba samodzielnie tworzyć i utrzymywać.

3. Trwałość: Utrzymuj standardy i decyzje tam, gdzie mogą się kumulować

Trwałość, czyli pamięć, polega na zachowaniu informacji między sesjami, dzięki czemu agent nie zaczyna za każdym razem od zera. Trzy główne pytania do rozważenia to: co agent przechowuje podczas zadania, co powinien zachować między zadaniami i do jakich informacji może sięgnąć w razie potrzeby.

• Jak to działa w Jirze: Konwencje, decyzje architektoniczne i preferowane wzorce są przechowywane we wspólnej przestrzeni Confluence, z której cały zespół i wszystkie agenty korzystają jako ze wspólnego źródła za pośrednictwem wykresu, zamiast z kopii znajdującej się na komputerze jednego pracownika, niedostępnej dla innych. W miarę jak praca przechodzi przez system, wykres staje się coraz bardziej rozbudowany, dzięki czemu kolejny agent ma więcej informacji do wykorzystania. Kontekst gromadzi się w miarę postępu prac, bez konieczności wykonywania dodatkowych czynności przez programistów.

Dwie rzeczy umożliwiają skuteczną współpracę w zespole: jedna warstwa kontekstu dostępna dla każdego agenta oraz nadzór, który zapewnia niezawodność i zgodność z uprawnieniami.

Jedna warstwa kontekstu dla wszystkich agentów

Tworzony przez Ciebie kontekst ma sens tylko wtedy, gdy każde narzędzie może z niego korzystać. Ponowne uczenie każdego agenta Twoich standardów to najszybszy sposób, aby kontekst znów uległ degradacji.

• Jak to działa w Jirze: Zapewnij każdemu agentowi kodującemu ten sam kontekst organizacyjny dostępny za pośrednictwem dwóch ścieżek. Teamwork Graph CLI umożliwia agentowi kodującemu bezpośredni dostęp do tego kontekstu i narzędzi z poziomu terminala; po jednorazowej konfiguracji agent może odpytywać wykres podczas pracy. Serwer MCP Atlassian Rovo zapewnia taką samą obsługę klientom MCP, takim jak Claude, Cursor, Codex i GitHub Copilot. To właśnie Teamwork Graph spaja wszystko, łącząc zgłoszenia, decyzje, dokumenty i kod w jedną warstwę, którą można odpytywać. Kontekst przygotowujesz raz, a następnie wykorzystujesz z dowolnym modelem realizującym zadanie.

Nadzór: zapewnij wiarygodność i dostępność kontekstu

Kontekst jest przydatny tylko wtedy, gdy jest aktualny, a agent ma do niego dostęp. Nadzór zapewnia wiarygodność wspólnej warstwy, gdyż korzysta z niej więcej agentów.

• Jak to działa w Jirze: agenty przejmują te same uprawnienia, które zespół już wykorzystuje jako punkt odniesienia, dzięki czemu agent widzi to samo, co jego użytkownik i nic więcej. Zakres uprawnień można dodatkowo ograniczyć za pomocą reguł specyficznych dla agenta. Aby dowiedzieć się, jak łączą się ze sobą dostęp, zatwierdzanie i audyt, zobacz Zabezpieczenia i bezpieczeństwo inżynierii agentowej w Jirze.

Jak Jira wpisuje się w pozostałe elementy Twojego pakietu kontekstowego?

Obecnie większość kontekstu agenta kodowania znajduje się na jednej maszynie: w otwartym repozytorium, kilku lokalnych plikach oraz w tym, co programista wpisał do promptu. To podejście sprawdza się, gdy programista pracuje sam, ale informacje są rozproszone, przypisane do poszczególnych osób i łatwo o nich zapomnieć. Jira i Teamwork Graph pobierają istotny kontekst do jednej wspólnej, aktualnej i kontrolowanej warstwy używanej przez cały zespół i jego agenty.

Żadne z tych rozwiązań nie zastępuje agenta kodowania, IDE ani lokalnej konfiguracji. Nadal odpowiadają one za szczegóły dotyczące poszczególnych repozytoriów oraz za właściwy kod. Jira stanowi wspólną nadrzędną warstwę, dzięki czemu cały zespół korzysta z uporządkowanego, aktualnego i spójnego kontekstu.

Jak zapewnić prawdziwy kontekst pierwszemu agentowi w Jirze

Inżynieria kontekstu polega ostatecznie na zapewnieniu agentowi narzędzi i informacji, które umożliwią mu samodzielne znalezienie tego, czego potrzebuje. Jira i Teamwork Graph stanowią wspólną warstwę kontekstu, do której uzyskuje on dostęp za pośrednictwem MCP lub CLI, dlatego praca utrzymuje dokładność i połączenie tej warstwy.

Zacznij od jednego poprawnie utworzonego zgłoszenia, aby zobaczyć różnicę między agentem, który zgaduje, a takim, który działa zgodnie z intencją.

1. Określ agentowi punkt odniesienia do oceny. Wybierz jedno zadanie o ograniczonym zakresie i niskim ryzyku, które można łatwo cofnąć, na przykład samodzielną refaktoryzację lub rozwiązanie drobnego błędu, a następnie zapisz cel w opisie z kryteriami akceptacji na liście kontrolnej.

2. Zamiast wklejać kontekst pozwól agentowi go przejąć. Połącz zgłoszenie z kodem, odwołując się do klucza zgłoszenia w swojej gałęzi, commicie lub pull requeście, a następnie powiąż z nim dokument lub podjętą decyzję. Agent pobiera powiązany kontekst dotyczący zadania, a nie tylko tekst zgłoszenia.

3. Wskaż wspólny standard. Powiąż konwencję, którą powinien stosować, ze stroną Confluence, aby kolejny agent i kolega z zespołu korzystali z tego samego źródła.

4. Przypisz go agentowi. Agent zaczyna od zgłoszenia i powiązanego z nim kontekstu, co stanowi bardziej precyzyjny punkt wyjścia niż cała baza kodu lub pusty prompt.

5. Oceń na podstawie kryteriów, które go zainicjowały. Sprawdź pull request pod kątem kryteriów akceptacji zapisanych w zgłoszeniu, aby dane wyjściowe były oceniane według pierwotnego punktu odniesienia dla agenta.

6. Poleć agentowi zamknięcie procesu. Każ mu na końcu zaktualizować zgłoszenie, dodając podsumowanie sesji, kluczowe decyzje i kompromisy oraz powiązany pull request, dzięki czemu kolejny kolega z zespołu lub agent będzie mógł łatwo kontynuować pracę w Teamwork Graph.

Po uruchomieniu w ten sposób kilku zgłoszeń wykres stopniowo się uzupełnia: każdy agent zostawia w zgłoszeniu podsumowanie, kluczowe decyzje oraz powiązany pull request, dzięki czemu kolejne rozpoczyna się już z pełniejszym obrazem sytuacji niż poprzednie. To inżynieria kontekstu, która się kumuluje, zamiast być resetowana przy każdym uruchomieniu.

Często zadawane pytania dotyczące inżynierii kontekstu

Czym różni się inżynieria kontekstu od inżynierii promptów?

Inżynieria promptów to dziedzina polegająca na ręcznym dobieraniu odpowiednich informacji dla pojedynczego promptu. Inżynieria kontekstu to dziedzina zajmująca się wdrażaniem systemu, który dostarcza agentowi informacje potrzebne podczas realizacji wieloetapowego zadania, w tym dotyczące wyszukiwania, struktury, pamięci oraz samego celu, dzięki czemu szczegóły są udostępniane na żądanie w razie potrzeby.

W jaki sposób agenty kodujące oparte na sztucznej inteligencji uzyskują kontekst z Jiry?

Agenty czerpią kontekst ze zgłoszenia, jego opisu i kryteriów akceptacji, a także z warstwy Teamwork Graph, która łączy powiązane zgłoszenia, dokumentację i kod, dzięki czemu agent działa zgodnie z rzeczywistym zamiarem, a nie na podstawie pustego promptu.

Dlaczego agenty kodujące generują błędny kod, nawet jeśli korzystają z dobrego promptu?

Prompt rzadko uwzględnia przyjęte konwencje, architekturę czy decyzje stojące za zadaniem. Większość błędów agentów wynika z problemów z kontekstem, a nie z samym modelem — lepszy kontekst rozwiązuje więcej problemów niż lepsze sformułowanie.

Czy inżynieria kontekstu jest nadal potrzebna, jeśli agent już analizuje moje repozytorium?

Tak. Repozytorium informuje agenta, czym jest kod, ale nie wyjaśnia, dlaczego został zbudowany w taki sposób, jakie standardy należy stosować ani co jeszcze dzieje się w zespole. Resztę dostarcza inżynieria kontekstu.

Czym jest degradacja kontekstu?

Degradacja kontekstu to stopniowe pogarszanie się jakości danych wyjściowych agenta w miarę zapełniania się okna kontekstu nieaktualnymi, mało istotnymi lub sprzecznymi tokenami. Odpowiedzi stają się wolniejsze i mniej precyzyjne, mimo że model nie uległ zmianie.