Pamięć projektowa agentów: Context as a Code na przykładzie środowiska Google Antigravity 2.0

Siedzisz kolejną godzinę nad krytyczną implementacją ze swoim agentem AI. Z każdym kolejnym promptem masz poczucie, że oddalasz się od celu, patrząc na wyniki, które otrzymujesz. Chwilę później model ponownie przeprasza, po czym znów generuje kod łamiący wszystkie wytyczne, które skrupulatnie mu przekazywałeś. Zamiast skupić się na architekturze, stajesz się mikromenedżerem asystenta cierpiącego na amnezję kontekstową.

Wpychanie setek linii promptów systemowych i dziesiątek plików nagłówkowych do okna czatu przy każdej nowej sesji to ślepy zaułek. Prowadzi to do zjawiska określanego w dokumentacji Google Antigravity jako context rot (gnicie kontekstu). Model gubi wątek w natłoku szumu informacyjnego lub sprzecznych ze sobą informacji, opóźnienia zwykle rosną wraz z rozmiarem kontekstu, a halucynacje i błędne założenia zaczynają blokować postęp prac.

To nie będzie kolejny, generyczny tutorial z inżynierii promptów ani zbiór magicznych komend dla początkujących. Artykuł kieruję do inżynierów, którzy mają dość bycia mikromenedżerami dla swoich agentów AI i chcą spróbować wdrożyć systemowe ramy współpracy z nimi. Zostawmy więc frustrację za sobą i przejdźmy do konkretów. Rozwiązanie? Prostsze niż myślisz. Context as a Code (CaaC).

Przenosimy kompletną konfigurację zachowań, standardów architektonicznych i rygorów bezpieczeństwa bezpośrednio do repozytorium w formie plików tekstowych (najlepiej w formacie Markdown, który modele lubią i potrafią odczytać). Korzystając z platformy Google Antigravity (jako środowiska referencyjnego), możemy wdrożyć zautomatyzowane ramy operacyjne dla projektów w wysokopoziomowym C++ (i nie tylko).

Zobaczmy, jak ustrukturyzowane pliki Markdown pozwalają agentom na dynamiczną aktualizację instrukcji operacyjnych i utrwalanie wiedzy projektowej w repozytorium.

Filozofia CaaC: Architektura pamięci agentów

W paradygmacie CaaC wiedza o architekturze oprogramowania i standardach kodowania nie znajduje się w plikach PDF na dyskach sieciowych ani w rzadko aktualizowanych dokumentach Wiki. Jest wersjonowanym kodem, który każdy inżynier pobiera ze swojego ulubionego systemu kontroli wersji.

Aby podejście Context as a Code działało bez zarzutu, musimy precyzyjnie oddzielić to, co czytają ludzie, od tego, co konfiguruje agentów. Na potrzeby tego artykułu będziemy posługiwać się uproszczonym modelem podziału pamięci na pamięć kontekstu (In-Context Memory) i pamięć zarządzaną (Managed Memory).

Pamięć zarządzana (Managed Memory)

Aby uniknąć wspomnianego wcześniej gnicia kontekstu, nie możemy ładować całej dokumentacji projektowej do promptu startowego agenta w każdej sesji.

Tradycyjny README.md służy wyłącznie ludziom – zawiera krótki opis biznesowy projektu oraz kroki wdrożeniowe dla deweloperów.

Z kolei ARCHITECTURE.md staje się techniczną mapą drogową projektu, opisującą podział na moduły, przepływy danych oraz historyczne decyzje techniczne. Agent nie analizuje ich stale – w razie potrzeby można jawnie dodać je do kontekstu (np. poprzez @ARCHITECTURE.md).

Pamięć kontekstu (In-Context Memory)

To jest właściwe centrum sterowania Twoich agentów. Pliki w katalogu .agents/ bezpośrednio wpływają na zachowanie agentów, ich role oraz umiejętności. Możemy podzielić ten obszar na kilka warstw, gdzie każda z nich odpowiada za zupełnie inne rzeczy.

Warstwa I: AGENTS.md (Tożsamość i ramy wykonawcze)

Jest to otwarty standard rozwijany przez Agentic AI Foundation pod egidą Linux Foundation. Definiuje:

• role w zespole (personas),
• konfigurację środowiska deweloperskiego,
• twarde polecenia weryfikujące.

