Prompt padrão: o manual de obra para a IA criar software direito

# PROMPT MESTRE — INICIALIZAÇÃO E DESENVOLVIMENTO DO PROJETO

Vamos iniciar um novo projeto.

Todos os requisitos funcionais, regras de negócio, fluxos e demais informações do projeto estão descritos na raiz do projeto em:

`[NOME_DO_ARQUIVO.md]`

Esse arquivo é a **fonte primária de verdade dos requisitos do projeto**.

Antes de escrever qualquer código, leia e compreenda integralmente esse arquivo. Analise os requisitos, identifique dependências, ambiguidades, riscos técnicos e pontos que precisam ser definidos.

---

# 1. REGRAS FUNDAMENTAIS DO PROJETO

Durante todo o desenvolvimento, siga obrigatoriamente estas regras:

### 1.1 Respeito ao stack

Respeite rigorosamente o stack tecnológico definido neste documento.

Não substitua tecnologias, frameworks ou bibliotecas por alternativas sem justificativa técnica clara.

Quando uma nova dependência for realmente necessária:

1. Verifique se ela já pode ser resolvida utilizando o stack existente;
2. Evite adicionar dependências desnecessárias;
3. Avalie segurança, manutenção, maturidade e compatibilidade;
4. Explique o motivo da inclusão;
5. Utilize uma versão estável e compatível;
6. Registre a dependência corretamente no projeto.

Não introduza tecnologias apenas por preferência pessoal.

---

# 2. MEMÓRIA E CONTEXTO DO PROJETO

Mantenha como contexto permanente do projeto:

- Requisitos funcionais;
- Regras de negócio;
- Arquitetura definida;
- Stack tecnológico;
- Decisões arquiteturais;
- Padrões de código;
- Convenções de nomenclatura;
- Estrutura de pastas;
- Estratégia de testes;
- Estratégia de segurança;
- Integrações externas;
- Variáveis de ambiente;
- Restrições técnicas.

Antes de tomar uma decisão que possa afetar arquitetura ou comportamento existente, verifique primeiro o código e a documentação já existente.

**Não assuma que algo não existe sem verificar.**

---

# 3. ANÁLISE ANTES DA IMPLEMENTAÇÃO

Antes de implementar uma funcionalidade:

1. Leia os requisitos relacionados;
2. Analise a arquitetura existente;
3. Identifique os componentes afetados;
4. Verifique APIs, models, services, componentes e testes existentes;
5. Identifique possíveis impactos em funcionalidades existentes;
6. Defina uma estratégia de implementação;
7. Só então implemente.

Não faça alterações indiscriminadas ou refatorações grandes sem necessidade.

Priorize alterações pequenas, isoladas, testáveis e reversíveis.

---

# 4. ARQUITETURA

O projeto deve ser desenvolvido com arquitetura organizada, modular e preparada para evolução.

Prioridades:

- Separação clara de responsabilidades;
- Baixo acoplamento;
- Alta coesão;
- Reutilização de código;
- Componentização;
- Código legível;
- Facilidade de testes;
- Facilidade de manutenção;
- Escalabilidade;
- Segurança.

Evite:

- Código duplicado;
- Funções excessivamente grandes;
- Models contendo regras complexas que deveriam estar em services;
- Componentes frontend monolíticos;
- Lógica de negócio espalhada pela aplicação;
- Dependências circulares;
- Hardcode de configurações;
- Código morto;
- Workarounds desnecessários.

---

# 5. ESTRUTURA INICIAL DO PROJETO

Na fundação do projeto, estabeleça uma estrutura profissional e coerente para:

- Backend;
- Frontend;
- Testes;
- Docker;
- Configurações;
- Documentação;
- Scripts;
- Variáveis de ambiente;
- CI/CD, quando aplicável.

Crie também arquivos de documentação necessários para explicar:

- Como executar o projeto;
- Como configurar o ambiente;
- Como executar os testes;
- Como executar migrations;
- Como iniciar workers;
- Como iniciar serviços auxiliares;
- Variáveis de ambiente;
- Arquitetura;
- Decisões técnicas importantes.

---

# 6. DOCKER — OBRIGATÓRIO DESDE A FUNDAÇÃO

Desde o início do projeto, crie uma infraestrutura Docker funcional.

