Modulo 4.6 - Prompts de Arquitetura e API Design

⚖️ Architecture Decision Prompt (Compare Options)

Decisoes de arquitetura sao as mais caras de reverter. Escolher entre monolito e microservicos, entre SQL e NoSQL, entre SSR e SPA, pode definir o sucesso ou fracasso do projeto. O Architecture Decision prompt forca o Claude a comparar opcoes sistematicamente antes de recomendar.

🎯 Conceito Principal

O prompt de Architecture Decision segue o formato ADR (Architecture Decision Record) adaptado para interacao com IA:

I need to decide: [decision to make].

Context:

- Team size: [N developers]

- Expected scale: [users/requests]

- Timeline: [deadline]

- Constraints: [budget, tech stack, team skills]

Compare options with:

1. Pros and cons of each

2. Complexity to implement

3. Long-term maintenance cost

4. Risk assessment

5. Your recommendation and why

• Contexto e crucial: A melhor arquitetura para 3 devs e diferente da melhor para 30. O Claude precisa saber o contexto real para recomendar corretamente
• Comparacao estruturada: Em vez de pedir "o que devo usar?", voce pede uma analise comparativa. Isso elimina o vies de confirmacao
• Custo de manutencao: A opcao mais rapida de implementar nem sempre e a melhor. O Claude avalia o custo total ao longo do tempo
• Recomendacao justificada: O Claude nao so compara, mas recomenda. E explica o raciocinio, para voce poder concordar ou discordar com base em fatos

💡 Dica Pratica

Salve o output do Architecture Decision como ADR no repositorio (pasta docs/adr/). Decisoes de arquitetura documentadas sao invaluaveis quando alguem pergunta "por que fizemos assim?" daqui a 6 meses.

Depois da recomendacao, faca follow-up: "Now assume I chose [option]. What are the first 5 things I should implement to set up this architecture correctly?"

🔌 API Design Prompt (REST API)

APIs mal projetadas geram dor por anos. Naming inconsistente, paginacao ausente, versionamento inexistente, respostas de erro sem padrao. O API Design prompt faz o Claude projetar APIs profissionais desde o primeiro endpoint, seguindo boas praticas de REST e da industria.

🎯 Conceito Principal

O prompt de API Design cobre todas as dimensoes de uma API bem projetada:

Design a REST API for [domain/feature].

Include:

1. All endpoints (method + path + description)

2. Request/response schemas (with examples)

3. Authentication strategy

4. Pagination approach

5. Error response format (consistent)

6. Versioning strategy

7. Rate limiting recommendations

Follow REST best practices and use consistent naming.

• Endpoints completos: O Claude gera a lista inteira de endpoints com metodo HTTP correto, path semantico e descricao clara
• Schemas com exemplos: Request e response bodies com exemplos reais. Isso serve como documentacao instantanea
• Error format consistente: Um formato padrao para erros (ex: {error: {code, message, details}}) em toda a API. Facilita o frontend e integradores

💡 Dica Pratica

Depois de gerar o design da API, peca ao Claude: "Now generate the OpenAPI 3.0 spec for this API." Voce recebe um arquivo YAML que pode ser importado diretamente no Swagger UI, Postman ou qualquer ferramenta de documentacao de API.

Para APIs publicas, adicione: "This API will be consumed by third-party developers. Include comprehensive documentation, clear error messages, and idempotency keys for write operations."

🗄️ Database Schema Prompt

O schema do banco de dados e a fundacao de tudo. Um schema mal projetado gera queries complexas, performance ruim e migracoes dolorosas. O Database Schema prompt faz o Claude modelar dados pensando em queries, performance e evolucao do schema ao longo do tempo.

🎯 Conceito Principal

O prompt de Database Schema vai alem de "crie tabelas". Ele considera o uso real dos dados:

Design a database schema for [domain].

Requirements:

- [list main entities and relationships]

- [list main queries/access patterns]

Include:

1. Tables with columns, types, and constraints

