- Andre Lucas
- Wed Mar 05 2026
AI-First Software Design: Além do CLAUDE.md
Tres meses atras eu comecei a construir um gerador de scaffold de microservicos com o Claude Code. A primeira semana foi eletrizante. Eu descrevia o que queria, o agente gerava boilerplate de Onion Architecture, conectava modulos Spring Boot, escrevia testes. Parecia um multiplicador de 10x.
Na segunda semana, o multiplicador tinha sumido.
O agente continuava violando o Outbox pattern que eu ja tinha explicado. Colocava anotacoes JPA dentro da domain layer. Gerava use cases como inner classes dentro de controllers. Toda sessao comecava comigo re-explicando as mesmas constraints arquiteturais -- as mesmas constraints que eu tinha explicado no dia anterior.
O problema nao era o modelo. O problema era que meu projeto nao tinha nenhuma estrutura persistente para uma IA entender. Eu estava tratando o agente como um dev junior que conseguia ler meus pensamentos. Ele nao consegue. Nenhum modelo consegue.
O Problema do Contexto Zero
Isso e o que acontece quando voce entrega ao Claude Code (ou Cursor, ou qualquer coding agent) um projeto sem contexto arquitetural explicito:
Session 1: "Add a cancel order use case"
Agent: Adds cancelOrder() method directly in OrderController
Uses JPA annotations in domain layer
No test written
→ You spend 20 minutes fixing it
Session 2: "Add a cancel order use case" (new session, same project)
Agent: Makes the same mistakes again
→ You spend another 20 minutes
Cada sessao e uma folha em branco. O agente nao tem memoria das suas decisoes arquiteturais. Ele nao sabe que seu projeto usa Onion Architecture. Nao sabe que a domain layer precisa ser livre de frameworks. Nao sabe que voce segue TDD e escreve o teste primeiro.
A pesquisa do Stack Overflow 2024 revelou que 65% dos desenvolvedores reportam que ferramentas de IA perdem contexto critico durante refactoring. A pesquisa da Qodo mostra que quando o contexto e selecionado manualmente, a IA perde relevancia em 54% dos casos -- mas quando o contexto e estruturado arquiteturalmente, esse numero cai para 16%.
A diferenca nao e prompting melhor. E design de projeto melhor. Explorei os fundamentos dessa mudanca em Vibe Coding é Engenharia — Não Mágica.
CLAUDE.md como Design Constraint
A maioria dos tutoriais trata o CLAUDE.md como um arquivo de configuracao. "Coloque seu estilo de codigo preferido aqui. Liste sua tech stack. Adicione algumas regras."
Isso erra o ponto completamente.
Um CLAUDE.md nao e documentacao para a IA. E uma constraint arquitetural -- da mesma forma que um ArchitectureTest.java enforced pelo ArchUnit e uma constraint. A diferenca e que o ArchUnit roda em compile time e faz o build falhar. O CLAUDE.md roda em generation time e impede o agente de escrever codigo que viola sua arquitetura antes mesmo de comecar.
Aqui vai uma secao do CLAUDE.md do Mars Enterprise Kit Lite -- um microservico de Order open-source com Onion Architecture, Kafka e PostgreSQL:
## Architecture
### Onion Architecture (Single Module, Package-Based Layers)
src/main/java/io/mars/lite/
├── domain/ # Domain Layer — NO JPA, NO Kafka, NO Web
│ ├── Order.java # Aggregate Root (record)
│ ├── OrderRepository.java # Port (interface)
│ └── usecase/
│ └── CreateOrderUseCase.java # @Service class
│
├── infrastructure/ # Infrastructure Layer — implements domain ports
│ ├── persistence/
│ │ └── OrderRepositoryImpl.java # Adapter
│ └── messaging/
│ └── OrderCreatedPublisher.java
│
└── api/ # API Layer — HTTP entry points
└── OrderController.java
Repare o que isso faz. Nao esta dizendo ao agente "a gente usa Onion Architecture." Esta mostrando ao agente a estrutura exata de pacotes, as convencoes de nomenclatura, quais anotacoes sao permitidas em qual camada, e o relacionamento entre ports e adapters. O agente le isso antes de escrever uma unica linha de codigo.
Mas a secao de constraints e onde mora o valor real:
## Code Generation Guidelines
**DO:**
- Use Java records for immutable domain objects
- Follow TDD strictly: test FIRST, then implement
- Use ports (interfaces) in domain/, adapters in infrastructure/
**DON'T:**
- Add JPA, Kafka, or Spring Web annotations in domain/ package
- Let domain/ depend on infrastructure/ or api/
- Write production code before a failing test
- Implement Outbox pattern (out of scope for Lite)
Isso nao e guia de estilo. E um conjunto de invariantes. Quando o agente le "DON'T add JPA annotations in domain/", ele trata isso como um limite rigido. Eu medi a diferenca: sem essas constraints, o Claude Code viola a Onion Architecture em aproximadamente 3 de cada 5 sessoes. Com elas, as violacoes caem para perto de zero.
graph TD
subgraph L1["Layer 1 — Constraints"]
C["CLAUDE.md<br/>Architecture rules<br/>Layer invariants<br/>Naming conventions<br/>Test strategy"]
end
subgraph L2["Layer 2 — Knowledge Base"]
D[".mars/docs/<br/>Structured architectural decisions<br/>Pattern rationale<br/>Trade-off documentation"]
end
subgraph L3["Layer 3 — Capabilities"]
S[".claude/skills/<br/>chaos-phantom-event/SKILL.md<br/>chaos-testing/SKILL.md<br/>exploratory-testing/SKILL.md"]
end
subgraph L4["Layer 4 — Workflows"]
W[".claude/commands/<br/>generate-prp.md<br/>execute-prp.md<br/>Git Worktree isolation"]
end
A["AI Agent<br/>(Claude Code)"] -->|"reads at session start"| L1
A -->|"loads on demand"| L2
A -->|"invokes when needed"| L3
A -->|"executes to deliver features"| L4
L1 -->|"defines boundaries for"| L2
L2 -->|"informs"| L3
L3 -->|"operates within"| L4
L4 -->|"produces"| OUT["Merge-ready code<br/>First attempt"]
style L1 fill:#0f3460,stroke:#e94560,color:#eaeaea
style L2 fill:#0f3460,stroke:#4ecca3,color:#eaeaea
style L3 fill:#0f3460,stroke:#533483,color:#eaeaea
style L4 fill:#0f3460,stroke:#4ecca3,color:#eaeaea
style A fill:#16213e,stroke:#e94560,color:#eaeaea
style OUT fill:#16213e,stroke:#4ecca3,color:#eaeaea
style C color:#eaeaea
style D color:#eaeaea
style S color:#eaeaea
style W color:#eaeaea
Alem do CLAUDE.md: A Arquitetura de Contexto
Aqui e onde a maioria dos desenvolvedores para. Escrevem um bom CLAUDE.md, veem melhoria imediata, e acham que acabou.
Nao acabou. CLAUDE.md e necessario mas insuficiente -- da mesma forma que um README e necessario mas insuficiente para fazer onboarding de um dev novo. O CLAUDE.md diz ao agente o que fazer. Uma arquitetura de contexto completa diz ao agente por que, como, e o que ja foi decidido antes.
O Mars Enterprise Kit usa uma arquitetura de contexto em camadas:
mars-enterprise-kit-lite/
├── CLAUDE.md # Layer 1: Constraints
├── .mars/
│ └── docs/
│ └── mars-enterprise-kit-context-lite.md # Layer 2: Knowledge Base
├── .claude/
│ ├── skills/
│ │ ├── chaos-phantom-event/SKILL.md # Layer 3: Capabilities
│ │ ├── chaos-testing/SKILL.md
│ │ └── exploratory-testing/SKILL.md
│ └── commands/
│ ├── generate-prp.md # Layer 4: Workflows
│ └── execute-prp.md
Cada camada tem um proposito distinto. Deixa eu detalhar.
Layer 1: CLAUDE.md -- O Que o Agente Deve Respeitar
Ja cobri acima. O CLAUDE.md define constraints: regras de arquitetura, convencoes de nomenclatura, estrategia de testes, direcao de dependencias. Ele e carregado no contexto no inicio de cada sessao, automaticamente. Pense nele como a memoria de trabalho do agente para "como esse projeto funciona."
Layer 2: .mars/docs/ -- O Que Ja Foi Decidido
O diretorio .mars/docs/ guarda a knowledge base persistente do projeto -- documentacao estruturada de decisoes arquiteturais. No Kit Lite, e um unico documento de contexto abrangente que cobre a arquitetura central, os patterns e os trade-offs. A ideia e emprestada de Architecture Decision Records (ADRs): cada decisao significativa e documentada com seu contexto, a decisao em si, consequencias e alternativas consideradas.
A diferenca critica em relacao a documentacao comum: esses documentos sao escritos para maquinas, nao apenas para humanos. Eles seguem uma estrutura consistente para que o agente consiga analisar programaticamente. Quando o agente precisa entender por que o projeto usa o Transactional Outbox pattern em vez de publicacao direta no Kafka, a justificativa esta documentada. Quando precisa entender por que o Redpanda e usado localmente em vez de um cluster Kafka completo, a analise de trade-off esta la.
O impacto e mensuravel. Sem documentacao estruturada de decisoes, ferramentas de IA tropeam em patterns especificos do projeto:
Developer: "Add a new event when order is cancelled"
AI (without context):
@PostMapping("/orders/{id}/cancel")
public void cancel(@PathVariable String id) {
orderRepository.updateStatus(id, "CANCELLED");
// WRONG: Forgot Outbox pattern
// WRONG: Direct repository access (violates Onion Architecture)
// WRONG: No domain event raised
}
AI (with context, reads structured decision docs):
public void cancel() {
this.status = OrderStatus.CANCELLED;
DomainEventPublisher.raise(new OrderCancelledEvent(this.id));
}
// Outbox automatically handles publishing
Se voce quiser entender por que o Outbox pattern e necessario antes de ler o ADR, o artigo sobre Arquitetura Event-Driven cobre a distincao entre evento e comando que motiva essa decisao.
Na minha experiencia, a diferenca e de aproximadamente 90% de codigo compativel com os patterns quando ha contexto estruturado vs. 40% sem. A diferenca de 50 pontos percentuais e o valor de contexto arquitetural persistente.
Layer 3: Skills -- O Que o Agente Consegue Fazer
Uma Skill, no contexto de agentes de IA para codigo, e uma instrucao operacional persistente que o agente carrega sob demanda quando precisa executar uma tarefa complexa especifica. Nao e documentacao. Documentacao descreve o que um sistema faz. Uma Skill diz ao agente como executar uma operacao passo a passo -- com comandos exatos, outputs esperados, tratamento de erros e a ordem em que as coisas precisam acontecer.
A distincao importa. Se voce escreve um README dizendo "este projeto usa chaos testing para validar o problema de Dual Write," o agente le e sabe que o conceito existe. Mas nao faz ideia de como de fato rodar o teste. Uma Skill da ao agente a sequencia de execucao completa: quais servicos iniciar, qual profile ativar, qual endpoint chamar, como a falha esperada se parece e como verificar o resultado. O agente sai de "eu sei que isso existe" para "eu consigo executar isso de forma autonoma."
Na pratica, plataformas como o Claude Code implementam Skills como arquivos Markdown armazenados em .claude/skills/. Cada Skill e uma pasta contendo um SKILL.md com frontmatter YAML (nome, descricao, hints de invocacao) e um corpo com instrucoes passo a passo. O agente descobre as Skills disponiveis no inicio da sessao e carrega a relevante no contexto quando a tarefa exige. O Cursor segue um padrao paralelo com .cursor/rules/ -- formato de arquivo diferente, mesmo principio subjacente: instrucoes estruturadas e persistentes que o agente le e executa, em vez de conhecimento generico sobre o qual ele tenta raciocinar.
A Anthropic levou isso adiante tornando Agent Skills um padrao aberto. A ideia e que uma Skill bem escrita deve ser portavel -- utilizavel por qualquer agente que implemente a spec. Seja rodando Claude Code, Cursor ou outro coding agent, o formato da Skill e o mesmo: instrucoes em Markdown que o agente carrega, interpreta e segue. Isso nao e teorico. E como o chaos testing do Mars Enterprise Kit Lite funciona na pratica.
Mas o que a maioria das discussoes sobre Skills nao menciona: voce nao consegue escrever uma Skill eficaz sem conhecimento profundo do dominio. A Skill chaos-phantom-event so existe porque eu conhecia o produto intimamente -- o fluxo correto de teste, o Spring profile que ativa o endpoint de chaos, o conflito de porta entre o schema registry do Redpanda e a aplicacao, a ordem exata de operacoes para reproduzir a falha de Dual Write. Escrever uma Skill nao e escrever documentacao. E codificar conhecimento operacional que ja existe na cabeca do desenvolvedor ou do arquiteto. Um agente sem essa Skill tentaria adivinhar o fluxo de teste e falharia nos detalhes criticos -- porta errada, Spring profile esquecido, ordem de operacoes incorreta. O dev precisa entender a logica de negocio e a arquitetura antes de conseguir traduzir esse conhecimento em uma Skill que o agente consiga executar de forma autonoma.
Com esse fundamento, aqui vai um exemplo concreto. No Mars Enterprise Kit Lite, Skills sao conjuntos de instrucoes autocontidos para operacoes complexas. Quando o agente precisa executar um chaos test para provar o problema de Dual Write, ele nao improvisa. Ele carrega a skill chaos-phantom-event e segue uma sequencia validada de 10 passos.
A skill chaos-phantom-event existe precisamente para provar o modo de falha do Dual Write — a inconsistencia que ocorre quando um evento Kafka e publicado mas a transacao do banco reverte.
Aqui vai o header da skill chaos-phantom-event do Kit Lite:
---
name: chaos-phantom-event
description: >
Run the Phantom Event chaos test against Mars Enterprise Kit Lite.
This skill starts infrastructure, builds and runs the app with
the "chaos" Spring profile, calls POST /chaos/phantom-event, and
validates the Dual Write failure: the Kafka event EXISTS but the
order does NOT exist in PostgreSQL (DB rolled back by AOP).
argument-hint: "[optional: number of phantom events to generate]"
---
A skill contem a sequencia de execucao completa: verificar infraestrutura, buildar a aplicacao, iniciar com o perfil chaos, registrar estado baseline, executar o phantom event, verificar a inconsistencia no PostgreSQL, verificar a inconsistencia no Kafka, imprimir prova, verificar que o fluxo normal ainda funciona, cleanup.
Cada passo tem comandos exatos, outputs esperados e orientacao de troubleshooting. O agente nao precisa descobrir como rodar um chaos test. Ele segue a skill.
Isso importa porque operacoes complexas tem modos de falha que nao sao obvios. A skill chaos-phantom-event, por exemplo, sabe que o endpoint de chaos retorna 404 se voce esquece de ativar o perfil Spring de chaos. Sabe que o schema registry do Redpanda conflita com a porta 8081, entao a aplicacao roda na 8082. Sao os detalhes que um agente sem skill erra na primeira tentativa.
Se quiser ver essas skills em acao, o Mars Enterprise Kit Lite tem a skill chaos-phantom-event completa com a sequencia de 10 passos, as constraints do CLAUDE.md e o scaffold de Onion Architecture — tudo pronto para producao e open-source. Veja a implementacao →
Layer 4: Workflows -- Como o Agente Entrega Features
O sistema PRP (Product Requirements Prompt) e como o agente recebe e executa pedidos de features. Um PRP e um documento estruturado que define escopo, criterios de aceitacao e passos de implementacao -- e o agente tem comandos para gerar e executar PRPs em Git worktrees isoladas.
---
name: git-worktree-prp
description: >
Manages Git Worktrees as an isolated development environment
whenever the user invokes /generate-prp or /execute-prp commands.
Every feature runs in its own worktree — completely isolated from
the main working directory.
---
O agente nunca comeca trabalho de implementacao direto na branch atual. Ele cria uma worktree, executa o PRP dentro dela, valida o resultado (compilacao, testes, checks de arquitetura) e so entao faz merge. E o mesmo workflow que um dev humano disciplinado seguiria -- so que codificado e repetivel.
Worktrees e paralelismo de agentes. A vantagem dos Git Worktrees vai alem do isolamento de uma unica feature. Com worktrees, voce consegue rodar multiplos agentes em paralelo -- cada um em uma branch isolada, sem conflitos de arquivo, sem interferencia de estado compartilhado. Enquanto um agente implementa a feature A no worktree 1, outro agente pode estar executando chaos tests no worktree 2. Quando cada um termina, entrega um resultado limpo e merge-ready na sua propria branch. Sem worktrees, agentes paralelos colidem: escrevem nos mesmos arquivos simultaneamente, corrompem o estado local, e o resultado e inutilizavel. Worktrees transformam o paralelismo de agentes de um conceito teorico em um workflow pratico.
O Que AI-First Design NAO Resolve
Preciso ser honesto sobre as limitacoes, porque nenhum artigo sobre esse assunto esta completo sem elas.
Nao elimina a revisao. O conselho do Martin Fowler se aplica aqui: trate cada output de IA como um pull request de um colaborador produtivo mas nao confiavel. Meu CLAUDE.md previne violacoes estruturais, mas nao pega erros sutis de logica de dominio. Eu ainda reviso cada mudanca.
Nao escala para contexto infinito. LLMs sofrem de context rot -- quanto mais tokens voce carrega, menos atencao cada token recebe. Conforme o projeto cresce e a documentacao expande, vai exceder o que cabe em uma unica context window. A solucao e carregamento em camadas: CLAUDE.md e sempre carregado, documentos de decisao sao carregados sob demanda, skills sao carregadas apenas quando invocadas. E por isso que a arquitetura e em camadas em vez de monolitica.
Nao funciona sem fundamentos. Se voce nao entende Domain-Driven Design, nao consegue escrever constraints que protejam domain boundaries. Se nao entende o Outbox pattern, nao consegue escrever um ADR que impeca o agente de implementar Dual Write. AI-First design amplifica expertise de engenharia. Nao substitui.
O custo de manutencao e real. Quando eu mudo uma decisao arquitetural, preciso atualizar o CLAUDE.md, os ADRs relevantes e qualquer skill afetada. Se a documentacao diverge do codigo, o agente gera codigo que corresponde aos docs desatualizados. E o mesmo problema que toda documentacao tem -- mas e pior aqui porque o agente confia nos docs implicitamente.
A Surpresa: AI-First Design Serve Humanos Tambem
Uma coisa que eu nao esperava quando comecei a construir esse sistema.
A mesma arquitetura de contexto que torna um projeto operavel por IA torna ele dramaticamente melhor para devs humanos. Quando suas decisoes arquiteturais estao documentadas em um formato estruturado e navegavel, onboarding vira questao de ler decisoes em sequencia em vez de fazer engenharia reversa da intencao a partir do codigo. Um dev novo pode comecar pelas decisoes fundacionais (estilo de arquitetura, limites de camadas) e progredir para as mais especificas (patterns de mensageria, estrategia de testes). No fim da primeira semana, ele entende nao apenas o que o projeto faz, mas por que cada decisao foi tomada.
A secao de constraints do CLAUDE.md funciona como checklist de code review. "DON'T add JPA annotations in domain/" e igualmente util para um revisor humano analisando um pull request.
As skills sao executaveis por humanos tambem. A sequencia de 10 passos da skill chaos-phantom-event e um procedimento legitimo de QA para validar o problema de Dual Write -- qualquer engenheiro consegue seguir manualmente.
Esse e o argumento real a favor de AI-First design: o investimento nao e para a IA. E para o sistema. A IA e apenas a forcing function que te faz ser explicito sobre decisoes que antes eram implicitas -- vivendo na cabeca do arquiteto, erodindo gradualmente conforme o time evolui.
graph LR
subgraph BEFORE["WITHOUT Context Architecture"]
direction TB
B1["Session start<br/>Zero context loaded"]
B2["Agent re-reads codebase<br/>~20 min reconstruction"]
B3["Generates code<br/>JPA in domain layer<br/>No test written<br/>Wrong pattern"]
B4["Developer corrects<br/>~25 min fix cycle"]
B5["Next session<br/>Same mistakes repeat"]
B1 --> B2 --> B3 --> B4 --> B5
B5 -->|"loop"| B2
end
subgraph AFTER["WITH Context Architecture"]
direction TB
A1["Session start<br/>CLAUDE.md auto-loaded"]
A2["Constraints active<br/>Architecture known<br/>Patterns understood"]
A3["Generates code<br/>Domain layer clean<br/>Test written first<br/>Outbox respected"]
A4["Developer reviews<br/>~5 min verification"]
A5["Merge-ready<br/>First attempt"]
A1 --> A2 --> A3 --> A4 --> A5
end
subgraph DELTA["Measured Difference"]
direction TB
M1["Fix time<br/>25 min -> 5 min"]
M2["Violations/session<br/>2-3 -> 0-1"]
M3["Attempts to merge<br/>3-4 -> 1"]
M4["Context re-explain<br/>~40% -> ~0%"]
end
BEFORE -.->|"add context architecture"| AFTER
AFTER -.->|"measured result"| DELTA
style BEFORE fill:#16213e,stroke:#e94560,color:#eaeaea
style AFTER fill:#16213e,stroke:#4ecca3,color:#eaeaea
style DELTA fill:#16213e,stroke:#533483,color:#eaeaea
style B1 fill:#0f3460,stroke:#e94560,color:#eaeaea
style B2 fill:#0f3460,stroke:#e94560,color:#eaeaea
style B3 fill:#0f3460,stroke:#e94560,color:#eaeaea
style B4 fill:#0f3460,stroke:#e94560,color:#eaeaea
style B5 fill:#0f3460,stroke:#e94560,color:#eaeaea
style A1 fill:#0f3460,stroke:#4ecca3,color:#eaeaea
style A2 fill:#0f3460,stroke:#4ecca3,color:#eaeaea
style A3 fill:#0f3460,stroke:#4ecca3,color:#eaeaea
style A4 fill:#0f3460,stroke:#4ecca3,color:#eaeaea
style A5 fill:#0f3460,stroke:#4ecca3,color:#eaeaea
style M1 fill:#0f3460,stroke:#533483,color:#eaeaea
style M2 fill:#0f3460,stroke:#533483,color:#eaeaea
style M3 fill:#0f3460,stroke:#533483,color:#eaeaea
style M4 fill:#0f3460,stroke:#533483,color:#eaeaea
Um Antes/Depois Concreto
Deixa eu quantificar a diferenca com base na minha experiencia construindo o Mars Enterprise Kit nos ultimos tres meses.
Sem arquitetura de contexto (primeiras duas semanas):
- Tempo medio para corrigir output do agente por sessao: ~25 minutos
- Violacoes de arquitetura por sessao: 2-3 (camada errada, testes faltando, pattern errado)
- Sessoes ate o agente produzir codigo merge-ready: 3-4 tentativas
- Tempo gasto re-explicando constraints: ~40% do tempo total da sessao
Com CLAUDE.md + .mars/docs/ + skills (ultimos tres meses):
- Tempo medio para corrigir output do agente por sessao: ~5 minutos
- Violacoes de arquitetura por sessao: 0-1 (geralmente naming/estilo, nao estrutural)
- Sessoes ate o agente produzir codigo merge-ready: 1 (primeira tentativa, maioria das tasks)
- Tempo gasto re-explicando constraints: ~0% (constraints estao no arquivo)
Os numeros sao aproximados -- nao rodei um experimento controlado. Mas a magnitude da diferenca e real. A arquitetura de contexto transformou o agente de uma ferramenta contra a qual eu lutava em uma ferramenta com a qual eu colaboro.
Conclusao
AI-First nao e uma feature que voce adiciona a um projeto. E uma disciplina de design. O CLAUDE.md e o ponto de entrada, nao o sistema. O sistema e a arquitetura de contexto em camadas -- constraints, knowledge base, skills, workflows -- que torna seu projeto operavel por qualquer agente (ou humano) que leia.
Se seu agente continua violando sua arquitetura, o problema nao e o modelo. O problema e que sua arquitetura nao e explicita o suficiente para o modelo seguir.
Comece pelo CLAUDE.md. Torne suas constraints reais. Depois construa as camadas ao redor.
A versao Lite te da o scaffold de Onion Architecture, as constraints do CLAUDE.md e tres skills de chaos testing -- o suficiente para comecar a aplicar essas ideias nos seus proprios projetos. Estou construindo uma versao PRO que expande a knowledge base com um conjunto completo de architectural decision records, documentacao AI-native e workflows coordenados por agentes. Se isso parece util, voce pode acompanhar o progresso aqui →