From 9228eae569bf43c44a1e996d33b78647f95a7799 Mon Sep 17 00:00:00 2001 From: Guilherme Biff Zarelli Date: Mon, 13 Apr 2026 10:06:55 -0300 Subject: [PATCH 1/2] Update README skill references and add repo skills Add skill references across the main README sections, replace the ADR-only section with the repository docs flow, and introduce dedicated skills for Flyway decoupled migrations and observability. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .agents/skills/flyway-decoupled/SKILL.md | 54 ++++++++++++++++++++++++ .agents/skills/observability/SKILL.md | 54 ++++++++++++++++++++++++ AGENTS.md | 2 + README.md | 38 +++++++++++++++-- README.pt.md | 37 ++++++++++++++-- 5 files changed, 177 insertions(+), 8 deletions(-) create mode 100644 .agents/skills/flyway-decoupled/SKILL.md create mode 100644 .agents/skills/observability/SKILL.md diff --git a/.agents/skills/flyway-decoupled/SKILL.md b/.agents/skills/flyway-decoupled/SKILL.md new file mode 100644 index 0000000..582366a --- /dev/null +++ b/.agents/skills/flyway-decoupled/SKILL.md @@ -0,0 +1,54 @@ +--- +name: flyway-decoupled +description: Use when changing schema migrations, Flyway container wiring, or startup ordering for the template's decoupled migration flow. +--- + +# Flyway Decoupled + +Use when a schema or startup change must preserve this repository's pattern of running Flyway outside the Spring Boot process. + +## Destination + +- `resources/flyway/db/migration/*.sql` +- `resources/flyway/pom.xml` +- `resources/flyway/run-migration.sh` +- `Dockerfile` +- `.docker-compose-local/application.yaml` +- `.docker-compose-local/infrastructure.yaml` +- `README.md` only when developer-facing execution guidance changes + +## Use For + +- adding new versioned SQL migrations +- changing Flyway runner commands, locations, or connection variables +- adjusting startup ordering between the database, migration step, and application +- keeping local and deployment-like migration flows reproducible + +## Inputs + +1. Schema change or migration behavior to implement +2. Expected database URL, credentials, and migration location +3. Whether the change affects local startup, deployment startup, or both +4. Compatibility, rollback, or rollout expectations + +## Workflow + +1. Add or update versioned SQL files under `resources/flyway/db/migration/` using Flyway naming. +2. Keep migration execution decoupled from the Spring Boot startup path; prefer the dedicated runner script or migration service over in-app hooks. +3. Align `resources/flyway/pom.xml`, `run-migration.sh`, and compose environment variables when connection settings or migration locations change. +4. Preserve explicit startup ordering so the application waits for the migration step in `.docker-compose-local/application.yaml`. +5. Keep `.docker-compose-local/infrastructure.yaml` and the application startup flow coherent when the local stack also needs Flyway changes. +6. If the work changes operational recovery or rollout procedure, route to `docs-runbook`; if it changes long-lived migration strategy, route to `docs-design-doc` or `docs-adr`. + +## Output Shape + +1. Versioned migration files +2. Minimal wiring changes for Dockerfile, compose, or Flyway runner files +3. README or runbook follow-up only when operator behavior changed + +## Rules + +- Do not move schema migration responsibility back into the application startup unless the architecture intentionally changes. +- Keep migrations append-only and versioned; prefer new scripts over rewriting applied ones. +- Keep connection settings and migration locations aligned across compose files and runner scripts. +- Use `make run-all` as the default validation target when startup wiring changes. diff --git a/.agents/skills/observability/SKILL.md b/.agents/skills/observability/SKILL.md new file mode 100644 index 0000000..a8ad0c5 --- /dev/null +++ b/.agents/skills/observability/SKILL.md @@ -0,0 +1,54 @@ +--- +name: observability +description: Use when changing the local OpenTelemetry, Prometheus, Grafana, or Jaeger stack and its wiring to the application. +--- + +# Observability + +Use when telemetry collection, export, or local observability services change and the template's metrics and traces setup must stay coherent. + +## Destination + +- `.docker-compose-local/observability.yaml` +- `.docker-compose-local/config/otel-collector.yaml` +- `.docker-compose-local/config/prometheus.yaml` +- `.docker-compose-local/config/ds-prometheus.yaml` +- `.docker-compose-local/application.yaml` +- `README.md` only when access URLs or startup guidance changes + +## Use For + +- changing OTLP endpoints or application telemetry environment variables +- adjusting OpenTelemetry Collector pipelines, exporters, or processors +- changing Prometheus scraping or remote-write configuration +- updating Grafana datasource wiring or Jaeger exposure +- troubleshooting missing local metrics, traces, or dashboards + +## Inputs + +1. The affected signal or user-visible behavior: metrics, traces, dashboards, or collector flow +2. The config or service being changed +3. Expected URLs, ports, networks, and dependencies +4. Any application environment changes required for the new telemetry path + +## Workflow + +1. Start from `.docker-compose-local/application.yaml` and confirm how the app points to OTLP endpoints. +2. Follow the signal path through `.docker-compose-local/config/otel-collector.yaml`. +3. Keep downstream exporters and services aligned in `.docker-compose-local/observability.yaml`. +4. Preserve Grafana `:3000`, Prometheus `:9090`, Jaeger `:16686`, and OTLP `:4317/:4318` access paths unless a deliberate change is required. +5. Keep Prometheus and Grafana configuration in sync with the collector and service ports. +6. If the change affects operational response or support workflows, route to `docs-runbook`; if it changes cross-cutting platform design, route to `docs-design-doc`. + +## Output Shape + +1. Minimal stack or config changes across application wiring, collector, Prometheus, Grafana, or Jaeger +2. A clear telemetry path that remains coherent end to end +3. README or runbook updates only when developer-visible behavior changed + +## Rules + +- Keep the telemetry path coherent end to end: app -> OTEL collector -> Jaeger or Prometheus -> Grafana. +- Prefer config-as-code under `.docker-compose-local/` over manual container tweaks. +- Do not change developer-facing ports casually; update docs when you do. +- Use `make run-observability` as the default validation target, plus `make run-app` when application wiring changes. diff --git a/AGENTS.md b/AGENTS.md index 226ec23..943841b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,8 @@ Use these repository-native skills for common delivery workflows. For new produc - `.agents/skills/archunit-guard/SKILL.md` for diagnosing or preserving architecture rules enforced by ArchUnit - `.agents/skills/acceptance-scenario-scaffold/SKILL.md` for black-box acceptance coverage in the `acceptance-test/` module - `.agents/skills/api-doc-auditor/SKILL.md` for keeping OpenAPI and AsyncAPI output aligned with source code +- `.agents/skills/flyway-decoupled/SKILL.md` for decoupled database migration scripts, runner wiring, and startup ordering +- `.agents/skills/observability/SKILL.md` for local OpenTelemetry, Prometheus, Grafana, and Jaeger stack wiring ## Documentation Conventions diff --git a/README.md b/README.md index 061de1d..4844a14 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ CloudEvents of type `br.com.helpdev.sample.user.created` and enriches the user w ## **Architecture** +**Related skill:** [`hexagon-scaffold`](.agents/skills/hexagon-scaffold/SKILL.md) for adding feature slices that follow the template's hexagonal structure. + This project follows the **Hexagonal Architecture**, as proposed by Alistair Cockburn, focuses on **decoupling the application’s core business logic from its input and output mechanisms**. This design principle promotes adaptability, testability, and sustainability by encapsulating the application layer (business core) and exposing defined ports for interactions with external systems. @@ -65,6 +67,8 @@ acceptance-test ### **Architecture Tests** +**Related skill:** [`archunit-guard`](.agents/skills/archunit-guard/SKILL.md) for preserving and evolving the repository's architecture rules safely. + This architecture is warranted by [**ArchUnit tests**](application/src/test/java/br/com/helpdev/sample/ArchitectureTest.java) to ensure the project's compliance with the defined structure. These tests validate the project's adherence to the Hexagonal Architecture principles, @@ -76,6 +80,8 @@ _Read more about: [Garantindo a arquitetura de uma aplicação sem complexidade] ### **Acceptance Tests** +**Related skill:** [`acceptance-scenario-scaffold`](.agents/skills/acceptance-scenario-scaffold/SKILL.md) for Docker-based black-box scenarios in the `acceptance-test/` module. + To ensure robust testing, the **acceptance-test** module encapsulates the application within a Docker image and executes integration tests in an environment that closely mimics the real-world behavior of the application. This approach guarantees homogeneity in the application modules by restricting unit tests to the main application module, while handling integration tests separately within the acceptance-test module. @@ -145,6 +151,8 @@ environment. ### **The Flyway Database Migration Tool** +**Related skill:** [`flyway-decoupled`](.agents/skills/flyway-decoupled/SKILL.md) for versioned migrations, Flyway runner wiring, and startup ordering. + To ensure better startup performance and avoid concurrency issues in Kubernetes environments, **Flyway** has been implemented as a decoupled database migration tool. This design enables the migration process to run independently of the application. @@ -160,6 +168,9 @@ This approach enhances deployment reliability and maintains a clean separation o You see the sample how to execute in: [application docker-compose file](.docker-compose-local/application.yaml). ### **OpenAPI** + +**Related skill:** [`api-doc-auditor`](.agents/skills/api-doc-auditor/SKILL.md) for keeping generated API documentation aligned with the source code. + This project uses **Springdoc OpenAPI** to automatically document REST endpoints. 🔗 [Official OpenAPI site](https://swagger.io/specification/) @@ -171,6 +182,9 @@ After starting the application, access: - **OpenAPI specification in JSON**: [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs) ### **AsyncAPI** + +**Related skill:** [`api-doc-auditor`](.agents/skills/api-doc-auditor/SKILL.md) for keeping async contracts and generated docs aligned with the source code. + This project uses **Springwolf** to document asynchronous events (Kafka, RabbitMQ, etc.) with **AsyncAPI**. Kafka messages on the `user-events` topic follow the **CloudEvents structured JSON** format (`application/cloudevents+json`). @@ -189,6 +203,8 @@ functionalities: #### Observability Services +**Related skill:** [`observability`](.agents/skills/observability/SKILL.md) for the local OpenTelemetry, Prometheus, Grafana, and Jaeger stack. + See the stack: [docker-compose-observability.yaml](.docker-compose-local/observability.yaml) - **Grafana**: Visualization and monitoring dashboard, available at [http://localhost:3000](http://localhost:3000). @@ -206,12 +222,26 @@ These services are orchestrated using Docker Compose to ensure seamless setup an -## **Architectural Decision Records (ADR)** +## **Docs** + +**Related skills:** [`docs`](.agents/skills/docs/SKILL.md) as the entrypoint, then [`docs-spec`](.agents/skills/docs-spec/SKILL.md), [`docs-adr`](.agents/skills/docs-adr/SKILL.md), [`docs-design-doc`](.agents/skills/docs-design-doc/SKILL.md), [`docs-runbook`](.agents/skills/docs-runbook/SKILL.md), and [`docs-selective-persistence`](.agents/skills/docs-selective-persistence/SKILL.md). + +This template treats documentation as an active part of delivery, guided by repository skills instead of ad-hoc files. The entry point is +`.agents/skills/docs/SKILL.md`, which decides whether the change needs durable documentation, whether an existing document should be updated, or whether +explicitly no new document is needed. + +The flow works like this: -The project includes a dedicated folder for **Architectural Decision Records (ADR)**, located in the `docs/adr` directory. This folder documents key -architectural decisions made throughout the project, providing context, rationale, and implications for these choices. +1. Clarify scope first through definition, spec, or plan mode. +2. Route the work to the right artifact: + - **Spec** for scope, scenarios, constraints, and acceptance criteria (`docs/specs/` when created). + - **ADR** for long-lived architectural decisions and guardrails in [`docs/adr/`](./docs/adr/README.md). + - **Design Doc** for non-trivial structure, integrations, migrations, or risks in [`docs/design/`](./docs/design/README.md). + - **Runbook** for operations, rollout, rollback, support, and incident handling (`docs/runbooks/` when created). +3. When required, ADRs and design docs are written and aligned before implementation starts. +4. After planning or execution, `docs-selective-persistence` decides what remains durable and what should stay transient. -To learn more about the ADRs and explore the documented decisions, refer to the [ADR README](./docs/adr/README.md). +This keeps documentation lean, decision-oriented, and connected to execution instead of turning every discussion into a permanent artifact. ## **Contribute** diff --git a/README.pt.md b/README.pt.md index 0be271a..c99c477 100644 --- a/README.pt.md +++ b/README.pt.md @@ -16,6 +16,8 @@ Neste template, fornecemos um **endpoint de cadastro de usuário** que publica u ## **Architecture** +**Skill relacionada:** [`hexagon-scaffold`](.agents/skills/hexagon-scaffold/SKILL.md) para adicionar novas fatias de funcionalidade seguindo a estrutura hexagonal do template. + Este projeto segue a **Arquitetura Hexagonal**, conforme proposta por **Alistair Cockburn**, focando em **desacoplar a lógica de negócio principal da aplicação de seus mecanismos de entrada e saída**. Esse princípio de design promove **adaptabilidade, testabilidade e sustentabilidade**, encapsulando a camada de aplicação (núcleo de negócio) e expondo portas definidas para interação com sistemas externos.

