Stack registra as decisões técnicas oficiais do projeto — linguagens, frameworks, banco de dados, infraestrutura, testes, observabilidade e qualidade — com justificativas e trade-offs documentados.
Fase: 1 — Definição
Pré-requisito: Docs/project.md aprovado
Template: Templates/Full/stack.md ou Templates/Quick/stack.md
Artefato oficial: Docs/stack.md
Próximos artefatos: Docs/entities.md · Docs/architecture.md · Docs/structure.md
Quando criar ou revisar
- Após aprovação do
Docs/project.md - Mudança de linguagem, framework ou banco de dados
- Descoberta de restrição técnica não mapeada
- Mudança de plataforma ou ambiente de hospedagem
Full vs Quick
| Situação | Template |
|---|---|
| Projeto novo com múltiplas camadas, integrações e ambientes | Templates/Full/stack.md |
| Feature com stack já definida — apenas registrar adições | Templates/Quick/stack.md |
| Ambiguidade surgiu durante o Quick | Migrar para Full na mesma task |
Estrutura — Stack Full
O template Full tem 13 seções, com a seção 5 (Stack Oficial) subdividida em 10 blocos por camada.
1. Identificação
Nome do projeto:
Versão do documento:
Status: [rascunho | revisando | aprovado]
Responsável pela definição técnica:
Data de criação:
Última atualização:
Documento base: Docs/project.md2. Objetivo do Documento
Define o que Docs/stack.md cobre e o que não cobre:
Cobre: linguagens, frameworks, banco, bibliotecas, infraestrutura, padrões técnicos, critérios de escolha.
Não cobre: modelagem de entidades, arquitetura de módulos, endpoints de API, tasks, plano de execução.
3. Contexto Técnico do Projeto
Resumo técnico: [tipo de sistema sendo construído]
Natureza: [web app | backend api | admin | híbrido | SaaS | microserviço | automação]
Tipo de operação: [baixa/média/alta escala | interno | público | tempo real | transacional]
Plataformas-alvo: [web | mobile | api | admin | worker | cli]
Contexto que influencia a stack:
- [restrição de prazo]
- [experiência do time]
- [legado existente]4. Princípios de Escolha da Stack
O que guia as decisões:
- [ex.: simplicidade operacional]
- [ex.: rapidez de desenvolvimento]
- [ex.: baixo custo inicial]
- [ex.: facilidade de manutenção]
- [ex.: escalabilidade progressiva]
O que será evitado:
- complexidade desnecessária
- dependência de serviços difíceis de operar
- stack desalinhada com o time
- ferramentas imaturas
- overengineering5. Stack Oficial — por camada
5.1 Linguagens
Principal: [ex.: TypeScript]
Secundárias: [ex.: SQL, Bash]
Justificativa:5.2 Frontend
Framework principal: [ex.: Next.js]
Bibliotecas:
- [ex.: TanStack Query]
- [ex.: Zod]
- [ex.: React Hook Form]
Estratégia de UI: [SSR | CSR | híbrido | design system próprio]
Justificativa:5.3 Backend
Framework principal: [ex.: NestJS | Fastify | Express]
Responsabilidades:
- autenticação
- regras de negócio
- integrações
- persistência
- fila (quando aplicável)
- arquivos (quando aplicável)
- notificações (quando aplicável)
Justificativa:5.4 Banco de Dados
Principal: [ex.: PostgreSQL]
Auxiliares: [ex.: Redis, Elastic — quando aplicável]
ORM / Query Builder: [ex.: Prisma | Drizzle | Knex | SQL puro]
Justificativa:5.5 Infraestrutura e Hospedagem
Ambiente principal: [ex.: VPS | Docker | Vercel | Railway | AWS | GCP]
Serviços previstos:
- app
- banco
- cache (quando aplicável)
- fila (quando aplicável)
- storage (quando aplicável)
- cdn (quando aplicável)
- proxy / load balancer
- monitoramento
Justificativa:5.6 Autenticação e Autorização
Estratégia: [JWT | sessão | OAuth | auth provider | RBAC | ACL]
Justificativa:5.7 Comunicação e API
Padrão principal: [REST | GraphQL | RPC | WebSocket | eventos]
Formato de contrato: [OpenAPI | contract-first | code-first | híbrido]
Justificativa:5.8 Testes
Ferramentas:
- [unitário: ex.: Vitest | Jest]
- [e2e: ex.: Playwright | Cypress]
- [API: ex.: Supertest]
Estratégia: [unitário | integração | contrato | e2e]
Justificativa:Dica
Testes de integração usam Testcontainers por padrão (ver Quality/realistic-tests.md). Defina aqui qual ferramenta — não deixe para descobrir na task.
5.9 Observabilidade e Logs
Estratégia:
- logs estruturados
- monitoramento
- alertas
- health checks
- rastreamento (quando aplicável)
Ferramentas previstas: [preencher]
Justificativa:5.10 Dev Experience e Qualidade
Ferramentas:
- [ESLint]
- [Prettier]
- [TypeScript strict]
- [Husky]
- [lint-staged]
- [commitlint]
- [turbo / pnpm workspace — quando houver monorepo]
Justificativa:6. Decisões Técnicas Estruturais
Padrões adotados:
- tipagem forte
- validação de entrada
- separação entre domínio e infraestrutura
- contratos centralizados
- tratamento padronizado de erro
- logs estruturados
- configuração por ambiente
Convenções obrigatórias:
- [convenção 1]
- [convenção 2]7. Alternativas Consideradas
Para cada alternativa descartada:
Opção avaliada:
Vantagens percebidas:
Desvantagens percebidas:
Motivo de não adoção:8. Restrições Técnicas
Restrições que impactaram a stack:
- [restrição 1]
Limitações assumidas conscientemente:
- [limitação 1]
Riscos técnicos da stack escolhida:
- [risco 1]
Mitigações iniciais:
- [mitigação 1]9. Dependências Principais
Críticas: [dependências com maior risco de falha]
Serviços externos previstos: [preencher]
Dependências com maior risco operacional: [preencher]10. Estratégia Inicial de Ambientes
Ambientes previstos: [local | dev | staging | prod]
Diferenças relevantes entre ambientes:
Diretriz de configuração por ambiente:11. Diretrizes para os Próximos Documentos
Orientações objetivas de como esta stack impacta cada artefato seguinte:
Docs/architecture.md — quais decisões de stack impactam a arquitetura
Docs/entities.md — restrições sobre persistência e modelagem
Docs/contract.yaml — padrões técnicos que devem ser refletidos no contrato
Docs/structure.md — organização de pastas e camadas
Docs/deploy.md — restrições e necessidades operacionais da stack
Docs/plan.md — impacto da stack na ordem de execução e fases
Docs/tasks.md — áreas técnicas que devem virar tasks logo no início12. Síntese Operacional para Dev e AI
Stack oficial:
Frontend: [preencher]
Backend: [preencher]
Banco: [preencher]
Infraestrutura: [preencher]
Testes: [preencher]
Por que essa stack:
- [motivo 1]
- [motivo 2]
O que deve ser respeitado na implementação:
- [regra 1]
- [regra 2]
O que deve ser evitado:
- [erro a evitar]
O que ainda pode mudar:
- [ponto em aberto]13. Aprovação
Status: [pendente | aprovado | revisando]
Aprovado por:
Data de aprovação:
Observações finais:Estrutura — Stack Quick
Para projetos com stack já conhecida ou contexto reduzido:
## Resumo técnico
[direção técnica do projeto em poucas linhas]
## Princípios de escolha
- [simplicidade]
- [velocidade]
- [baixo custo]
## Linguagens
- [principal]
- [auxiliares]
## Frontend
Base: [preencher]
Bibliotecas principais:
- [lib 1]
## Backend
Base: [preencher]
Responsabilidades:
- [item 1]
## Banco de dados
Principal: [preencher]
Apoio: [preencher]
## Infraestrutura
- [hospedagem]
- [deploy]
- [storage quando aplicável]
## API / Comunicação
- [REST | GraphQL | WebSocket]
- [OpenAPI | outro]
## Testes
- [unitário: ferramenta]
- [e2e: ferramenta]
## Qualidade e DX
- [lint]
- [tipagem]
- [git hooks]
## Restrições técnicas
- [restrição]
## Alternativas descartadas
- [alternativa + motivo resumido]
## Riscos principais
- [risco]
## Direção para os próximos documentos
Docs/architecture.md: [orientação]
Docs/entities.md: [orientação]
Docs/deploy.md: [orientação]
## Síntese para Dev e AI
Stack escolhida: [resumo]
Por que ela foi escolhida: [motivo]
O que deve ser respeitado: [regra]
O que ainda está em aberto: [ponto]Prompt para gerar com agente
Atue como SystemAgent.
Objetivo: criar Docs/stack.md com base em Docs/project.md
Carregue contexto base:
- GUIDE.md
- Skills/contracts.md
- Templates/Full/stack.md
- Docs/project.md
Preencha as 13 seções do template Full.
Preencha cada bloco da seção 5 com as decisões concretas e justificativas.
Seção 7 (Alternativas) deve registrar o que foi descartado e por quê.
Seção 11 (Diretrizes para próximos documentos) deve ter orientação por artefato.
Seção 12 (Síntese para Dev e AI) em linguagem direta.
Marque [indefinido] onde houver decisão ainda pendente.Definição de pronto
O stack está pronto quando:
- Todas as camadas estão cobertas com tecnologia, justificativa e nível de risco
- Seção 3 indica a natureza e a operação esperada do sistema
- Seção 7 registra pelo menos as principais alternativas descartadas
- Seção 11 tem orientações para cada artefato seguinte que depende de decisões técnicas
- Seção 12 está preenchida com síntese objetiva para Dev e AI
- Aprovação registrada na seção 13
Atenção
Listar tecnologia sem justificar a escolha é o erro mais custoso da stack. Quem implementa sem entender o "por quê" toma decisões inconsistentes durante a execução. A justificativa não é documentação decorativa — é contexto operacional.
Erros comuns
| Erro | Correção |
|---|---|
| Listar tecnologia sem justificar | Cada camada tem campo Justificativa: — não deixar em branco |
| Misturar decisão atual com desejo futuro | Marcar explicitamente o que é atual vs. o que é aspiracional |
| Ignorar impacto operacional | Seção 5.5 e 5.9 existem para mapear isso antes da implementação |
| Não registrar alternativas descartadas | Seção 7 evita que a mesma discussão seja reaberta no futuro |
| Seção 11 em branco | Cada artefato seguinte perde a orientação técnica do projeto |
Documentos que nascem da Stack
Docs/stack.md (aprovado)
↓
Docs/entities.md — modelagem orientada pelo banco e padrões definidos
Docs/architecture.md — estrutura técnica guiada pelas escolhas de stack
Docs/structure.md — árvore de diretórios derivada do stack e da arquitetura
Docs/contract.yaml — contrato de API seguindo os padrões de comunicação definidos
Docs/deploy.md — pipeline alinhado com infraestrutura e ambientes escolhidos