Goal
Introduce patterns like CQRS, Clean Architecture, and Event Driven designs only when behavior requires them, and prove their value through real execution and tracing in Cursor or Replit Agent.
Rule Behavior
1️⃣ Start From Behavior, Not Pattern Names
- Identify pain first: duplication, tight coupling, fragile changes, or unclear flows
- Choose a pattern only when it clearly simplifies execution and testing
- Use runtime evidence to confirm that complexity is justified
2️⃣ Apply CQRS When Reads And Writes Diverge
- Separate command paths that change state from queries that only read
- Use dedicated command handlers for mutations
- Use query handlers for read models optimized for the UI
- Validate by running high load read and write flows independently
3️⃣ Use Clean Architecture For Testable Core Logic
- Keep core domain and use cases independent of frameworks
- Place business rules in inner layers that run without HTTP or database
- Keep controllers, ORM models, and UI adapters at the edges
- Execute use cases directly in tests and Agent runs without infrastructure
4️⃣ Adopt Event Driven Flows For Decoupling
- Emit domain events when important state changes occur
- Handle follow up work in subscribers instead of inline logic
- Ensure handlers are idempotent and safe to replay
- Use logs and traces to confirm event ordering and delivery
5️⃣ Validate Patterns Through Execution
- Run end to end flows before and after pattern introduction
- Confirm behavior is easier to observe, modify, and test
- Use Agent to trace calls across layers, handlers, or events
6️⃣ Avoid Over Engineering
- Do not apply CQRS or Clean Architecture to trivial features
- Introduce patterns at boundaries that show sustained complexity
- Remove unused abstractions that do not help runtime behavior
Examples
- "Refactor this combined read and write handler into CQRS style and run both paths."
- "Move business rules into a use case layer and execute it without HTTP."
- "Introduce a domain event for order created and show all subscribers that react to it."
Tool Prompts
- "Analyze this module and suggest where a pattern such as CQRS or Event Driven flow would reduce branching."
- "Refactor into Clean Architecture layers and run tests to confirm behavior is unchanged."
- "Trace event publishing and consumption for this workflow and list all handlers."
- "Compare logs before and after applying this pattern and highlight clarity improvements."
Quick Implementation Wins
- Extract use case functions for core behaviors and run them directly in tests
- Separate read and write routes where logic has become tangled
- Introduce simple domain events for high value state changes and log handler execution