@@ -62,6 +64,8 @@ acceptance-test ### **Architecture Tests** +**Skill relacionada:** [`archunit-guard`](.agents/skills/archunit-guard/SKILL.md) para preservar e evoluir com segurança as regras de arquitetura do repositório. + Esta arquitetura é garantida por meio de testes **ArchUnit**, que validam a conformidade do projeto com os princípios da Arquitetura Hexagonal, assegurando a separação de responsabilidades e a independência da lógica de negócio central em relação aos sistemas externos. _Read more about: [Garantindo a arquitetura de uma aplicação sem complexidade](https://medium.com/luizalabs/garantindo-a-arquitetura-de-uma-aplica%C3%A7%C3%A3o-sem-complexidade-6f675653799c)_ @@ -70,6 +74,8 @@ _Read more about: [Garantindo a arquitetura de uma aplicação sem complexidade] ### **Acceptance Tests** +**Skill relacionada:** [`acceptance-scenario-scaffold`](.agents/skills/acceptance-scenario-scaffold/SKILL.md) para cenários black-box baseados em Docker no módulo `acceptance-test/`. + Para garantir testes robustos, o módulo **acceptance-test** encapsula a aplicação dentro de uma imagem Docker e executa testes de integração em um ambiente que imita de perto o comportamento real da aplicação. Essa abordagem garante a homogeneidade nos módulos da aplicação ao restringir os testes unitários ao módulo principal, enquanto lida com testes de integração separadamente no módulo acceptance-test. Esta separação garante: @@ -135,6 +141,8 @@ Esta configuração garante uma experiência de desenvolvimento eficiente e cons ### **The Flyway Database Migration Tool** +**Skill relacionada:** [`flyway-decoupled`](.agents/skills/flyway-decoupled/SKILL.md) para migrações versionadas, wiring do Flyway e ordenação de startup. + Para garantir um melhor desempenho de inicialização e evitar problemas de concorrência em ambientes Kubernetes, o **Flyway** foi implementado como uma ferramenta de migração de banco de dados desacoplada. Este design permite que o processo de migração seja executado de forma independente da aplicação. Principais Características: @@ -148,6 +156,8 @@ Essa abordagem melhora a confiabilidade da implantação e mantém uma separaç Você pode ver um exemplo de como executar em: [arquivo docker-compose da aplicação](.docker-compose-local/application.yaml). ### **OpenAPI** +**Skill relacionada:** [`api-doc-auditor`](.agents/skills/api-doc-auditor/SKILL.md) para manter a documentação gerada da API alinhada com o código-fonte. + Este projeto utiliza o **Springdoc OpenAPI** para documentar automaticamente os endpoints REST. 🔗 [Site oficial da OpenAPI](https://swagger.io/specification/) @@ -159,6 +169,8 @@ Após iniciar a aplicação, acesse: - **Especificação OpenAPI em JSON**: [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs) ### **AsyncAPI** +**Skill relacionada:** [`api-doc-auditor`](.agents/skills/api-doc-auditor/SKILL.md) para manter contratos assíncronos e documentação gerada alinhados com o código-fonte. + Este projeto utiliza o **Springwolf** para documentar eventos assíncronos (Kafka, RabbitMQ, etc.) com **AsyncAPI**. As mensagens Kafka no tópico `user-events` seguem o formato **CloudEvents structured JSON** (`application/cloudevents+json`). @@ -177,6 +189,8 @@ essenciais: #### Observability Services +**Skill relacionada:** [`observability`](.agents/skills/observability/SKILL.md) para a stack local de OpenTelemetry, Prometheus, Grafana e Jaeger. + Veja a stack: [docker-compose-observability.yaml](.docker-compose-local/observability.yaml) - **Grafana**: Visualization and monitoring dashboard, available at [http://localhost:3000](http://localhost:3000). @@ -193,11 +207,26 @@ Veja a stack: [docker-compose-infrastructure.yaml](.docker-compose-local/infrast Esses serviços são orquestrados usando o Docker Compose para garantir configuração e operação perfeitas em um ambiente de desenvolvimento local. -## **Architectural Decision Records (ADR)** -O projeto inclui uma pasta dedicada para **Registros de Decisões Arquiteturais (ADR)**, localizada no diretório `docs/adr`. Esta pasta documenta as principais -decisões arquiteturais tomadas ao longo do projeto, fornecendo contexto, justificativa e implicações para essas escolhas. +## **Docs** + +**Skills relacionadas:** [`docs`](.agents/skills/docs/SKILL.md) como entrada, depois [`docs-spec`](.agents/skills/docs-spec/SKILL.md), [`docs-adr`](.agents/skills/docs-adr/SKILL.md), [`docs-design-doc`](.agents/skills/docs-design-doc/SKILL.md), [`docs-runbook`](.agents/skills/docs-runbook/SKILL.md) e [`docs-selective-persistence`](.agents/skills/docs-selective-persistence/SKILL.md). + +Este template trata a documentação como uma parte ativa da entrega, guiada por skills do repositório em vez de arquivos criados de forma ad hoc. O ponto +de entrada é `.agents/skills/docs/SKILL.md`, que decide se a mudança precisa de documentação durável, se um documento existente deve ser atualizado, ou se +explicitamente nenhum novo documento é necessário. + +O fluxo funciona assim: + +1. Primeiro, o escopo é esclarecido por definição, spec ou plan mode. +2. Depois, a necessidade é roteada para o artefato correto: + - **Spec** para escopo, cenários, restrições e critérios de aceite (`docs/specs/`, quando existir). + - **ADR** para decisões arquiteturais duráveis e guardrails em [`docs/adr/`](./docs/adr/README.md). + - **Design Doc** para estrutura não trivial, integrações, migrações ou riscos em [`docs/design/`](./docs/design/README.md). + - **Runbook** para operação, rollout, rollback, suporte e incidentes (`docs/runbooks/`, quando existir). +3. Quando necessários, ADRs e design docs são escritos e alinhados antes do início da implementação. +4. Após o planejamento ou a execução, `docs-selective-persistence` decide o que permanece durável e o que deve continuar transitório. -Para saber mais sobre os ADRs e explorar as decisões documentadas, consulte o [README do ADR](./docs/adr/README.md). +Com isso, a documentação fica enxuta, orientada a decisão e conectada à execução, em vez de transformar toda conversa em artefato permanente. ## **Contribua** From f1aaf9b67b63747a940945592448400f5aedae44 Mon Sep 17 00:00:00 2001 From: Guilherme Biff Zarelli Date: Mon, 13 Apr 2026 11:00:15 -0300 Subject: [PATCH 2/2] Mention docs article in README Reference the article about documentation as execution context in the Docs section of both README variants. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 ++ README.pt.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index 4844a14..68dbcba 100644 --- a/README.md +++ b/README.md @@ -243,6 +243,8 @@ The flow works like this: This keeps documentation lean, decision-oriented, and connected to execution instead of turning every discussion into a permanent artifact. +Read more about this perspective in [Documentacao na era da IA: quando a documentacao vira contexto de execucao](https://medium.com/@guilherme.zarelli/documenta%C3%A7%C3%A3o-na-era-da-ia-quando-a-documenta%C3%A7%C3%A3o-vira-contexto-de-execu%C3%A7%C3%A3o-cb8d6fdf84ed) _(Portuguese)_. + ## **Contribute** diff --git a/README.pt.md b/README.pt.md index c99c477..3fde0ea 100644 --- a/README.pt.md +++ b/README.pt.md @@ -228,6 +228,8 @@ O fluxo funciona assim: Com isso, a documentação fica enxuta, orientada a decisão e conectada à execução, em vez de transformar toda conversa em artefato permanente. +Leia mais em [Documentação na era da IA: quando a documentação vira contexto de execução](https://medium.com/@guilherme.zarelli/documenta%C3%A7%C3%A3o-na-era-da-ia-quando-a-documenta%C3%A7%C3%A3o-vira-contexto-de-execu%C3%A7%C3%A3o-cb8d6fdf84ed). + ## **Contribua**