SDD na prática:
um backend Spring hexagonal, do papel ao Postgres

Vamos preparar as regras do projeto antes do primeiro código.

Inspecione o projeto e proponha um plano curto. Depois aguarde meu OK antes de editar.

Após aprovação, crie:
1. AGENTS.md como fonte principal, com: objetivo do serviço; Java 21 e Spring Boot; comandos pelo Maven Wrapper; arquitetura hexagonal; domínio e aplicação sem Spring/JPA; dinheiro com BigDecimal; sem Lombok; nenhuma dependência nova sem pedir; ler a spec indicada, planejar, aguardar OK, testar e mostrar diff.
2. CLAUDE.md contendo uma breve apresentação e a importação @AGENTS.md, para o Claude Code receber as mesmas regras.
3. .specs/README.md explicando que cada mudança terá contexto, tarefa, regras e definição de pronto, e que a pasta só entra no contexto quando o agente é instruído a lê-la.

Não altere pom.xml nem arquivos Java. Não crie infraestrutura ainda. Não faça commit. Ao terminar, mostre git status --short, diff dos arquivos rastreados e conteúdo dos arquivos novos; relacione cada arquivo ao pedido.

Leia AGENTS.md e .specs/README.md. Não implemente código.

Crie somente .specs/01-dominio-pedido.md com contexto, tarefa, regras e definição de pronto.

O domínio inicial terá Pedido, ItemPedido e StatusPedido. Use linguagem de comportamento antes de nomes de implementação. Inclua: quantidade e preço positivos; total derivado; dinheiro com BigDecimal; pedido novo começa ABERTO; adicionar item devolve novo pedido; pedido pago ou cancelado não aceita item; listas não podem ser modificadas por fora; nenhuma dependência de Spring/JPA. Pedido.novo cria um rascunho ABERTO e vazio com UUID; adicionarItem devolve outro objeto. ABERTO pode pagar ou cancelar; outras transições são recusadas. Use records e cópia defensiva. Na aula, c-1 compra CAFE-500: 2 x 18.90 = 37.80.

Na definição de pronto, transforme cada regra em caso de teste, incluindo erros. Não altere Java, pom.xml ou outros arquivos. Mostre a spec e destaque qualquer ambiguidade que eu precise decidir.

Leia AGENTS.md e .specs/01-dominio-pedido.md. Inspecione a estrutura atual.

Primeiro, proponha um plano com a lista exata de arquivos de produção e teste. Para cada arquivo, diga qual regra da spec ele atende. Não implemente até eu responder OK.

Após meu OK: implemente somente o domínio e seus testes; execute os testes pelo Maven Wrapper; corrija falhas sem ampliar o escopo; mostre o resultado dos testes, git diff --stat e uma revisão regra por regra da spec.

Não use Spring, JPA, Lombok, setters ou double no domínio. Não faça commit.

Atue como tutor de arquitetura para uma turma iniciante em hexagonal. Não altere arquivos.

Leia AGENTS.md, a spec 01 e o domínio implementado. Explique usando exatamente este projeto:
1. o que é o núcleo e por que Pedido fica nele;
2. a diferença entre port de entrada, caso de uso, port de saída e adapter;
3. quem chama quem ao criar um pedido;
4. para que lado apontam as dependências de código;
5. como testar CriarPedido sem Spring nem Postgres;
6. um exemplo de interface desnecessária que seria exagero.

Use frases curtas, mostre uma árvore de pacotes proposta e termine com cinco perguntas para a turma. Não proponha implementação ainda.

Leia AGENTS.md e .specs/01-dominio-pedido.md. Antes de editar, crie .specs/02-caso-de-uso-criar-pedido.md com o contrato abaixo e mostre seu plano. Aguarde meu OK.