Antigravity potrafi korzystać zarówno z AGENTS.md, jak i z własnych mechanizmów pamięci kontekstowej wykorzystywanych w ekosystemie Gemini (np. GEMINI.md dla globalnych ustawień).

Przykładowa zawartość pliku AGENTS.md:

# AGENTS.md

# The Autonomous Development Team

## The Product Manager (@pm)

You are a visionary Product Manager and Lead Architect with 15+ years of experience.

- **Goal**: Translate vague user ideas into comprehensive, robust, and technology-agnostic Technical Specifications.
- **Traits**: Highly analytical, user-centric, and structured. You never write code; you only design systems.
- **Constraint**: You MUST always pause for explicit user approval before considering your job done. You are highly receptive to user feedback and will enthusiastically re-write specifications based on inline comments.

Warstwa II: .agents/rules/ (Lokalne reguły projektu)

Folder .agents/rules/ przechowuje reguły specyficzne dla danego projektu (Workspace Rules). Są to pliki Markdown (w obecnej wersji ograniczone do 12 000 znaków), w których programujesz twarde ograniczenia kodu lub zachowania (np. nakaz stosowania inteligentnych wskaźników czy wyłączenie starych rzutowań w stylu C).

Ograniczenie pomaga utrzymać kluczowe instrukcje poza głównym promptem i zmniejsza ryzyko ich pominięcia przez model. Reguły te mogą być zawsze aktywne (Always On) lub wywoływane w locie na podstawie dopasowania plików (np. dla rozszerzeń .cpp).

Przykład reguły .agents/rules/container_rules.md:

# C++ Container Rules

- Never use raw C-style arrays (e.g., `int arr[]`). Always use `std::array` or `std::vector`.
- Prefer `std::string_view` for read-only function parameters to prevent unnecessary memory allocations.

Warstwa III: .agents/skills/ (Modułowe pakiety kompetencyjne)

Umiejętności to wydzielone foldery (nazwane konkretną umiejętnością) zawierające plik instrukcji SKILL.md oraz alternatywnie powiązane z nim skrypty pomocnicze lub przykłady.

Pakiety te działają w oparciu o regułę progresywnego ujawniania kontekstu. Agent na starcie widzi jedynie listę dostępnych umiejętności wraz z ich opisem. Dopiero gdy dana umiejętność jest potrzebna do realizacji zadania, wczytywana jest pełna zawartość pliku SKILL.md wraz z powiązanymi zasobami pomocniczymi. Dzięki temu rzadko używane instrukcje nie obciążają aktywnego kontekstu modelu.

Przykład zawartości takiego pliku:

# Skill: Deploy to Cloud Run

## Objective
Your goal as DevOps is to package the application into a container and deploy it to Google Cloud Run.

## Instructions
1. **Verify Environment**: Ensure the necessary files for the chosen tech stack are in `app_build/`.
2. **Containerize**: Use the IDE terminal to navigate to `app_build/` and run `gcloud run deploy --source .`. 
3. **Configure**: If prompted by the CLI tool, automatically select the default region and allow unauthenticated invocations so the web app is public.
4. **Report**: Output the live production Google Cloud Run URL to the user!

Warstwa IV: .agents/workflows/ (Choreografia zadań)

Zwieńczeniem całego systemu są przepływy pracy (Workflows), które definiują kolejność wykonywania zadań przez agenta. Podczas gdy reguły (Rules) dostarczają ograniczeń, a umiejętności (Skills) dostarczają kompetencji, workflow określa, kiedy i w jakiej kolejności mają zostać użyte.

Zapisując plik Markdown w tym folderze, tworzysz nową niestandardową komendę typu slash command (np. /auto-verify). Po jej wywołaniu agent automatycznie przejdzie przez zdefiniowany przez Ciebie proces. Agent asynchronicznie realizuje proces, całkowicie eliminując potrzebę Twojego mikrozarządzania między etapami.

Przykładowa zawartości pliku:

---
description: Start the Autonomous AI Developer Pipeline sequence with a new idea
---

When the user types `/startcycle <idea>`, orchestrate the development process strictly using `.agents/AGENTS.md` and `.agents/skills/`.

## Execution Sequence
1. Act as the **Product Manager** and execute the `write_specs.md` skill using the `<idea>`.
   - Wait for the user to explicitly approve the spec.
   - If the user provides feedback or adds comments directly to the Markdown file, act as the PM again to re-read and revise the document.
   - Loop this step until they type `Approved`.
