Kapsuły i agenci AI w rozwoju produktów

Kapsuły w akcji: integracja agentów AI do automatyzacji rozwoju oprogramowania

Agenty AI w rozwoju produktów wymagają ścisłej struktury kontekstu. Kapsuły dostarczają ekspercką wiedzę w minimalistycznym formacie z gotowymi narzędziami, zapewniając przewidywalną generację kodu i artefaktów architektonicznych. Eliminuje to chaotyczną ewolucję architektury przy zadaniach sekwencyjnych.

Tryby pracy agentów i rola struktury

Agenci są stosowani w prototypowaniu i rozwoju produktowym. W prototypach nacisk kładzie się na szybki rezultat bez ram. W produktach obowiązkowe są wymagania niefunkcjonalne: utrzymywalność, czytelność, skalowalność.

Bez struktury agent dokonuje arbitralnych wyborów, tracąc jednolitość usług. Kapsuła rozwiązuje to poprzez trzy komponenty:

• Wiedza ekspercka: spakowane doświadczenie bez zgadywania.
• Minimalizm: esencja bez zbędnych informacji dla okna kontekstowego.
• Gotowe narzędzie: metody, umiejętności, interfejsy dla agentów.

Dodatkowy kontekst projektu przechowywany jest w AGENTS.md i CLAUDE.md — wytyczne stylu, formaty commitów.

Przekazywanie wiedzy przez serwer MCP

Wiedza ekspercka przekazywana jest agentowi przez serwer MCP z dwoma narzędziami:

• Dokumentacja frameworka: zasady, struktura usług, wzorce BaseMethod, kontener DI, zdarzenia.
• Dokumentacja archland.json: format, zasady wypełniania, generacja diagramów C4.

Podział oszczędza tokeny: agent żąda odpowiedniego narzędzia. Dokumenty są zorientowane na agenta — styl imperatywny, reguły, algorytmy.

Przykład z dokumentacji frameworka nsc-toolkit:

# Framework nsc-toolkit: Przewodnik po generacji kodu

Ten dokument jest ustrukturyzowany jako zestaw reguł i szablonów
do automatycznej generacji poprawnego kodu.

## Rdzeń frameworka: klasa metody (BaseMethod)

Zasady implementacji:
- Obowiązkowo zadeklaruj statyczną właściwość settings,
  skopiowaną z service.schema.json.
- Główna logika implementowana jest w metodzie handler.
- Wstrzyknij zależności przez konstruktor z dekoratorem @inject.
- Użyj this.logger do logowania.
- Użyj this.emitter do generacji zdarzeń.

REGUŁA: Utwórz metodę dla każdego wywołania RPC z service.schema.json.
REGUŁA: Do kontenera powinny być powiązane tylko aktualne
         i używane zależności.

Algorytm dla archland.json:

Algorytm generacji dla każdej usługi:

Krok 1. Informacje podstawowe:
  - Odczytaj service.schema.json → name, description
  - Zapisz ścieżki: describePath, folderPath

Krok 2. Analiza kontenera DI:
  - Odczytaj service.ts
  - Dla każdego container.bind() utwórz obiekt Dependency
  - Przeanalizuj tagi dla type i external

Krok 3. Analiza metod:
  - Dla każdej klasy w methods/:
    odczytaj service.schema.json dla opisu
    przeanalizuj kod pod kątem wywołań zależności i generacji zdarzeń

Krok 4. Analiza subskrypcji:
  - Dla każdej klasy w processing/:
    określ klucz DI z inversion.types.ts
    przeanalizuj metodę start() dla określenia usługi-źródła

Krok 5. Zbierz wszystkie dane w pojedynczy obiekt archland.json

Praktyka: dodanie metody ListOrders

Scenariusz: metoda do listy zamówień użytkownika w usłudze @services/order z przekazaniem do API HTTP.

Deweloper opisuje format danych. Agent generuje schemat w service.schema.json:

"ListOrders": {
  "action": "ListOrders",
  "description": "Pobieranie listy zamówień użytkownika",
  "request": {
    "type": "object",
    "properties": {
      "credentials": {
        "type": "object",
        "properties": {
          "user_id":  { "type": "string" },
          "space_id": { "type": "string" }
        },
        "required": ["user_id", "space_id"]
      }
    },
    "required": ["credentials"]
  },
  "response": {
    "type": "object",
    "properties": {
      "result": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order_id":   { "type": "string" },
                "product_id": { "type": "string" },
                "quantity":   { "type": "number" },
                "created_at": { "type": "string" }
              },
              "required": ["order_id", "product_id", "quantity", "created_at"]
            }
          }
        }
      }
    },
    "required": ["result"]
  }
}

Prompt dla agenta:

Utwórz nową metodę ListOrders w usłudze @services/order.
Metoda przyjmuje: user_id z credentials.
Zwraca: listę zamówień, każde z polami order_id, product_id, quantity, created_at.
Przekaż metodę do @services/gate w zestaw endpointów @services/gate/routes/orders.ts.

Sekwencja działań agenta:

• Czyta CLAUDE.md → żąda dokumentacji MCP.
• Dodaje schemat do service.schema.json.
• Uruchamia generację kodu według szablonów.
• Implementuje logikę biznesową z @inject, portami.
• Dodaje endpoint HTTP według wzorca.
• Tworzy commit według zasad.

Czas: 10 minut. Szablon jest reprodukowalny dla podobnych zadań.

Generacja albumu architektonicznego

Prompt: Wygeneruj archland.json i album architektoniczny projektu.

Agent z MCP otrzymuje dokumentację, przegląda usługi, analizuje schematy, DI, metody, subskrypcje. Zbiera dane w archland.json z diagramami C4 obszarów problemowych. Proces jest deterministyczny algorytmem z dokumentacji.

Co jest ważne

• Kapsuły zapewniają strukturę dla agentów w rozwoju produktowym.
• Serwer MCP przekazuje wiedzę ekspercką minimalistycznymi narzędziami.
• Dokumentacja jest imperatywna: reguły, algorytmy, szablony dla agentów.
• Automatyzacja zadań: generacja kodu, endpointy HTTP, albumy architektoniczne w 10 min.
• Przewidywalność: jednolita architektura bez chaotycznych zmian.

— Editorial Team