From ec028b046538a71d0c16556ea9e3bcdc92a3ea17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Bre=C3=B1a=20Moral?= Date: Mon, 1 Jun 2026 13:26:34 +0200 Subject: [PATCH] feat(Skills): Adding first steps with Design patterns --- .../resources/skill-indexes/123-skill.xml | 71 ++++++ ...123-cross-cutting-integration-patterns.xml | 107 +++++++++ .../123-database-persistence-patterns.xml | 102 +++++++++ .../123-java-design-patterns.xml | 203 ++++++++++++++++++ .../123-kafka-event-driven-patterns.xml | 105 +++++++++ .../123-rest-api-patterns.xml | 128 +++++++++++ .../src/main/resources/skills.xml | 9 + 7 files changed, 725 insertions(+) create mode 100644 skills-generator/src/main/resources/skill-indexes/123-skill.xml create mode 100644 skills-generator/src/main/resources/skill-references/123-cross-cutting-integration-patterns.xml create mode 100644 skills-generator/src/main/resources/skill-references/123-database-persistence-patterns.xml create mode 100644 skills-generator/src/main/resources/skill-references/123-java-design-patterns.xml create mode 100644 skills-generator/src/main/resources/skill-references/123-kafka-event-driven-patterns.xml create mode 100644 skills-generator/src/main/resources/skill-references/123-rest-api-patterns.xml diff --git a/skills-generator/src/main/resources/skill-indexes/123-skill.xml b/skills-generator/src/main/resources/skill-indexes/123-skill.xml new file mode 100644 index 00000000..7769dfb4 --- /dev/null +++ b/skills-generator/src/main/resources/skill-indexes/123-skill.xml @@ -0,0 +1,71 @@ + + + + Juan Antonio Breña Moral + 0.16.0-SNAPSHOT + Apache-2.0 + Use when you need to select, review, or implement Java design and integration patterns — including classic Java design patterns, REST API patterns, Kafka and event-driven patterns, database and persistence patterns, and cross-cutting integration patterns. This should trigger for requests such as Apply Java design patterns; Review REST API patterns; Design Kafka event-driven patterns; Improve database persistence patterns; Add resilient integration patterns. + + + Java Design and Integration Patterns + + + + Pattern guidance must be problem-led, concrete, and safe to apply in Java projects. + + **PROBLEM FIRST**: Identify the design pressure before naming or applying a pattern + **NO PATTERN SHOPPING**: Do not add abstractions only because a pattern exists; prefer simple code when variation is not present + **BUILD SAFETY**: For code changes, run `./mvnw compile` or `mvn compile` before refactoring and `./mvnw clean verify` or `mvn clean verify` after changes + **REFERENCE SELECTION**: Read the relevant reference before acting: Java code patterns, REST API patterns, Kafka/event-driven patterns, database/persistence patterns, or cross-cutting integration patterns + **TRADE-OFFS REQUIRED**: Explain the benefit, cost, and when-not-to-use guidance for any recommended pattern + + + + + + Apply Java design patterns + Review Java code for design patterns + Choose REST API patterns + Design Kafka event-driven patterns + Improve database persistence patterns + Add resilient integration patterns + + + + + + Identify the design pressure + Clarify the concrete problem: object creation, behavior variation, API contract evolution, event delivery, persistence consistency, integration reliability, or another recurring design force. + + + Select the relevant reference + Read only the matching reference(s): `references/123-java-design-patterns.md`, `references/123-rest-api-patterns.md`, `references/123-kafka-event-driven-patterns.md`, `references/123-database-persistence-patterns.md`, or `references/123-cross-cutting-integration-patterns.md`. + + + Recommend the smallest useful pattern + Choose the simplest pattern that addresses the design pressure. Show how it changes responsibilities, boundaries, tests, operations, or evolution safety. + + + Implement or document the pattern + When code changes are requested, make focused Java or configuration changes following the project conventions. When design advice is requested, provide diagrams, examples, request/response shapes, event shapes, or transaction flows as appropriate. + + + Validate the outcome + Verify that the resulting design remains understandable, testable, and operationally safe. Run the project build for code changes and name any remaining trade-offs. + + + diff --git a/skills-generator/src/main/resources/skill-references/123-cross-cutting-integration-patterns.xml b/skills-generator/src/main/resources/skill-references/123-cross-cutting-integration-patterns.xml new file mode 100644 index 00000000..9eb6d742 --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/123-cross-cutting-integration-patterns.xml @@ -0,0 +1,107 @@ + + + + Juan Antonio Breña Moral + 0.16.0-SNAPSHOT + Apache-2.0 + Java Design and Integration Patterns + Use when designing or reviewing cross-cutting integration patterns — anti-corruption layers, strangler fig migration, bulkheads, timeouts, retries, backoff, circuit breakers, correlation ids, trace propagation, inbox, outbox, and reliable service boundaries. + + + You are a Senior software engineer with extensive experience in distributed Java systems, integration architecture, resilience, and observability + + + Design integration boundaries that isolate external complexity, fail predictably, propagate observability context, and support incremental system evolution. + + ### Pattern selection principles + + 1. **Protect the domain**: Use anti-corruption layers to translate external models into internal language. + 2. **Bound failure**: Combine timeouts, retries, circuit breakers, and bulkheads carefully to avoid amplifying outages. + 3. **Make flow observable**: Propagate correlation ids and trace context across HTTP, messaging, jobs, and database work. + 4. **Prefer reliable boundaries**: Use outbox and inbox patterns when side effects cross transactional systems. + 5. **Evolve incrementally**: Use strangler fig migration to replace legacy behavior behind stable routes or adapters. + + + + Cross-cutting patterns must reduce integration risk without hiding important failure modes. + + **TIMEOUTS REQUIRED**: Remote calls must have explicit timeouts before retries are considered + **RETRY WITH BACKOFF**: Never retry immediately in tight loops; use bounded attempts and jitter where appropriate + **NO DOMAIN POLLUTION**: Translate external DTOs and error models at the boundary + **OBSERVABILITY**: Preserve correlation and trace context through service and message boundaries + + + + + + + + + Use Anti-Corruption Layer for External Models + Translate legacy or third-party concepts at the boundary + + + + + + + + + + + + + + + Combine Timeout, Retry, and Circuit Breaker Carefully + Protect callers without overwhelming dependencies + + + + + + + + + + + + + + + + **MAP** external systems, trust boundaries, failure modes, latency budgets, and ownership boundaries + **SELECT** anti-corruption layer, strangler fig, timeout/retry/backoff, circuit breaker, bulkhead, inbox, outbox, or observability propagation patterns as needed + **DEFINE** operational behavior: limits, alerts, dashboards, replay procedures, and fallback expectations + **VALIDATE** resilience and observability through integration tests, failure injection where possible, and trace/log inspection + + + diff --git a/skills-generator/src/main/resources/skill-references/123-database-persistence-patterns.xml b/skills-generator/src/main/resources/skill-references/123-database-persistence-patterns.xml new file mode 100644 index 00000000..b5216351 --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/123-database-persistence-patterns.xml @@ -0,0 +1,102 @@ + + + + Juan Antonio Breña Moral + 0.16.0-SNAPSHOT + Apache-2.0 + Java Design and Integration Patterns + Use when designing or reviewing database and persistence patterns — repositories, unit of work, data mapper, aggregate boundaries, optimistic locking, migrations, CQRS read models, soft delete, multi-tenancy, sharding, connection pools, and N+1 avoidance. + + + You are a Senior software engineer with extensive experience in Java persistence, relational databases, transactions, and data modeling + + + Design persistence code around clear aggregate boundaries, explicit transaction scope, safe query behavior, schema evolution, and predictable operational characteristics. + + ### Pattern selection principles + + 1. **Transaction boundary first**: Know which invariants must be consistent together. + 2. **Domain boundary over table boundary**: Repositories should expose domain-oriented operations, not every table detail. + 3. **Explicit concurrency**: Choose optimistic or pessimistic locking based on contention and correctness needs. + 4. **Migration discipline**: Treat schema changes as versioned, reviewable, and reversible where possible. + 5. **Read/write separation when justified**: Use projections, materialized views, or CQRS only when query needs diverge from write models. + + + + Persistence patterns must protect data correctness while keeping queries and transactions understandable. + + **TRANSACTIONAL CLARITY**: Place transaction boundaries at use-case/service level unless the framework requires otherwise + **NO ENTITY LEAKAGE**: Do not expose persistence entities directly through REST or messaging contracts + **MIGRATION SAFETY**: Use versioned migrations for schema changes; avoid manual database drift + **QUERY VISIBILITY**: Watch for N+1 queries, unbounded result sets, and accidental eager loading + + + + + + + + + Use Repository for Domain-Oriented Persistence + Expose collection-like operations instead of database details + + + + + findById(OrderId id); + void save(Order order); + boolean existsOpenOrderFor(CustomerId customerId); +} + +record OrderId(String value) {} +record CustomerId(String value) {} +record Order(OrderId id, CustomerId customerId, OrderStatus status) {} +enum OrderStatus { NEW, CONFIRMED, CANCELLED }]]> + + + find(String table, String id); + List> query(String sql); + void execute(String sql); +}]]> + + + + + + + Use Optimistic Locking for Lost Update Protection + Reject stale writes instead of silently overwriting data + + + + + + + + + + + + + + + + **MODEL** aggregate boundaries, repository APIs, transaction scope, and consistency requirements + **SELECT** repository, unit of work, specification, locking, migration, projection, or multi-tenancy patterns based on data forces + **REVIEW** SQL/query shape, N+1 risks, indexes, result bounds, and connection-pool pressure + **VERIFY** persistence behavior with integration tests and migration validation + + + diff --git a/skills-generator/src/main/resources/skill-references/123-java-design-patterns.xml b/skills-generator/src/main/resources/skill-references/123-java-design-patterns.xml new file mode 100644 index 00000000..b519014d --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/123-java-design-patterns.xml @@ -0,0 +1,203 @@ + + + + Juan Antonio Breña Moral + 0.16.0-SNAPSHOT + Apache-2.0 + Java Design and Integration Patterns + Use when applying classic Java design patterns in application code — creational, structural, and behavioral patterns with practical Java 25 examples and explicit guidance against over-engineering. + + + You are a Senior software engineer with extensive experience in Java software design, refactoring, and pattern selection + + + Apply classic Java design patterns only when they solve a visible design pressure: repeated object creation rules, unstable implementation families, conditional behavior, cross-cutting decoration, or complex object collaboration. + + ### Pattern selection principles + + 1. **Problem signal before pattern name**: Start with the code smell or change pressure, not the catalog. + 2. **Prefer simple Java first**: Constructors, static factories, records, sealed interfaces, and small methods are often enough. + 3. **Keep boundaries testable**: A useful pattern should make tests easier to write or responsibilities easier to observe. + 4. **Avoid framework leakage**: Domain patterns should not depend on Spring, Quarkus, Micronaut, or persistence APIs unless the boundary explicitly belongs there. + 5. **Explain trade-offs**: Every pattern adds vocabulary and indirection; name when it is not justified. + + + + Classic patterns must improve clarity, substitution, or change safety in Java code. + + **MANDATORY**: Compile before and after pattern refactoring when changing code + **NO OVER-ABSTRACTION**: Do not introduce factories, strategies, decorators, or mediators for a single stable implementation + **MODERN JAVA**: Prefer records, sealed interfaces, enums, pattern matching, and immutable objects where they reduce ceremony + **TESTABILITY**: Add or update focused tests when a pattern changes dispatch, construction, or behavior selection + + + + + + + + + Use Strategy for Replaceable Policies + Replace growing conditionals with named behavior + + + + + + + + + + + + + + + Use Builder for Complex Immutable Construction + Keep required fields explicit and optional fields readable + + + + + + + + + + + + + + + Use Decorator for Additive Behavior + Add metrics, retries, or logging without changing the core implementation + + + + + + + + + + + + + + + + **IDENTIFY** the design pressure: creation, variation, collaboration, decoration, lifecycle, or state + **SELECT** the smallest useful pattern and name simpler alternatives + **IMPLEMENT** with modern Java features and project conventions + **TEST** behavior at the pattern boundary, especially strategy selection and decorators + **EXPLAIN** when not to use the pattern + + + diff --git a/skills-generator/src/main/resources/skill-references/123-kafka-event-driven-patterns.xml b/skills-generator/src/main/resources/skill-references/123-kafka-event-driven-patterns.xml new file mode 100644 index 00000000..427b509d --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/123-kafka-event-driven-patterns.xml @@ -0,0 +1,105 @@ + + + + Juan Antonio Breña Moral + 0.16.0-SNAPSHOT + Apache-2.0 + Java Design and Integration Patterns + Use when designing or reviewing Kafka and event-driven patterns — event schemas, partitioning keys, consumer groups, idempotent consumers, retry topics, dead-letter topics, outbox, CDC, sagas, CQRS projections, and event sourcing. + + + You are a Senior software engineer with extensive experience in Kafka, event-driven architecture, and Java messaging systems + + + Design Kafka and event-driven systems around reliable delivery, stable event contracts, explicit ordering boundaries, replay safety, and observable failure handling. + + ### Pattern selection principles + + 1. **Event purpose first**: Distinguish event notification, event-carried state transfer, command messages, and audit/event-sourcing streams. + 2. **Key for ordering**: Choose partition keys from business ordering needs, usually aggregate id, account id, customer id, or tenant id. + 3. **At-least-once by default**: Design consumers as idempotent because duplicates are normal in reliable messaging. + 4. **Schema evolution**: Version event contracts and maintain backward/forward compatibility. + 5. **Failure isolation**: Use retries, dead-letter topics, and replay procedures instead of losing or blocking messages silently. + + + + Kafka patterns must make delivery, ordering, schema evolution, and failure behavior explicit. + + **IDEMPOTENCY REQUIRED**: Consumers that change state must handle duplicate records safely + **KEY INTENTIONALLY**: Select partition keys based on ordering and load distribution, not convenience + **NO HIDDEN SCHEMAS**: Events must have explicit names, versions, and compatibility rules + **FAILURE PATHS**: Define retry, DLT, alerting, and replay behavior for poison records + + + + + + + + + Use Event-Carried State Transfer for Local Read Models + Publish enough state for consumers to update their own views + + + + + + + + + + + + + + + Use Transactional Outbox for Reliable Publishing + Persist domain state and outgoing events atomically + + + + + + + + + + + + + + + + **DESIGN** event name, payload, schema version, topic, key, headers, and consumer-group boundaries + **DEFINE** idempotency, retries, DLT, replay, ordering, and schema evolution behavior + **APPLY** outbox, inbox, saga, projection, or event-sourcing patterns only when their reliability or audit value is needed + **TEST** with realistic broker behavior, duplicate delivery, poison messages, and schema compatibility checks + + + diff --git a/skills-generator/src/main/resources/skill-references/123-rest-api-patterns.xml b/skills-generator/src/main/resources/skill-references/123-rest-api-patterns.xml new file mode 100644 index 00000000..8d2d58f0 --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/123-rest-api-patterns.xml @@ -0,0 +1,128 @@ + + + + Juan Antonio Breña Moral + 0.16.0-SNAPSHOT + Apache-2.0 + Java Design and Integration Patterns + Use when designing or reviewing REST API patterns — resource-oriented endpoints, DTO boundaries, idempotency, pagination, optimistic concurrency, Problem Details, API gateways, and resilient client interaction. + + + You are a Senior software engineer with extensive experience in REST API design, Java web applications, and distributed systems + + + Design REST APIs around stable resource contracts, predictable HTTP semantics, explicit error shapes, and evolvable client/server boundaries. + + ### Pattern selection principles + + 1. **Resource orientation**: Model URLs around domain resources and collections, not service method names. + 2. **Contract isolation**: Keep request and response DTOs separate from persistence entities and internal domain objects. + 3. **Retry safety**: Use idempotency keys and conditional requests when clients may retry. + 4. **Operational consistency**: Standardize pagination, filtering, sorting, error responses, rate limits, timeouts, and correlation IDs. + 5. **Client-specific adaptation**: Use Backend for Frontend only when client needs genuinely diverge. + + + + REST patterns must preserve HTTP semantics and make API contracts easier to evolve. + + **HTTP SEMANTICS**: Use methods, status codes, headers, and cache/concurrency semantics intentionally + **DTO BOUNDARY**: Do not expose persistence entities directly as public API contracts + **ERROR CONTRACTS**: Prefer RFC 9457-style Problem Details for machine-readable API errors + **IDEMPOTENCY**: For retryable state-changing operations, define idempotency behavior and storage requirements + + + + + + + + + Use Resource-Oriented Endpoints + Represent business resources instead of internal actions + + + + + + + + + + + + + + + Use Idempotency Key for Retryable Commands + Make client retries safe for create operations + + + + + + + + + + + + + + + Use Problem Details for API Errors + Return stable machine-readable errors + + + + + + + + + + + + + + + + **DESIGN** resource paths, HTTP methods, status codes, request DTOs, response DTOs, and error shapes + **DEFINE** pagination, filtering, sorting, idempotency, optimistic concurrency, and versioning rules when needed + **EXPLAIN** trade-offs between generic APIs, BFF endpoints, and domain-specific resources + **VALIDATE** API contracts with OpenAPI, integration tests, and negative cases for validation and conflict handling + + + diff --git a/skills-generator/src/main/resources/skills.xml b/skills-generator/src/main/resources/skills.xml index ea885ad2..37b89dca 100644 --- a/skills-generator/src/main/resources/skills.xml +++ b/skills-generator/src/main/resources/skills.xml @@ -105,6 +105,15 @@ 122-java-type-design + + + 123-java-design-patterns + 123-rest-api-patterns + 123-kafka-event-driven-patterns + 123-database-persistence-patterns + 123-cross-cutting-integration-patterns + + 124-java-secure-coding