2. Indexes optimized for the query patterns above

3. Foreign keys and relationships

4. Normalization decisions (and when to denormalize)

5. Migration SQL

• Access patterns primeiro: Definir como os dados serao lidos antes de definir como serao armazenados. Isso guia decisoes de indexacao e desnormalizacao
• Indexes otimizados: O Claude cria indexes baseados nos patterns de query que voce listou. Nao indexes genericos, mas indexes que aceleram suas queries reais
• Decisoes de normalizacao: Nem tudo deve ser normalizado. O Claude explica quando desnormalizar para performance e quando manter normalizado para consistencia
• Migration SQL pronta: O output ja inclui o SQL de migracao que voce pode rodar diretamente ou adaptar para o ORM do seu projeto

💡 Dica Pratica

Sempre liste os access patterns mais frequentes no prompt. "Users will query orders by date range with status filter" e muito mais util que "I need an orders table". O Claude otimiza indexes compostos para exatamente esses patterns.

Apos o schema inicial, peca: "Now stress-test this schema. What happens with 10M rows in orders? What queries will become slow? What indexes should we add proactively?"

🌐 System Design Prompt (Distributed)

System design vai alem de um unico servico. Envolve multiplos componentes, comunicacao entre servicos, filas, caches, CDNs e tolerancia a falhas. O System Design prompt faz o Claude pensar como arquiteto de sistemas distribuidos, considerando escalabilidade, resiliencia e custos.

🎯 Conceito Principal

O prompt de System Design cobre todas as camadas de um sistema distribuido:

Design a system for [use case].

Scale requirements:

- [N] daily active users

- [N] requests per second (peak)

- [N] GB data stored

Include:

1. High-level architecture diagram (text)

2. Service boundaries and responsibilities

3. Data flow for main use cases

4. Caching strategy

5. Queue/async processing needs

6. Failure scenarios and mitigation

7. Estimated infrastructure costs

• Numeros reais: Fornecer DAU, RPS e volume de dados permite ao Claude dimensionar corretamente. Sem numeros, o design fica generico demais
• Failure scenarios: O que acontece se o cache cai? Se um servico fica indisponivel? O Claude projeta fallbacks e circuit breakers
• Custos estimados: O Claude estima custos de infra baseado nos numeros fornecidos. Isso ajuda a validar se o design cabe no orcamento

💡 Dica Pratica

Use o System Design prompt nao so para projetos novos, mas tambem para entender e documentar sistemas existentes. Descreva os componentes atuais e peca: "Given this current architecture, identify bottlenecks and propose an evolution path for 10x the current scale."

Para startups em estagio inicial: "Design this for 1000 users initially, but plan the architecture so it can scale to 1M users without a complete rewrite. Show what changes at each scale milestone."

🔄 Migration Planning Prompt

Migracoes sao as tarefas mais arriscadas em engenharia de software. Migrar banco de dados, trocar framework, atualizar major version, mover para cloud. Cada uma pode quebrar tudo se mal planejada. O Migration Planning prompt forca o Claude a planejar migracoes com zero-downtime e rollback garantido.

🎯 Conceito Principal

O prompt de Migration Planning cria um plano detalhado com fases, rollback e verificacao:

Plan a migration from [current] to [target].

Current state: [describe current setup]

Target state: [describe desired end state]

Constraint: zero downtime required

Provide:

1. Step-by-step migration phases

2. Rollback plan for each phase

3. Data migration strategy

4. Verification checks between phases

5. Risk assessment per phase

6. Estimated timeline

• Fases incrementais: Nunca migre tudo de uma vez. O Claude divide em fases que podem ser executadas e verificadas independentemente
• Rollback por fase: Cada fase tem seu proprio plano de rollback. Se a fase 3 falha, voce volta so a fase 3, nao o projeto inteiro
• Verificacao entre fases: Checks automaticos que confirmam que cada fase completou com sucesso antes de avancar para a proxima

💡 Dica Pratica