O caso de uso recebe cliente e itens, recusa lista vazia, cria o domínio, salva por uma interface chamada Pedidos e devolve o pedido salvo. Crie um port de entrada CriarPedido, sua implementação CriarPedidoService e o port de saída Pedidos. A aplicação não pode importar Spring, JPA, HTTP ou adapters.

Após meu OK, implemente e teste com uma implementação em memória de Pedidos dentro do teste. Execute os testes pelo Maven Wrapper. Mostre os imports de aplicacao/, o resultado dos testes e o diff. Não crie Controller, JPA, DTOs, configuração ou commit.

Leia AGENTS.md e as specs 01 e 02. Inspecione o ambiente sem editar. Proponha um plano apenas para infra/docker-compose.yml com Postgres 16, serviço postgres, db/user/senha pedidos, porta local configurável e volume nomeado. Verifique conflito na porta 5432. Aguarde meu OK.
Após aprovação, crie o compose e suba somente esse serviço. Comprove pg_isready e SELECT 1. Não altere Java, pom.xml ou application.yml. Não remova containers/volumes alheios. Pare se o banco não estiver pronto e explique o erro. Mostre arquivos novos e modificados.

Leia AGENTS.md e specs 01/02. Proponha .specs/03-adapters-rest-e-jpa.md com as três provas: banco disponível; persistência pelo adapter; HTTP. Escreva a spec antes do Java. Apresente plano só do checkpoint 4B e aguarde meu OK.
Após aprovação, adicione SOMENTE Data JPA e PostgreSQL Driver ao pom. Crie entidades PedidoJpaEntity/ItemJpaEntity, repository Spring Data, mapper manual e PedidosJpaAdapter; application.yml para o Postgres local. Mantenha domínio e aplicação intactos, sem imports de framework. Não crie endpoint ainda.
Mapeie a tabela pedido; ID String/UUID do domínio, sem gerar outro ID; total derivado dos itens, sem coluna total. Cada item guarda sku, quantidade e precoUnitario. Use transação no adapter para mapear itens antes de fechar a sessão; open-in-view=false.
Preserve os testes unitários. Crie PedidosJpaAdapterIT (integração, execução explícita) e adapte o teste de contexto gerado para essa mesma convenção *IT; não o apague nem desative. Rode os testes unitários pelo Wrapper sem banco; depois execute explicitamente os *IT contra o Postgres: salvar pedido de c-1 com CAFE-500, 2 x 18.90, e recuperar por UUID, em uma nova transação. Verifique itens, status ABERTO e total 37.80. Mostre a consulta à tabela e o diff. Não crie H2, endpoint, Lombok ou MapStruct.

Leia AGENTS.md e specs 01/02/03. Antes de editar, complete na spec o contrato HTTP e proponha o plano. Aguarde meu OK.
Implemente POST /pedidos com PedidoRequest, PedidoResponse, PedidoController e config/CasosDeUsoConfig. O controller chama CriarPedido; não conhece JPA. Resposta 201 com UUID, clienteId, itens, status ABERTO e total. Preços e total em JSON são números decimais.
Autorize nesta etapa um PedidoExceptionHandler em adapters/entrada/rest: ItemInvalidoException e PedidoSemItensException viram 422 com mensagem; JSON malformado ou campos obrigatórios ausentes viram 400. Use @Valid para formato e presença; a regra quantidade/preço positivos continua no domínio. Não crie outros endpoints.
Após implementar, rode unitários sem banco e os *IT com Postgres. Inicie a aplicação e registre status HTTP e corpo para: CAFE-500, quantidade 2, precoUnitario 18.90 -> 201 e total 37.80; quantidade zero -> 422; itens vazios -> 422; JSON malformado -> 400. Nas recusas, comprove que nenhuma linha foi adicionada.
Consulte o pedido pelo UUID no banco, reinicie a aplicação e comprove que a mesma linha e seus itens continuam lá. Mostre testes, arquivos novos, diff e encerre somente o processo da aplicação que você iniciou. Não faça commit.