Cursor Rules Template: CQRS Event Sourcing with Axon Framework (Java)

Overview

This Cursor rules template provides a copyable, stack-specific .cursorrules configuration for a CQRS + Event Sourcing stack using Axon Framework on Java. It guides AI to produce safe, consistent guidance aligned with Axon patterns and Java best practices.

When to Use These Cursor Rules

• When implementing CQRS with Axon in Java, including commands, events, aggregates, and sagas.
• When adopting Event Sourcing with Axon’s Event Store and Snapshotting.
• When guiding AI-authored code and configuration to follow Axon conventions and Spring Security integration.
• When you want to enforce consistent project structure and testing pipelines.

Copyable .cursorrules Configuration

# Cursor Rules for Axon Framework (Java)
# Format: YAML-like for the Cursor AI rules parser (raw .cursorrules)
framework:
  name: Axon Framework
  language: Java
  stack: 'CQRS + Event Sourcing'
context: 'You are Cursor AI, guiding safe AI-assisted development for a Java Axon-based CQRS app with Event Sourcing. Stay within Axon conventions and Java standards.'
roles:
  - Framework Role & Context
  - Code Style and Style Guides
  - Architecture & Directory Rules
  - Authentication & Security Rules
  - Database and ORM patterns
  - Testing & Linting Workflows
  - Prohibited Actions and Anti-patterns
codeStyle: 'Google Java Style'
architecture:
  directories:
    - src/main/java
    - src/main/resources
  packages:
    - com.example.cqrs.app
  di: true
security:
  auth:
    method: spring-security
    tokens: [JWT, OAuth2]
database:
  eventStore: 'Axon Event Store backed by SQL (e.g., PostgreSQL)'
  snapshotting: true
  projections: true
testing:
  unit: JUnit 5
  integration: 'Spring Test + Axon TestKit'
  lint: Checkstyle
  ci: 'GitHub Actions'
prohibited:
  - 'Do not bypass aggregate boundaries or directly mutate event store outside Axon components'
  - 'Do not bypass...'

# End of Cursor Rules block

Recommended Project Structure

src/
  main/
    java/
      com/example/cqrs/app/
        application/
        domain/
        infrastructure/
        command/
        event/
        query/
        projection/
        axon/
        config/
    resources/
  test/
    java/
      com/example/cqrs/app/
        test/

Core Engineering Principles

• Explicit Axon CQRS boundaries: commands, events, and queries live in dedicated modules.
• Event Sourcing-first design with clear event schemas and versioning.
• Type-safe boundaries between aggregates and read models.
• Secure by default: integrate Spring Security with JWT/OAuth2 for command dispatch and query handling.
• Treat Cursor AI rules as a part of the codebase and CI.

Code Construction Rules

• Follow Axon Framework conventions for command handlers, aggregates, and event handling.
• Maintain a single source of truth for domain events and avoid direct persistence of read models in aggregates.
• Use repository patterns provided by Axon where applicable; avoid raw JDBC in domain logic.
• Document event schemas with adequate versioning in code comments and changelogs.
• Do not bypass command bus or event bus; let Axon orchestrate dispatching and processing.

Security and Production Rules

• Enforce authentication for command dispatch and read model queries using Spring Security and JWT/OAuth2.
• Enable CSRF protection where applicable; use stateless JWT-based sessions for APIs.
• Protect aggregates with access control on command handlers; log sensitive failures securely.

Testing Checklist

• Unit tests for each Command Handler and Event Handler with Axon TestKit.
• Integration tests for read models and projections against a test database.
• End-to-end tests for typical user journeys using in-memory event stores.
• Linting and formatting enforced in CI; run tests on push and PR.

Common Mistakes to Avoid

• Mixing read models with write models in the same aggregate.
• Directly mutating the event store outside Axon patterns.
• Ignoring event versioning and breaking compatibility in events.

FAQ

What is a Cursor Rules Template for Axon Java CQRS?

A Cursor Rules Template provides a copyable .cursorrules configuration that enforces Axon CQRS and Event Sourcing best practices in Java. It guides AI assistance to stay within framework conventions, supports safe code generation, and ensures consistent project structure.

How does this template guide Axon CQRS patterns?

The template prescribes command handlers, event handlers, aggregates, and sagas placement, with folder structure, event versioning, and projections guided by Cursor AI rules to avoid anti-patterns and ensure testability.

Can I customize security for command dispatch in this template?

Yes. The template includes Spring Security integration with JWT/OAuth2; you can adjust token validation, role checks, and per-command access controls while keeping safe defaults.

Where should I place project structure and tests?

Follow the provided directory tree under src/main/java for domain and application logic, and src/test/java for tests. Projections go under projection/read-model packages; tests use JUnit 5 and Axon TestKit.

What are common pitfalls when using Axon with Cursor AI?

Avoid bypassing aggregates, mixing write/read models in a single aggregate, or embedding SQL in domain logic. Ensure events are versioned and read models are independently evolved.