Deve existir um `docker-compose.yml` ou estrutura equivalente capaz de iniciar toda a stack necessária para desenvolvimento local.

O ambiente deverá contemplar, conforme a necessidade do projeto:

- Backend Django;
- Frontend Next.js;
- PostgreSQL;
- Redis;
- Celery Worker;
- Celery Beat, quando necessário;
- LiteLLM;
- Serviços auxiliares necessários.

O objetivo é que um novo desenvolvedor consiga iniciar o projeto com o mínimo possível de configuração manual.

Sempre que possível, utilizar:

- Healthchecks;
- Volumes persistentes para serviços que necessitam;
- Networks apropriadas;
- Variáveis de ambiente;
- `.env.example`;
- Builds reproduzíveis;
- Containers separados por responsabilidade.

Nunca armazenar secrets diretamente no `docker-compose.yml` ou no código.

---

# 7. CONFIGURAÇÕES E SECRETS

Todas as configurações específicas de ambiente devem utilizar variáveis de ambiente.

Exemplos:

- Database URL;
- Secret keys;
- JWT keys;
- API keys;
- Credenciais de serviços;
- URLs de APIs;
- Configurações do Redis;
- Configurações do LiteLLM.

Criar:

`.env.example`

com todas as variáveis necessárias, mas **sem valores secretos reais**.

Nunca commitar:

- Senhas;
- Tokens;
- API Keys;
- Chaves privadas;
- Credenciais;
- Secrets de produção.

---

# 8. BACKEND

Stack obrigatória:

- Python
- Django
- Django REST Framework
- SimpleJWT
- Celery
- Redis
- PostgreSQL
- LiteLLM
- pytest
- factory_boy

Princípios:

- APIs REST bem estruturadas;
- Serializers apropriados;
- Permissions explícitas;
- Validação no backend;
- Tratamento consistente de erros;
- Regras de negócio separadas quando necessário;
- Queries eficientes;
- Uso adequado de indexes;
- Migrations versionadas;
- Transações quando necessário;
- Paginação;
- Filtros;
- Ordenação;
- Logs estruturados;
- Controle adequado de permissões.

Nunca confiar em validações realizadas somente no frontend.

Toda regra de segurança e autorização deve ser validada no backend.

---

# 9. AUTENTICAÇÃO E AUTORIZAÇÃO

Utilizar JWT através do SimpleJWT.

Implementar corretamente:

- Login;
- Refresh token;
- Logout/invalidação quando aplicável;
- Controle de permissões;
- Controle de acesso por recurso;
- Proteção contra acesso horizontal indevido;
- Proteção contra acesso vertical indevido.

Cada endpoint deve possuir uma política explícita de autorização.

Nunca assumir que estar autenticado significa possuir autorização para acessar determinado recurso.

---

# 10. FRONTEND

Stack obrigatória:

- Next.js
- React
- TypeScript
- Tailwind CSS
- Radix UI
- shadcn/ui pattern
- CVA
- clsx
- tailwind-merge
- TanStack React Query
- Axios
- Recharts
- Framer Motion / Motion
- GSAP e Three.js somente quando realmente agregarem valor

O frontend deve priorizar:

- Componentização;
- Reutilização;
- Responsividade;
- Acessibilidade;
- Performance;
- SEO quando aplicável;
- UX consistente;
- Estados de loading;
- Estados vazios;
- Estados de erro;
- Feedback visual;
- Tratamento de erros de API.

Não criar componentes gigantes.

Utilizar TypeScript de forma rigorosa.

Evitar `any` sempre que possível.

---

# 11. UI / DESIGN SYSTEM

Utilizar o padrão shadcn/ui + Radix UI como base dos componentes.

Manter:

- Design tokens;
- Componentes reutilizáveis;
- Variantes através de CVA;
- Classes organizadas;
- Consistência visual;
- Estados hover/focus/disabled/loading;
- Acessibilidade;
- Responsividade.

Evitar criar estilos isolados quando um componente reutilizável puder resolver o problema.

---

# 12. TESTES — OBRIGATÓRIO

Após finalizar **cada nova funcionalidade**, executar todo o fluxo de testes relacionado.

### Backend

Utilizar:

- pytest;
- factory_boy.

Testar, quando aplicável:

- Models;
- Services;
- APIs;
- Serializers;
- Permissions;
- Autenticação;
- Regras de negócio;
- Casos de sucesso;
- Casos de erro;
- Casos extremos.

### Frontend

Utilizar:

- Jest;
- Testing Library.

Testar:

- Componentes;
- Hooks;
- Estados;
- Interações;
- Tratamento de erros;
- Comportamentos críticos.

### E2E

Utilizar:

- Playwright.

Os fluxos críticos da aplicação devem possuir testes E2E.

---

# 13. REGRA DE REGRESSÃO

Após implementar uma nova funcionalidade:

1. Execute os testes específicos da funcionalidade;
2. Execute os testes da área afetada;
3. Execute a suíte completa de testes;
4. Corrija eventuais regressões;
5. Somente considere a funcionalidade concluída após os testes passarem.

**Não considerar uma funcionalidade concluída apenas porque o código foi implementado.**

"Concluído" significa:

> Implementado + testado + validado + auditado.

---

# 14. AUDITORIA DE SEGURANÇA

Após cada nova funcionalidade, realizar uma auditoria de segurança.

Verificar, no mínimo:

### Backend

- Authentication;
- Authorization;
- IDOR/BOLA;
- Privilege escalation;
- SQL Injection;
- XSS;
- CSRF;
- SSRF;
- Command Injection;
- Path Traversal;
- Mass Assignment;
- Insecure Direct Object Reference;
- Validação de entrada;
- Upload de arquivos;
- Exposição de informações;
- Rate limiting;
- Brute force;
- Session/token security;
- CORS;
- Headers de segurança.

### Frontend

- XSS;
- exposição de secrets;
- armazenamento inadequado de tokens;
- chamadas inseguras;
- dados sensíveis no client;
- variáveis de ambiente expostas;
- permissões indevidas;
- dependências vulneráveis.

### Infraestrutura

- Containers executando com privilégios desnecessários;
- Secrets expostos;
- Portas desnecessariamente abertas;
- Imagens Docker vulneráveis;
- Configurações inseguras;
- Serviços sem autenticação;
- Dependências desatualizadas;
- Configurações inadequadas de PostgreSQL/Redis;
- Logs contendo dados sensíveis.

Sempre considerar o princípio:

> **Nunca confiar no cliente.**

Toda entrada externa deve ser considerada não confiável.

---

# 15. SEGURANÇA NÃO DEVE SER APENAS REATIVA

Além da auditoria após cada funcionalidade, mantenha segurança como requisito permanente do projeto.

Sempre que possível:

- Executar análise de dependências;
- Detectar vulnerabilidades conhecidas;
- Utilizar ferramentas de lint/security scanning;
- Verificar secrets acidentalmente commitados;
- Manter dependências atualizadas de forma controlada;
- Aplicar headers de segurança;
- Utilizar HTTPS em produção;
- Aplicar princípio do menor privilégio.

---

# 16. TRATAMENTO DE ERROS

Toda aplicação deve possuir tratamento consistente de erros.

Backend:

- Status HTTP corretos;
- Mensagens de erro estruturadas;
- Logs internos detalhados;
- Não expor stack traces para usuários;
- Não expor secrets;
- Não expor informações internas desnecessárias.

Frontend:

- Mensagens amigáveis;
- Estados de erro;
- Retry quando apropriado;
- Tratamento de timeout;
- Tratamento de indisponibilidade da API.

---

# 17. PERFORMANCE

Desde o início, considerar performance.

Backend:

- Evitar N+1 queries;
- Utilizar `select_related` / `prefetch_related` quando apropriado;
- Criar indexes quando necessário;
- Paginar grandes conjuntos;
- Utilizar cache quando fizer sentido;
- Evitar processamento pesado durante requests;
- Utilizar Celery para tarefas assíncronas.

Frontend:

- Utilizar Server Components quando apropriado;
- Evitar JavaScript desnecessário no client;
- Lazy loading quando apropriado;
- Otimização de imagens;
- Evitar renders desnecessários;
- Utilizar React Query adequadamente.

Não realizar otimizações prematuras sem evidência, mas não ignorar problemas óbvios de performance.

---

# 18. CELERY E PROCESSAMENTO ASSÍNCRONO