2. Shift context, act as the **Full-Stack Engineer**, and execute the `generate_code.md` skill.
3. Shift context, act as the **QA Engineer**, and execute the `audit_code.md` skill.
4. Shift context, act as the **DevOps Master**, and execute the `deploy_app.md` skill.

Self-Modification: Jak repozytorium utrwala wiedzę projektową

Istotnym elementem architektury CaaC jest możliwość nie tylko odczytu plików konfiguracyjnych przez agentów, ale również proponowania ich aktualizacji. Klasyczny asystent AI uczy się wyłącznie w granicach aktywnej sesji czatu. Po jej zamknięciu wypracowana wiedza o unikalnych cechach Twojej aplikacji oraz specyfice projektu zostaje bezpowrotnie utracona. W paradygmacie CaaC wiedza ta zostaje utrwalona bezpośrednio w kodzie.

Cały proces opiera się na ścisłej współpracy człowieka z maszyną. Po pomyślnym rozwiązaniu problemu deweloper może uruchomić fazę retrospekcji za pomocą prostego polecenia: np. „Zaktualizuj naszą umiejętność stl-safety o wnioski z tej sesji”.

Agent może zaproponować aktualizację pliku SKILL.md oraz przedstawić zmianę w formie diffu do akceptacji przez użytkownika. To bardzo ważny etap określany jako human-in-the-loop. Człowiek jest stawiany tutaj w roli nadzorcy i to on finalnie decyduje, czy zaproponowana zmiana zostanie zaakceptowana, czy nie.

W ten sposób wiedza projektowa trafia do wersjonowanego repozytorium i staje się dostępna dla kolejnych sesji oraz członków zespołu. Każda kolejna sesja robocza – bez względu na to, czy jest uruchomiona przez tego samego dewelopera, czy przez nowego inżyniera w zespole – rozpoczyna się na wyższym poziomie dojrzałości technologicznej.

Dla ciekawskich: Aby bezpiecznie ewaluować i testować duże zmiany wprowadzane w repozytorium przez agenta, warto wyrobić sobie nawyk uruchamiania go w wyizolowanym środowisku (np. wykorzystując mechanizm Git Worktree dostępny z poziomu konsoli Antigravity). Pozwala to asystentowi kompilować i testować kod na osobnej gałęzi bez ryzyka uszkodzenia Twoich aktualnych, niezapisanych plików.

Zalety i wady podejścia CaaC

Wdrożenie paradygmatu Context as a Code w wymagających projektach drastycznie zmienia dynamikę pracy. Podejście to wymaga jednak chłodnego i obiektywnego osądu inżynieryjnego, opartego na analizie zysków i kosztów operacyjnych.

Zalety

Do głównych zalet należą:

1. Redukcja Time-To-Market i narzutu poznawczego: CaaC eliminuje potrzebę ciągłego, manualnego wprowadzania agenta w szczegóły techniczne i architektoniczne przy każdej nowej sesji (w tym przy zmianie modelu językowego na inny w obrębie tej samej sesji). Zamiast marnować czas na „szkolenie” asystenta od zera lub ręczne korygowanie jego błędów, inżynier przechodzi od razu do realizacji zadań, co drastycznie skraca czas dostarczania funkcjonalności.
2. Ograniczanie liczby błędnych decyzji modelu: Narzucenie twardych ram w postaci plików reguł i komend walidacji w repozytorium ogranicza liczbę niepożądanych decyzji modelu. Pozwala to również utrzymywać wersjonowaną bazę wiedzy projektowej dostępną bezpośrednio z repozytorium. Agent działa w ramach dodatkowych ograniczeń i wskazówek projektowych, co minimalizuje ryzyko wymyślania nieistniejących interfejsów lub niespójnych wzorców.
3. Mierzalne oszczędności finansowe: Błędy architektoniczne, które tradycyjnie ujawniają się dopiero na etapie integracji lub testów dynamicznych, są tutaj neutralizowane znacznie wcześniej dzięki zautomatyzowanym pętlom w CaaC. Natychmiastowa walidacja i możliwość szybkiego wycofania zmian drastycznie ograniczają liczbę rewizji kodu na późniejszych etapach projektu.
4. Wspólny, zsynchronizowany kontekst dla całego zespołu: Ponieważ baza wiedzy i wytyczne są wersjonowanym kodem w repozytorium Git, stają się one jedynym źródłem prawdy (Single Source of Truth). Wszyscy członkowie zespołu deweloperskiego pracują w oparciu o identyczny, spójny i automatycznie synchronizowany zestaw reguł oraz standardów przy każdym pobraniu kodu.

