cqrs
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill cqrsRun 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.
/cqrsInstall 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.
SKILL.md
View on GitHub β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
| Error | Cause | Solution |
|---|---|---|
Stale Data | Lag between Command execution and Query update. | UI design updates (spinners/optimistic updates); Check projector lag. |
Complexity | Over-engineering. | Revert to simple CRUD if the domain doesn't warrant separation. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill