Mert

Introdução

Hoje, quero te contar sobre uma experiência que tive com uma nova forma de desenvolver software, algo que me deixou realmente empolgada. É como quando você descobre aquela ferramenta que muda a forma como você faz tudo — e isso é exatamente o que o GitHub Speckit fez por mim!

O GitHub Spec Kit, ou Speckit, é uma solução incrível para o desenvolvimento software que segue a metodologia de Desenvolvimento Orientado a Especificações, ou SDD. Esse kit ajuda a estruturar ideias e documentações antes mesmo de começarmos a programar, permitindo um trabalho mais preciso e organizado, especialmente quando utilizamos IA.

Vamos mergulhar um pouco mais no que torna essa ferramenta tão especial?

O que é o GitHub Speckit?

O Speckit é como aquele amigo sábio que te guia em cada passo do desenvolvimento, garantindo que você esteja no caminho certo. Em vez de apenas te jogar na selva do código, ele ajuda a elaborar princípios de projeto, escopo, regras de clean code e requisitos de ponta a ponta.

Estrutura do Speckit

1. Arquitetura Estruturada: Instrui a IA a formar uma base sólida de princípios e requisitos.
2. Documentos Vivos: Funciona como um “mapa” que a IA consulta e atualiza constantemente.
3. Divisão de Tarefas (Tasking): Transforma projetos complexos em listas de tarefas menores, garantindo clareza e precisão.

Uma vez que você coloca as especificações do projeto no Speckit com o comando inicial /speckit.constitution, ele te guia, passo a passo, até a implementação final. Veja abaixo o passo a passo.

Passo a passo do Speckit

Vamos detalhar como cada comando do Speckit funciona e sua importância no fluxo de desenvolvimento:

Instalação

Para começar, você precisa instalar o Speckit em seu projeto com:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

A partir daqui, você pode iniciar o Speckit no diretório do projeto:

specify init . --integration opencode

Dica: Coloque a pasta .opencode no .gitignore, mas mantenha a .specify no repositório GitHub.

Estruturando o Desenvolvimento

/speckit.constitution

Aqui é onde você define as regras do projeto. Padrão de código… Digite no prompt do opencode, algo do tipo:

/speckit.constitution Este projeto segue princípios SOLID, testes obrigatórios, clean architecture

/speckit.specify

É usado para descrever o que você quer construir (features novas), e não para analisar código existente. Para documentar o que seu projeto já faz, você precisa descrever manualmente no comando:

/speckit.specify Meu projeto já existente faz A, B, C. Ele tem as seguintes funcionalidades: [detalhes]. Quero documentar isso como especificação.

/speckit.clarify

Use este comando para refinar seu pedido antes de seguir para a implementação:

/speckit.clarify

Este é o momento de esclarecer ambiguidades e melhorar a especificação com a ajuda da IA.

/speckit.plan

Transforma sua ideia em um plano estruturado, quebrando o problema em partes menores e etapas definidas:

/speckit.plan

/speckit.tasks

A partir do plano, gera uma lista de tarefas executáveis, simplificando o processo de desenvolvimento:

/speckit.tasks

/speckit.implement

Finalmente, tudo que foi planejado é transformado em código real:

/speckit.implement

Comparação e Experiência Prática

Experimentei o desenvolvimento do mesmo aplicativo em diferentes abordagens de IA. Primeiro, apenas com o OpenCode no VSCode, que demandou revisões constantes. Depois, usei a skill grill-with-docs, que foi um pouco mais organizada e me trouxe bons resultados, mas ainda exigia supervisão e revisão. Com o Github Speckit, porém, foi impressionante: um plano bem estruturado, passos audíveis e uma execução precisa, resultando em um programa que rodou sem erros na primeira tentativa.

Conclusão

A experiência com o Github Speckit me fez refletir sobre como as ferramentas de IA podem transformar nosso papel como desenvolvedores. Não se trata de substituir, mas sim de evoluir com o apoio de uma tecnologia que nos liberta das tarefas operacionais, possibilitando que o foco esteja na criação e no entendimento do projeto.

Então, para você que como eu ama tecnologia, vale a pena explorar o Speckit e ver como ele pode elevar o seu desenvolvimento a outro nível. Afinal, entender as origens e a lógica por trás de cada linha de código continua sendo nossa arte e talento insubstituíveis.

Introduction

One of the most consequential decisions in microservices architecture is data storage. Monolithic systems traditionally rely on a single relational database to service all needs — a model that worked well for decades but creates tight coupling, limits scalability, and forces every domain to conform to the same persistence paradigm regardless of whether it is the right fit.

Modern distributed systems have embraced a concept known as polyglot persistence — the practice of using different data storage technologies within the same system, each chosen to match the access patterns and characteristics of the domain it serves. A MVP e-commerce project examined in this document demonstrates this pattern in a concrete way: three different databases, each serving a distinct microservice, each chosen deliberately.

The Three-Database Architecture

The platform studied here organizes data across three specialized stores:

This is the Database per Service pattern [1]. Each service owns its database exclusively — no service reads directly from another’s store. This boundary enforces loose coupling and allows each team to evolve the schema independently without risk of cross-service breakage.

PostgreSQL for the Order Service: ACID as a Requirement

A relational database organizes data into tables — structured grids where every row is a record and every column is a typed, constrained attribute. Relationships between tables are expressed through foreign keys: a column in one table that references the primary key of another, letting the engine enforce referential integrity automatically. This rigid schema is not a limitation but a deliberate guarantee: every row must conform to the same structure, and the engine validates constraints at write time. The payoff is ACID — the ability to group multiple writes into a single all-or-nothing transaction that either commits fully or rolls back completely, leaving the database in a consistent state regardless of failures.

The Order Service persists financial records. An order is not just data — it is a legal artifact, a commitment. This makes ACID guarantees non-negotiable.

The service uses Spring Data JPA with Flyway for schema migrations. The schema reflects classical relational design: parent orders table with a child order_items table linked by a foreign key with ON DELETE CASCADE.

CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    user_id VARCHAR(255) NOT NULL,
    total DECIMAL(19, 2) NOT NULL,
    status VARCHAR(50) NOT NULL,
    order_date TIMESTAMP NOT NULL
);

CREATE TABLE order_items (
    id BIGSERIAL PRIMARY KEY,
    order_id BIGINT NOT NULL,
    product_id VARCHAR(255) NOT NULL,
    price DECIMAL(19, 2) NOT NULL,
    quantity INTEGER NOT NULL,
    CONSTRAINT fk_order FOREIGN KEY (order_id) REFERENCES orders (id) ON DELETE CASCADE
);

The OrderService.placeOrder() method is annotated with @Transactional. This ensures that if any step in the checkout flow fails — building the item list, calculating the total, persisting the record — the database rolls back to a consistent state. The JPA cascade configuration ensures that saving the parent Order entity also persists all child OrderItem entities in a single atomic operation.

Flyway provides versioned, reproducible migration scripts. On startup the service validates that the running schema matches the expected baseline, preventing “works on my machine” drift between environments [2].

MongoDB for the Product Service: Schema Flexibility at Catalog Scale

A document database stores data as self-describing records — typically JSON or BSON objects — where each document can carry a different set of fields. There is no enforced column list; a document simply contains whatever the application writes into it. Documents that represent the same concept live in a collection, but the engine does not require them to be structurally identical. This makes document databases well-suited to domains where the data model is heterogeneous.

Products have heterogeneous attributes: a laptop has RAM and storage, a t-shirt has size and color, a book has an ISBN and author. Fitting all of these into rigid relational columns requires either complex EAV (Entity-Attribute-Value) schemes or sparse nullable columns — both are maintenance burdens.

MongoDB’s document model stores each product as a self-describing JSON document. When the catalog team needs to add a new attribute category, no schema migration is required. The application code simply begins writing the new field, and existing documents remain valid.

The Product Service uses Spring Data MongoDB with repository abstraction:

@Document(collection = "products")
public class Product {
    @Id
    private String id;
    private String name;
    private String description;
    private BigDecimal price;
    private Integer stockQuantity;
    private String skuCode;
    private String category;
}

