Kapsle a AI agenti ve vývoji produktů

Kapsule v akci: integrace AI agentů pro automatizaci vývoje

AI agenti ve vývoji produktů vyžadují přísnou strukturu kontextu. Kapsule poskytují odborné znalosti v minimalistickém formátu s připravenými nástroji, zajišťují předvídatelnou generaci kódu a architektonických artefaktů. Tím se eliminuje chaotický vývoj architektury při sekvenčních úlohách.

Režimy práce agentů a role struktury

Agenti se používají při prototypování a produktovém vývoji. U prototypů je důraz na rychlý výsledek bez omezení. U produktů jsou povinné nefunkční požadavky: udržovatelnost, čitelnost, škálovatelnost.

Bez struktury agent dělá libovolná rozhodnutí, čímž ztrácí jednotnost služeb. Kapsule to řeší prostřednictvím tří komponent:

• Odborné znalosti: zabalená zkušenost bez hádání.
• Minimalismus: esence bez nadbytečných informací pro kontextové okno.
• Připravený nástroj: metody, dovednosti, rozhraní pro agenty.

Dodatečný kontext projektu je uložen v AGENTS.md a CLAUDE.md – styly, formáty commitů.

Přenos znalostí přes MCP server

Odborné znalosti jsou předávány agentovi přes MCP server se dvěma nástroji:

• Dokumentace frameworku: principy, struktura služeb, vzory BaseMethod, DI kontejner, události.
• Dokumentace archland.json: formát, pravidla vyplňování, generace C4 diagramů.

Rozdělení šetří tokeny: agent žádá relevantní nástroj. Dokumenty jsou orientovány na agenta – imperativní styl, pravidla, algoritmy.

Příklad z dokumentace frameworku nsc-toolkit:

# Framework nsc-toolkit: Průvodce pro generaci kódu

Tento dokument je strukturován jako soubor pravidel a šablon
pro automatickou generaci správného kódu.

## Jádro frameworku: třída metody (BaseMethod)

Pravidla implementace:
- Povinně deklarujte statickou vlastnost settings,
  zkopírovanou z service.schema.json.
- Hlavní logika je implementována v metodě handler.
- Vkládejte závislosti přes konstruktor s dekorátorem @inject.
- Používejte this.logger pro logování.
- Používejte this.emitter pro generaci událostí.

PRAVIDLO: Vytvořte metodu pro každé RPC volání z service.schema.json.
PRAVIDLO: Ke kontejneru musí být vázány pouze aktuální
a používané závislosti.

Algoritmus pro archland.json:

Algoritmus generace pro každou službu:

Krok 1. Základní informace:
  - Přečíst service.schema.json → name, description
  - Zapsat cesty: describePath, folderPath

Krok 2. Analýza DI kontejneru:
  - Přečíst service.ts
  - Pro každou container.bind() vytvořit objekt Dependency
  - Analyzovat tagy pro type a external

Krok 3. Analýza metod:
  - Pro každou třídu v methods/:
    přečíst service.schema.json pro popis
    analyzovat kód na volání závislostí a generaci událostí

Krok 4. Analýza odběrů:
  - Pro každou třídu v processing/:
    určit klíč DI z inversion.types.ts
    analyzovat metodu start() pro určení zdrojové služby

Krok 5. Shromáždit všechna data do jednotného objektu archland.json

Praxe: přidání metody ListOrders

Scénář: metoda pro seznam objednávek uživatele ve službě @services/order s předáním do HTTP API.

Vývojář popíše formát dat. Agent vygeneruje schéma v service.schema.json:

"ListOrders": {
  "action": "ListOrders",
  "description": "Získání seznamu objednávek uživatele",
  "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 agentovi:

Vytvoř novou metodu ListOrders ve službě @services/order.
Metoda přijímá: user_id z credentials.
Vrací: seznam objednávek, každá s poli order_id, product_id, quantity, created_at.
Přidej metodu do @services/gate v sadu endpointů @services/gate/routes/orders.ts.

Posloupnost akcí agenta:

• Čte CLAUDE.md → žádá MCP dokumentaci.
• Přidá schéma do service.schema.json.
• Spustí generaci kódu podle šablon.
• Implementuje obchodní logiku s @inject, porty.
• Přidá HTTP endpoint podle vzoru.
• Vytvoří commit podle pravidel.

Čas: 10 minut. Šablona je reprodukovatelná pro podobné úlohy.

Generace architektonického alba

Prompt: Vygeneruj archland.json a architektonické album projektu.

Agent z MCP získá dokumentaci, projde služby, analyzuje schémata, DI, metody, odběry. Shromáždí data do archland.json s C4 diagramy problematických oblastí. Proces je deterministický podle algoritmu z dokumentace.

Co je důležité

• Kapsule zajišťují strukturu pro agenty v produktovém vývoji.
• MCP server předává odborné znalosti minimalistickými nástroji.
• Dokumentace je imperativní: pravidla, algoritmy, šablony pro agenty.
• Automatizace úloh: generace kódu, HTTP endpointy, architektonická alba za 10 min.
• Předvídatelnost: jednotná architektura bez chaotických změn.

— Editorial Team