1) Como o “contexto” é construído (e por que arquitetura importa)

Conceito
Projetos
Leitura do código

A qualidade do resultado depende da forma como você estrutura o repositório e como você posiciona o código no editor.
Pense no fluxo como: delimitação (o que entra) + relevância (o que é priorizado)
+ restrições (o que deve ser respeitado).

• Delimitação por escopo: mantenha arquivos pequenos, módulos coerentes e funções com responsabilidades claras.
  Contexto “aberto demais” tende a gerar variações inúteis.
• Relevância por padrões: use convenções consistentes (nomes, estrutura de pastas, camadas).
  Quando o padrão é estável, a geração fica mais previsível.
• Restrições por contratos: adote tipos (quando aplicável), interfaces, validações e schemas.
  Contratos fecham a “zona cinzenta” e reduzem churn na revisão.

2) Layout do repositório: otimize para navegação e consistência

Arquitetura
Padrões de projeto
Manutenibilidade

Para dominar a “arquitetura” do uso no dia a dia, você precisa tratar o repositório como uma base de conhecimento
para o seu próprio processo. Isso vale para quem gera código e para quem revisa.

• Organize por domínios/camadas: separe entrada (controllers), regras (services) e persistência (repositories).
  Evite misturar IO com lógica de domínio.
• Documente decisões: crie um docs/ com notas de arquitetura, ADRs ou README por módulo.
  Quando o “porquê” está claro, você reduz correções posteriores.
• Centralize utilitários: funções comuns (formatadores, validadores, helpers) devem ficar em um lugar único.
  Isso diminui duplicação e divergência.
• Defina regras de estilo: alinhe lint + formatter (ESLint/Prettier, ruff/black, etc.).
  O resultado final fica mais homogêneo entre autores e ciclos.

3) Escreva prompts como especificações de engenharia

Prompting
Especificação
Critérios de aceitação

Em vez de pedir “faça um código”, trate o pedido como uma tarefa bem definida: objetivo, restrições, entradas/saídas,
limites e critérios de aceitação. Isso encurta a distância entre expectativa e entrega.

• Inclua o “o quê” e o “por quê”: objetivo de negócio + contexto técnico.
• Declare restrições: stack, padrões do projeto, libs permitidas, e o que deve ser evitado.
• Traga insumos reais: trechos de código, assinaturas existentes, ou exemplos de payloads.
• Especifique critérios de aceitação: testes esperados, comportamento em erros, performance mínima.

Objetivo:
- Implementar uma função "parseOrderTotal" que receba um objeto Order (já tipado)
  e retorne o total em centavos (number), arredondando corretamente.

Restrições:
- Usar somente utilitários do projeto (não criar helpers duplicados).
- Respeitar padrão de nomenclatura e estrutura do repositório.
- Não lançar exceções; retornar { ok: false, error } quando o payload estiver inválido.

Entradas:
- order: { currency: string, total: string | number | null, items?: Array<{ price: number, qty: number }> }

Regras:
- Se total for número, converter para centavos.
- Se total for string, parsear removendo separadores (ex: "1.234,56" - pt-BR).
- Se total for null, calcular a partir de items.
- Para currency desconhecida, retornar ok: false.

Critérios de aceitação:
- Cobrir casos: total string válida, total string inválida, total null com items, items vazios, currency desconhecida.
- Adicionar testes unitários e pelo menos 1 teste de integração onde a função é usada.

4) Fluxo de trabalho: do rascunho ao PR com revisão eficiente

Processo
Testes
Qualidade

Para “dominar” de verdade, você precisa encaixar o uso no seu pipeline de qualidade.
A ideia é transformar geração em rascunho útil, e não em entrega final sem validação.

• Trabalhe em camadas: primeiro defina tipos/contratos, depois implemente, por fim cubra com testes.
  Assim você reduz retrabalho quando surgir um desvio na regra de negócio.
• Valide com testes antes do ajuste fino: rode o teste local/CI cedo.
  Muitas correções deixam de existir quando o comportamento é especificado por testes.
• Adote checklist de PR:
  • mensagens de erro com padrão do projeto;
  • tratamento de casos-limite;
  • conformidade com lint/formatter;
  • documentação mínima no ponto necessário;
  • cobertura de testes para cenários críticos.
• Refatore guiado por consistência: após validar o comportamento, alinhe estrutura e nomes para manter o
  repositório coeso.

Dica prática: sempre que o resultado “parecer quase certo”, corrija primeiro o contrato/testes e só depois ajuste o estilo.
Isso evita o ciclo de “muito refino estético” em cima de regras erradas.