O segredo de migracoes bem-sucedidas e o pattern "strangler fig": o novo sistema cresce em paralelo com o antigo ate substitui-lo completamente. Mencione isso no prompt: "Use strangler fig pattern. Both systems run in parallel during migration."

Sempre peca estimativa de timeline por fase. "Phase 1: 2 days, Phase 2: 1 week" ajuda voce a planejar sprints e comunicar stakeholders sobre o progresso da migracao.

🔍 Architecture Review Workflow

O Architecture Review combina todos os prompts anteriores num workflow completo para avaliar e melhorar a arquitetura existente. Em vez de projetar do zero, voce alimenta o Claude com a arquitetura atual e ele identifica problemas, sugere melhorias e prioriza mudancas.

🎯 Conceito Principal

O workflow de Architecture Review segue 4 etapas para avaliar qualquer sistema existente:

• Etapa 1 - Mapeamento: "Read the codebase and describe the current architecture. Include: services, databases, APIs, queues, external integrations." O Claude mapeia o que existe
• Etapa 2 - Analise: "Given this architecture, identify: single points of failure, scaling bottlenecks, coupling issues, and technical debt." O Claude aponta problemas
• Etapa 3 - Proposta: "Propose improvements prioritized by: impact (high/medium/low) and effort (days/weeks/months)." O Claude sugere com priorizacao
• Etapa 4 - Roadmap: "Create a migration roadmap from current to target architecture. Group changes into quarters." O Claude gera o plano de evolucao

Importante: Cada etapa usa o output da anterior. Nao pule etapas. O mapeamento preciso na etapa 1 e a base para analises corretas nas etapas seguintes.

💡 Dica Pratica

Rode o Architecture Review trimestralmente em projetos ativos. A arquitetura evolui organicamente e problemas se acumulam gradualmente. Uma review trimestral pega tech debt antes que se torne critico.

Compartilhe o output com o time. O mapeamento da etapa 1 e especialmente valioso para onboarding de novos membros. Eles ganham visao completa do sistema em minutos.

✎

Exercicio Pratico

Projetar API REST completa usando prompts de arquitetura

Escolha um dominio (e-commerce, rede social, sistema de reservas) e projete a API completa:

1. Use o Architecture Decision para decidir entre monolito vs microservicos para o seu dominio. Documente a decisao
2. Use o Database Schema prompt para modelar as entidades principais. Inclua pelo menos 5 tabelas com relacionamentos
3. Use o API Design prompt para projetar os endpoints REST. Inclua auth, paginacao e error format
4. Peca ao Claude para gerar a especificacao OpenAPI 3.0 da sua API
5. Rode o Architecture Review no design final e ajuste baseado no feedback

✅ Criterios de Sucesso

☐ Decisao de arquitetura documentada com pros/cons

☐ Schema com 5+ tabelas e indexes otimizados

☐ API com endpoints, auth, paginacao e errors

☐ Especificacao OpenAPI 3.0 gerada

☐ Architecture Review rodado e ajustes aplicados

📋 Resumo do Modulo

✓

Architecture Decision compara opcoes sistematicamente - Pros/cons, complexidade, custo de manutencao, risco. Recomendacao justificada.

✓

API Design cria APIs profissionais - Endpoints, schemas, auth, paginacao, errors, versioning. OpenAPI spec pronta.

✓

Database Schema modela pensando em queries - Access patterns primeiro, indexes otimizados, decisoes de normalizacao explicitas.

✓

System Design projeta sistemas distribuidos - Servicos, caching, filas, failure scenarios, custos estimados. Escala realista.

✓

Migration Planning garante migracoes seguras - Fases incrementais, rollback por fase, verificacao, zero downtime.

✓

Architecture Review avalia sistemas existentes - Mapeamento → Analise → Proposta → Roadmap. Review trimestral recomendado.

Proximo Modulo:

4.7 - Outcome Delegation (Tecnica 2026)

← Modulo Anterior Voltar para Trilha Proximo Modulo →