🎯

cqrs

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill cqrs

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/cqrs
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/cqrs/
  • All projects ~/.claude/skills/cqrs/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert CQRS (Command Query Responsibility Segregation) assistance covering command handlers, read projections, event denormalization, and asymmetric scaling. Use when separating read and write models, optimizing read performance, or pairing with Event Sourcing.

CQRS (Command Query Responsibility Segregation)

CQRS is a pattern that separates read and update operations for a data store. Instead of using a single model for both, you have a Command Model (Write) and a Query Model (Read).

When to Use

  • Asymmetric Read/Write Workloads: Systems where reads outnumber writes by 100:1 or 1000:1 and require independent horizontal scaling.
  • Complex Reporting & Search Views: Aggregating data across multiple aggregates into denormalized read stores (Elasticsearch, Read Replicas).
  • Collaboration & High Concurrency: Optimizing write performance and transactional consistency while delivering instant query responses.
  • Pairing with Event Sourcing: When state changes are captured as events and read models are asynchronously projected from event streams.

Quick Start

// Command Side (Write) - Optimized for Integrity
class CreateOrderCommand { ... }
class OrderAggregate {
    create(cmd: CreateOrderCommand) {
        // Validate business rules
        // Save to DB (Normalized / Event Store)
    }
}

// Query Side (Read) - Optimized for Speed
class GetOrderSummaryQuery { ... }
class OrderSummaryProjector {
    // Listens to "OrderCreated" event
    on(event) {
        // Update a flat "Read DB" (e.g., ElasticSearch, Redis, Document DB)
        // optimized for the specific UI view
    }
}

Core Concepts

Separation of Command and Query Models

Commands represent intent to mutate state (void return or ID); Queries request data without side effects:

Client
  β”œβ”€β”€ Command: POST /orders (CreateOrderCommand) ──→ Command Handler ──→ Write DB (Postgres)
  β”‚                                                                           β”‚ (CDC / Events)
  └── Query:   GET /orders/summary (OrderSummary) ←── Read Handler   ←── Read DB (Elastic/Redis)

Command Handlers with Explicit Domain Mutex

Validates permissions and business invariants before committing writes:

// commands/cancel-order.command.ts
export interface CancelOrderCommand {
  orderId: string;
  reason: string;
  requestedByUserId: string;
}

export class CancelOrderCommandHandler {
  constructor(private readonly orderRepo: OrderRepositoryPort) {}

  async handle(cmd: CancelOrderCommand): Promise<void> {
    const order = await this.orderRepo.getById(cmd.orderId);
    if (!order) throw new Error("Order not found");
    order.cancel(cmd.reason, cmd.requestedByUserId);
    await this.orderRepo.save(order);
  }
}

Materialized Read Projections

Updates optimized denormalized read views in response to domain events:

// projections/order-dashboard.projection.ts
export class OrderDashboardProjection {
  async onOrderCancelled(event: OrderCancelledEvent): Promise<void> {
    await redis.hset(`dashboard:order:${event.orderId}`, {
      status: "CANCELLED",
      cancelledAt: event.timestamp,
      cancellationReason: event.reason,
    });
  }
}

Common Patterns

Read-Model Projection with Event Handlers

Problem: Queries require aggregated data from multiple write models, causing slow and complex database joins.

Solution: Use an asynchronous projector to update a de-normalized, query-optimized document or key-value store:

interface OrderCreatedEvent {
  orderId: string;
  customerId: string;
  total: number;
  createdAt: string;
}

class OrderReadModelProjector {
  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
    await searchIndex.upsert("orders_summary", event.orderId, {
      id: event.orderId,
      customerId: event.customerId,
      totalAmount: event.total,
      placedAt: event.createdAt,
      status: "PLACED",
    });
  }
}

Best Practices

Do:

  • Make Queries Completely Side-Effect Free: Ensure queries never mutate database state or trigger transactional locks.
  • Embrace Eventual Consistency: Design client user experiences to anticipate small projection delays (optimistic UI updates).
  • Optimize Read Models for the UI: Structure read tables/documents to match the exact view model needed by frontend clients.
  • Use Dedicated Read Replicas: Direct query handlers to read replicas or fast key-value caches to protect the write primary.

Don't:

  • Apply CQRS globally to an entire system: Apply CQRS only to bounded contexts with complex requirements; simple CRUD benefits from standard MVC.
  • Share entities between Command and Query pipelines: Keep query handlers completely independent of domain aggregate classes.
  • Let read projections write back to the write store: Keep the data pipeline unidirectional.

Troubleshooting

ErrorCauseSolution
Stale DataLag between Command execution and Query update.UI design updates (spinners/optimistic updates); Check projector lag.
ComplexityOver-engineering.Revert to simple CRUD if the domain doesn't warrant separation.

References

More from this repository10