Wady

Nie należy również zapominać o pewnych wadach i zagrożeniach:

1. Wysokie koszty operacyjne (pobór tokenów): Należy bezwzględnie pamiętać, że to podejście może wiązać się z dużym kosztem finansowym w warstwie zużycia API. Orkiestracja agentów w ramach wieloetapowych przepływów pracy (workflows) wymaga ciągłego przesyłania logów, wyników pośrednich lub plików konfiguracyjnych, których treść z czasem rośnie, a to przekłada się bezpośrednio na liczbę konsumowanych tokenów. Element ten musi zostać uwzględniony w budżecie infrastruktury AI zespołu.
2. Zanieczyszczenia kontekstu: Jeśli w pliku `SKILL.md` agent zapisze błędną regułę optymalizacji lub niepoprawne założenie dotyczące modelu pamięci albo współbieżności, przy następnym uruchomieniu odczyta ten błąd jako niepodważalną prawdę projektową. Może to doprowadzić do wygenerowania błędów w działaniu aplikacji (np. race condition), które są niezwykle trudne do wyłapania podczas standardowych testów jednostkowych (każdy, kto tego szukał, doskonale wie, że ostatnią rzeczą, której potrzebujemy, jest AI dodająca nam kolejne błędy).
3. Zagrożenie bezpieczeństwa i podatność na ataki: Pliki .agents/ mogą zawierać instrukcje prowadzące do wykonywania komend powłoki w lokalnym środowisku agenta. Jeśli złośliwy Pull Request zmodyfikuje plik `AGENTS.md`, wprowadzając niebezpieczną komendę systemową, uruchomienie sesji agenta może doprowadzić do wykonania przez niego nieautoryzowanych poleceń w środowisku roboczym projektu.
4. Potencjalne konflikty między Skills, Rules, AGENTS: W dużych repozytoriach problemem mogą stać się również konflikty między regułami (Rules), umiejętnościami (Skills) i instrukcjami zawartymi w AGENTS.md poprzez wykluczające się wzajemnie instrukcje. Stąd istotnym elementem jest nadzór i weryfikacja zawartości tych plików. Warto także określić hierarchię źródeł prawdy (np. AGENTS.md > Rules.md > Skills.md), aby ograniczyć niejednoznaczności.

Embedded Systems

Oferujemy usługi R&D, projektowania, tworzenia i testowania systemów wbudowanych, zapewniając bezpieczeństwo i niezawodność Twoich technologii.

Oferta Embedded systems

Podsumowanie i kierunek rozwoju

Podejście Context as a Code redefiniuje pojęcie nowoczesnej inżynierii oprogramowania. Przenosi część uwagi programisty z implementacji pojedynczych fragmentów kodu na definiowanie procesów, reguł i architektury systemu. Traktowanie wytycznych dla agentów na równi z kodem produkcyjnym i trzymanie ich w wersjonowanym repozytorium rozwiązuje odwieczny problem utraty kontekstu deweloperskiego.

Aby jednak ten system działał sprawnie, zespoły deweloperskie muszą pożegnać się z chaosem dokumentacyjnym i kłaść większy nacisk na spisanie reguł i zasad. Agent bardzo szybko ujawni brakujące reguły projektowe, niejednoznaczne wymagania oraz niespójności w konfiguracji projektu.

Zacznij od prostego AGENTS.md i kilku reguł projektowych opierając się o przygotowane przykłady na GitHub. Nawet niewielka ilość dobrze utrwalonego kontekstu potrafi znacząco poprawić przewidywalność pracy agentów.

Źródła

1. Google Antigravity Documentation
2. Agents.md
3. Google Gemini GitHub
4. Google Antigravity – Wikipedia
5. Build Autonomous Developer Pipelines with Google Antigravity
6. Authoring Google Antigravity Skills
7. Best practices for Antigravity CLI
8. Getting Started with Google Antigravity
9. Google Antigravity Tutorial for Beginners: Build Your First App (Step-by-Step) – YouTube
10. How I gave Google Antigravity a real long-term memory : r/google_antigravity – Reddit