Prompts as Code: Ewolucja systemów agentowych i dekompozycja skilli w AOC

W miarę jak agenci w Agent Operations Center (AOC) zyskują coraz większą autonomię przy realizacji zadań, zarządzanie ich wiedzą domenową i instrukcjami stało się kluczowym wyzwaniem architektonicznym. Pojedyncze, ogólne zbiory reguł przestały wystarczać.

Problem: Monolityczne instrukcje i utrata ostrości kontekstu

Początkowo agenci operowali na wspólnym, globalnym zestawie zasad (m.in. reguły anti-slop.md). Choć twardy rygor eliminował złe wzorce w kodzie, podejście to miało istotną wadę: koder frontendowy, koder backendowy i inżynier bezpieczeństwa otrzymywali dokładnie te same instrukcje.

Wraz ze wzrostem liczby zadań pojawiły się konkretne problemy:

• Rozmycie uwagi modelu: Agent piszący komponent w React musiał przetwarzać instrukcje dotyczące transakcji SQLite i bindowania parametrów SQL, podczas gdy backendowiec czytał o stylach Tailwind CSS i dostępności (A11y).
• Duplikacja i chaos w rolach: W kodzie brokera funkcjonowały zduplikowane aliasy ról (np. sec obok security), co utrudniało jednoznaczne delegowanie zadań w systemie Kanban.
• Brak weryfikacji samych promptów: Instrukcje nie były testowane automatycznie pod kątem konfliktów, hardcodowanych sekretów czy podatności na prompt injection.

Co zrobiłem: Architektura Prompts as Code i bramka jakościowa

Zamiast monolitycznego promptu wdrożyłem modularny system umiejętności w katalogu skills/, czerpiąc z wzorców stosowanych w nowoczesnych konfiguracjach .mdc oraz frameworkach SWE-agent.

1. Dekompozycja na mikro-umiejętności (Skills)

Każda specjalizacja otrzymała własny plik SKILL.md z jawnie zdefiniowanym zakresem odpowiedzialności i kontraktem wyjściowym:

• backend-api-design (dla coder-backend, coder): Wymusza walidację wejścia schematami Zod, parametryzowane zapytania SQL zapobiegające SQL Injection oraz deterministyczną obsługę błędów w trybie fail-closed.
• frontend-react-components (dla coder-frontend, coder): Wymusza użycie unii dyskryminowanych dla stanów asynchronicznych, semantyczny HTML, standardy Tailwind CSS i zakaz pustych warunkowych spreadów obiektów.
• fullstack-feature-delivery (dla coder): Standard dla zadań end-to-end z backendem jako jedynym źródłem prawdy (Single Source of Truth) i synchronizacją typów TypeScript.
• sec-ops-vulnerability-scan oraz qa-regression-testing: Ujednolicony profil bezpieczeństwa (usunięcie zbędnego aliasu sec na rzecz jednoznacznego security).

2. Frontmatter jako interfejs maszynowy

Każdy plik skilla zawiera ustrukturyzowany nagłówek YAML:

---
name: "backend-api-design"
version: "1.0.0"
description: "Zasady projektowania i implementacji API Node.js, bezpieczeństwa baz danych i walidacji danych."
triggers:
  - "napisz backend"
  - "dodaj endpoint"
  - "backend api design"
  - "baza danych"
assignedAgents:
  - "coder-backend"
  - "coder"
---

3. Bramka ewaluacyjna (Tier 1 & Tier 2 Gate)

W lib/skills-registry.ts i skrypcie scripts/eval-skills.ts zaimplementowałem automatyczną walidację jakości:

• Tier 1 (Static & Security): Statyczna analiza treści skilla pod kątem braku hardcodowanych tokenów/kluczy API, niebezpiecznych poleceń powłoki (rm -rf, eval), kompletności metadanych oraz obecności sekcji Kryteria Akceptacji (Definition of Done).
• Tier 2 (Distinctiveness): Analiza konfliktów wyzwalaczy (triggers) między różnymi skillami, zapobiegająca niejednoznacznemu dopasowaniu reguł.

Dlaczego to ważne

Główna korzyść to izolacja i precyzja kontekstu. Gdy Product Manager zleca wdrożenie endpointu, broker ładuje wyłącznie skill backend-api-design. Agent skupia 100% okna kontekstowego na architekturze danych i walidacji Zod, bez zbędnego szumu informacyjnego.

Drugi zysk to ewolucyjna pewność kodu. Prompty i instrukcje zachowują się jak każdy inny moduł w repozytorium: podlegają wersjonowaniu w Git, przechodzą testy jednostkowe w CI/CD i posiadają jasną strukturę typów. Zmiana zasad bezpieczeństwa nie wymaga modyfikacji kodu aplikacji - wystarczy aktualizacja odpowiedniego pliku w skills/, która natychmiast jest weryfikowana przez bramkę jakościową.

Czego się nauczyłem

Traktowanie instrukcji dla agentów AI jako standardowego kodu (Prompts as Code) eliminuje niestabilność w systemach multi-agentowych. Zamiast rozbudowywać jeden nieczytelny system prompt, znacznie lepsze rezultaty daje dekompozycja na atomowe, testowalne umiejętności powiązane z konkretnymi rolami i triggerami.