The @Document annotation maps the Java class to a MongoDB collection. Spring Data’s MongoRepository provides CRUD operations and dynamic query derivation without boilerplate SQL.

Redis for the Cart Service: Ephemeral State at Memory Speed

A key-value store is the simplest of all database models: every entry is a pair of a unique key and an associated value, with no enforced structure beyond that. There is no schema, no query language, and no relational machinery — retrieval is always by key, and the engine does nothing more than store and fetch the associated value as fast as possible. That simplicity is what makes key-value stores fast: without the overhead of parsing queries, enforcing constraints, or managing transaction logs, the engine can serve reads and writes at memory speed.

A shopping cart is session-like: it changes frequently, needs sub-millisecond read/write response times, and is inherently transient — if a cart is lost, the customer can simply re-add items. These characteristics make a relational database an inappropriate choice (too much transactional overhead for short-lived state) and a document database acceptable but not optimal.

Redis was designed precisely for this use case. As an in-memory data structure store, it delivers microsecond latency for key-value operations [3]. The Cart Service models cart data as a Redis Hash where the top-level key is cart:{userId} and the value is a JSON-serialized Cart object.

The custom RedisConfig configures a RedisTemplate with explicit serializers:

@Bean
public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
    RedisTemplate<String, Object> template = new RedisTemplate<>();
    template.setConnectionFactory(connectionFactory);

    ObjectMapper mapper = new ObjectMapper();
    JacksonJsonRedisSerializer<Object> serializer = new JacksonJsonRedisSerializer<>(mapper, Object.class);

    template.setKeySerializer(new StringRedisSerializer());
    template.setValueSerializer(serializer);
    template.setHashKeySerializer(new StringRedisSerializer());
    template.setHashValueSerializer(serializer);

    return template;
}

This configuration ensures keys are stored as human-readable strings (cart:user123) while values are stored as JSON, which is both inspectable via Redis CLI and portable across service restarts.

The Trade-offs: What This Architecture Costs

Polyglot persistence is not free. The benefits in autonomy and performance come with real operational costs. For example:

1. No cross-service joins. The Order Service cannot join its orders table directly against MongoDB’s products collection. In a monolith, a JOIN happens inside the database engine in microseconds with full transactional isolation. Across services, the equivalent operation is an HTTP round trip, which introduces variable latency and a dependency on network availability.

2. Eventual consistency. In the OrderService.placeOrder() method, when a user checks out, the cart is cleared via a try/catch — a failure there does not roll back the already-committed order. True cross-service transactions require the Saga pattern [4].

3. Operational overhead. Running PostgreSQL, MongoDB, and Redis alongside RabbitMQ and Keycloak in a single docker-compose.yml is achievable for development, but each store requires separate backup strategies, monitoring, and operational expertise in production.

Conclusion

The demo e-commerce platform described here demonstrates that polyglot persistence, when applied with intention, produces a system where each component operates at its natural best. PostgreSQL provides the ACID guarantees that financial records demand. MongoDB provides the flexibility that a diverse product catalog requires. Redis provides the speed that shopping cart interactions need.

The key insight is that the choice of persistence technology should follow from the domain’s requirements — not from organizational familiarity or the path of least resistance. In practice, this means asking a different set of questions before reaching for a database. Is the data relational, or is it a self-describing document with variable structure? Is consistency a hard requirement, or can the system tolerate brief divergence in exchange for availability and speed? Is the data long-lived and auditable, or ephemeral by nature? Each of these questions points toward a different storage paradigm, and no single engine answers all of them optimally.

Source code: github.com/dancodingbr/ecommerce

References

[1] Microservices.io. Pattern: Database per service. Available at: https://microservices.io/patterns/data/database-per-service.html

[2] Flyway. Why database migrations. Available at: https://documentation.red-gate.com/fd/why-database-migrations-184127574.html

[3] Redis. Get Started. Available at: https://redis.io/docs/latest/get-started/

[4] Microservices.io. Pattern: Saga. Available at: https://microservices.io/patterns/data/saga.html