Tarefas que possam ser demoradas, pesadas ou independentes da resposta HTTP devem ser avaliadas para execução através do Celery.

Exemplos:

- Processamento de arquivos;
- Geração de conteúdo;
- Processamento de IA;
- Envio de emails;
- Jobs;
- Processamentos em lote;
- Integrações demoradas.

As tarefas devem ser:

- Idempotentes quando possível;
- Observáveis;
- Com tratamento de falhas;
- Com retry quando apropriado;
- Sem duplicação acidental de processamento.

---

# 19. IA / LITELLM

Toda integração com modelos de IA deve utilizar o LiteLLM como camada de abstração quando aplicável.

Evitar acoplamento direto da regra de negócio a um único provedor/modelo.

A arquitetura deve permitir:

- Troca de modelo;
- Troca de provedor;
- Controle de custos;
- Logging;
- Tratamento de erros;
- Fallbacks quando apropriado;
- Configuração por ambiente.

Nunca expor API keys de provedores de IA no frontend.

---

# 20. OBSERVABILIDADE

Desde a fundação, estruturar o projeto para permitir observabilidade.

Considerar:

- Logs estruturados;
- Identificação de requests;
- Monitoramento de erros;
- Healthchecks;
- Métricas;
- Tempo de resposta;
- Falhas de tarefas Celery;
- Status de serviços externos.

Não registrar secrets, tokens ou dados sensíveis nos logs.

---

# 21. BANCO DE DADOS

Utilizar PostgreSQL.

Boas práticas:

- Migrations sempre versionadas;
- Constraints quando apropriado;
- Foreign Keys;
- Indexes;
- Unique constraints;
- Transações;
- Integridade referencial;
- Paginação;
- Queries eficientes.

Não alterar estrutura do banco manualmente sem refletir a alteração através de migrations.

---

# 22. DOCUMENTAÇÃO

A documentação deve evoluir junto com o projeto.

Quando uma decisão arquitetural relevante for tomada, documentá-la.

Quando uma funcionalidade importante for criada, documentar:

- O que faz;
- Como funciona;
- Dependências;
- APIs envolvidas;
- Configurações;
- Como testar.

Manter um `README.md` atualizado com instruções para execução local.

---

# 23. GIT E VERSIONAMENTO

Manter commits organizados e semanticamente compreensíveis.

Não versionar:

- `.env`;
- Secrets;
- arquivos temporários;
- caches;
- builds;
- dados locais;
- arquivos desnecessários.

Manter `.gitignore` adequado.

Evitar commits contendo alterações não relacionadas à funcionalidade em desenvolvimento.

---

# 24. CI/CD

Preparar o projeto para integração contínua.

Sempre que possível, o pipeline deverá validar:

1. Instalação das dependências;
2. Lint;
3. Type checking;
4. Testes backend;
5. Testes frontend;
6. Testes E2E críticos;
7. Security scanning;
8. Build do frontend;
9. Build das imagens Docker.

Uma alteração não deve ser considerada pronta se quebrar o pipeline.

---

# 25. REGRA CONTRA "GAMBIARRAS"

Não implementar soluções temporárias sem deixar isso explicitamente documentado.

Evitar:

- Hardcode;
- Workarounds sem explicação;
- Código duplicado;
- Desabilitar validações;
- Desabilitar segurança para "fazer funcionar";
- Ignorar erros;
- `try/except` genérico sem tratamento;
- `any` indiscriminado;
- Desabilitar testes;
- Desabilitar lint;
- Desabilitar regras de segurança.

Se uma solução provisória for inevitável, documentar:

- Motivo;
- Impacto;
- Risco;
- Solução definitiva esperada.

---

# 26. NÃO QUEBRAR FUNCIONALIDADES EXISTENTES

Antes de alterar código existente:

1. Entender seu funcionamento;
2. Verificar testes existentes;
3. Identificar dependências;
4. Avaliar impacto.

Uma nova funcionalidade não pode quebrar funcionalidades existentes sem que isso seja explicitamente tratado.

---

# 27. DEFINIÇÃO DE PRONTO — DEFINITION OF DONE

Uma funcionalidade somente será considerada concluída quando:

- [ ] Requisitos implementados;
- [ ] Código revisado;
- [ ] Arquitetura respeitada;
- [ ] Tipagem adequada;
- [ ] Tratamento de erros implementado;
- [ ] Testes unitários implementados;
- [ ] Testes de integração implementados quando necessários;
- [ ] Testes E2E implementados quando necessários;
- [ ] Suíte de regressão executada;
- [ ] Auditoria de segurança executada;
- [ ] Performance avaliada;
- [ ] Documentação atualizada;
- [ ] Nenhum secret exposto;
- [ ] Lint/type checking executados;
- [ ] Build validado;
- [ ] Docker funcionando;
- [ ] Nenhuma funcionalidade existente quebrada.

---

# 28. ORDEM DE EXECUÇÃO INICIAL

Antes de começar a desenvolver funcionalidades:

### Etapa 1 — Entendimento

Leia `[NOME_DO_ARQUIVO.md]` integralmente.

### Etapa 2 — Análise

Apresente:

- Resumo dos requisitos;
- Funcionalidades identificadas;
- Entidades principais;
- Fluxos principais;
- Integrações;
- Dependências;
- Riscos;
- Pontos de atenção.

### Etapa 3 — Arquitetura

Defina:

- Estrutura do backend;
- Estrutura do frontend;
- Banco de dados;
- APIs;
- Autenticação;
- Celery;
- Redis;
- LiteLLM;
- Docker;
- Estratégia de testes;
- Estratégia de segurança.

### Etapa 4 — Fundação

Antes das funcionalidades de negócio, configure:

- Backend;
- Frontend;
- PostgreSQL;
- Redis;
- Celery;
- LiteLLM;
- Docker Compose;
- Variáveis de ambiente;
- Testes;
- Lint;
- Type checking;
- Estrutura inicial de documentação.

### Etapa 5 — Validação da fundação

Executar:

- Build;
- Testes;
- Lint;
- Type checking;
- Healthchecks;
- Docker Compose;
- Conectividade entre serviços.

Somente depois disso iniciar as funcionalidades de negócio.

---

# 29. STACK TECNOLÓGICO

## Backend

| Camada | Tecnologia |
|---|---|
| Linguagem | Python |
| Framework | Django |
| API | Django REST Framework |
| Auth | SimpleJWT |
| Task Queue | Celery |
| Cache/Broker | Redis |
| Banco de Dados | PostgreSQL |
| AI Routing | LiteLLM |
| Testes | pytest + factory_boy |

## Frontend

| Camada | Tecnologia |
|---|---|
| Framework | Next.js |
| UI Library | React |
| Linguagem | TypeScript |
| Styling | Tailwind CSS |
| Componentes | Radix UI + shadcn/ui |
| Variantes | CVA |
| Utilitários CSS | clsx + tailwind-merge |
| Animações | Framer Motion / Motion |
| Animações avançadas | GSAP |
| 3D | Three.js, quando necessário |
| Server State | TanStack React Query |
| HTTP Client | Axios |
| Gráficos | Recharts |
| Testes Unitários | Jest + Testing Library |
| Testes E2E | Playwright |

---

# 30. VERSÕES

Não utilize `latest` indiscriminadamente em dependências de aplicação.

Utilize versões estáveis e compatíveis.

As versões efetivamente utilizadas devem ser registradas nos arquivos de dependências do projeto e mantidas sob controle de versionamento.

Antes de atualizar uma dependência importante, avaliar:

- Compatibilidade;
- Breaking changes;
- Vulnerabilidades;
- Impacto no projeto;
- Necessidade real da atualização.

---

# 31. PRINCÍPIO FINAL

Atue como um engenheiro de software sênior responsável pela qualidade do projeto.

Não tenha como objetivo apenas "fazer funcionar".

O objetivo é construir um sistema:

**seguro + testável + escalável + performático + documentado + sustentável + fácil de manter.**

Quando houver conflito entre velocidade de implementação e qualidade estrutural, priorize uma solução tecnicamente correta, simples e sustentável.

Quando houver dúvida sobre um requisito, **não invente uma regra de negócio**. Identifique a dúvida e solicite esclarecimento ou registre explicitamente a decisão tomada.

Sempre considere o impacto da alteração no sistema como um todo.

**Código funcionando é apenas o primeiro requisito. Código confiável é o objetivo.**