Capsules and AI Agents in Product Development

Capsules in Action: Integrating AI Agents for Development Automation

AI agents in product development require strict context structure. Capsules provide expert knowledge in a minimalist format with ready-to-use tools, ensuring predictable code and architectural artifact generation. This eliminates chaotic architecture evolution during sequential tasks.

Agent Modes and the Role of Structure

Agents are used in prototyping and product development. In prototyping, the focus is on quick results without constraints. In products, non-functional requirements are mandatory: maintainability, readability, scalability.

Without structure, an agent makes arbitrary choices, losing service uniformity. A capsule solves this through three components:

• Expert Knowledge: Packaged experience without guesswork.
• Minimalism: The essence without extra information for the context window.
• Ready-to-Use Tool: Methods, skills, interfaces for agents.

Additional project context is stored in AGENTS.md and CLAUDE.md — style guides, commit formats.

Knowledge Transfer via MCP Server

Expert knowledge is transferred to the agent via an MCP server with two tools:

• Framework Documentation: Principles, service structure, BaseMethod patterns, DI container, events.
• archland.json Documentation: Format, filling rules, C4 diagram generation.

Separation saves tokens: the agent requests the relevant tool. Documents are agent-oriented — imperative style, rules, algorithms.

Example from the nsc-toolkit framework documentation:

# nsc-toolkit Framework: Code Generation Guide

This document is structured as a set of rules and templates
for automatic generation of correct code.

## Framework Core: Method Class (BaseMethod)

Implementation rules:
- Declare a static settings property,
  copied from service.schema.json.
- Main logic is implemented in the handler method.
- Inject dependencies via constructor with @inject decorator.
- Use this.logger for logging.
- Use this.emitter for event generation.

RULE: Create a method for each RPC call from service.schema.json.
RULE: Only current and used dependencies should be bound to the container.

Algorithm for archland.json:

Generation algorithm for each service:

Step 1. Basic information:
  - Read service.schema.json → name, description
  - Write paths: describePath, folderPath

Step 2. DI container analysis:
  - Read service.ts
  - For each container.bind() create a Dependency object
  - Analyze tags for type and external

Step 3. Method analysis:
  - For each class in methods/:
    read service.schema.json for description
    analyze code for dependency calls and event generation

Step 4. Subscription analysis:
  - For each class in processing/:
    determine DI key from inversion.types.ts
    analyze start() method to determine source service

Step 5. Collect all data into a single archland.json object

Practice: Adding a ListOrders Method

Scenario: A method for listing user orders in the @services/order service with exposure to the HTTP API.

The developer describes the data format. The agent generates the schema in service.schema.json:

"ListOrders": {
  "action": "ListOrders",
  "description": "Retrieving a list of user orders",
  "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 to the agent:

Create a new ListOrders method in the @services/order service.
The method accepts: user_id from credentials.
Returns: a list of orders, each with fields order_id, product_id, quantity, created_at.
Expose the method in @services/gate in the @services/gate/routes/orders.ts set of endpoints.

Sequence of agent actions:

• Reads CLAUDE.md → requests MCP documentation.
• Adds schema to service.schema.json.
• Runs code generation using templates.
• Implements business logic with @inject, ports.
• Adds HTTP endpoint following the pattern.
• Forms a commit according to rules.

Time: 10 minutes. The template is reproducible for similar tasks.

Generating an Architectural Album

Prompt: Generate archland.json and the project's architectural album.

The agent retrieves documentation from MCP, traverses services, analyzes schemas, DI, methods, subscriptions. Collects data into archland.json with C4 diagrams of problem areas. The process is deterministic based on the algorithm from the documentation.

Key Takeaways

• Capsules provide structure for agents in product development.
• MCP server transfers expert knowledge via minimalist tools.
• Documentation is imperative: rules, algorithms, templates for agents.
• Task automation: code generation, HTTP endpoints, arch albums in 10 min.
• Predictability: uniform architecture without chaotic changes.

— Editorial Team