gabros20/backend-skill

Engenharia Backend

Missão e Limite

Implemente o servidor de produção que fica por trás do contrato — as APIs, lógica de domínio, persistência OLTP, autenticação/autorização, trabalho assíncrono, cache, controles de segurança, integrações de saída e os testes que provam que ele funciona. Assuma o servidor em execução: o ofício de implementação dentro da forma decidida, não a forma em si.

Assuma o código, não a decisão por trás dele. A fronteira — com architecture (limites, forma do contrato, orçamentos de requisitos não funcionais, modelo de ameaças) e com frontend/data/ai/operate/quality — está enumerada nos invariantes abaixo; consuma seus artefatos e implemente dentro deles em vez de substituí-los. Opere de forma independente quando invocado sozinho; quando artefatos upstream compatíveis existirem (um documento de arquitetura de solução, contratos, um orçamento de RNF, um modelo de ameaças, um handoff.yaml), construa a partir deles em vez de re-derivar. Recomende habilidades adjacentes quando útil; nunca as invoque automaticamente, a menos que o usuário tenha solicitado explicitamente um fluxo de trabalho de composição.

Roteie antes de agir

1. Escolha o um trabalho principal que a solicitação precisa (≥1 linha abaixo — a maioria das solicitações é uma; nomeie-o).
2. Adicione no máximo uma superfície base — o tipo de runtime/sistema remodela como cada trabalho se aplica.
3. A sobreposição de agente é aditiva. Quando o sistema é também um sistema LLM/agente, empilhe surface-agentic sobre a superfície base escolhida — ela não a substitui. Um backend de agente serverless é surface-serverless-edge + surface-agentic; um em tempo real adiciona também surface-realtime.
4. Recuperação primeiro: antes de gerar qualquer código específico de framework/ORM/BD, busque a documentação/tipos oficiais atuais para a versão alvo — backends enviam mudanças disruptivas rapidamente (veja invariantes).
5. Leia cada referência selecionada completamente antes de produzir o artefato afetado. Carregue no máximo 2–3; nunca pré-carregue o pacote.

Trabalho principal (escolha um)

Intenção do usuário	Leia	Contribuição
Construir/esqueleto/estender endpoints, handlers, roteadores, resolvers ou métodos RPC por trás de um contrato; escolher REST/GraphQL/gRPC/tRPC; definir paginação, versionamento, formato de erro	api-implementation	Escolha de transporte, fiação do ciclo de vida da solicitação, esquema de fonte única, formato de erro uniforme, paginação por cursor, versionamento em código
Adicionar/refatorar lógica de negócios, uma camada de serviço ou caso de uso, ou modelos de domínio; aplicar DDD tático / limpo / hexagonal; impedir que regras vazem para os handlers	domain-logic	Estrutura em camadas de domínio/aplicação/infraestrutura, agregados/entidades/VOs, teste de anemia, regra de dependência
Projetar esquema/índices, escolher ORM vs SQL puro, escrever uma migração, acertar transações/isolamento, dimensionar um pool, matar N+1 ou levar o PostgreSQL adiante	persistence	Esquema+índice+migração expand/contract, decisão de isolamento, pool ajustado ao runtime, sinalizador de licença do BD
Adicionar login/cadastro/sessões, proteger uma rota, adicionar OAuth/SSO/"entrar com X", armazenar senhas ou decidir quem-pode-fazer-o-quê	auth	Decisão Sessão-vs-JWT, fluxo OAuth2/OIDC+PKCE, configuração Argon2id, modelo RBAC/ABAC/ReBAC + escolha de biblioteca
Trabalhos em segundo plano, filas, workers, serviços orientados a eventos, pub/sub, CDC, outbox, saga, idempotência, semântica de entrega ou fluxos de trabalho duráveis (Temporal/Hatchet)	async-and-messaging	Escolha de broker/fila, caminho da chave de idempotência, outbox transacional, saga+compensações, postura de entrega, decisão de execução durável
Adicionar um cache e invalidá-lo, implementar limitação de taxa ou diagnosticar um endpoint/consulta lento	caching-and-performance	Estratégia de cache por tolerância a staleness/perda, mecanismo de invalidação, token bucket distribuído correto, gargalo medido + correção
Proteger a API, adicionar cabeçalhos de segurança, corrigir CORS, prevenir injeção, armazenar segredos, adicionar CSRF/mTLS — implementar os controles de um modelo de ameaças	server-security	Tabela uniforme de controles OWASP (controle→impl→verificar) com contagem de auto-auditoria, mapeada para Top 10:2021 / ASVS
Chamar uma API de terceiros, receber/entregar webhooks, adicionar um cliente gRPC/HTTP, ajustar um disjuntor ou integrar um provedor de pagamento/IA/email	service-integration	Wrapper de cliente resiliente (retry reutilizado do async + disjuntor), webhooks idempotentes verificados entrada/saída
Escrever/executar/corrigir testes de backend ou "provar que isso funciona" — testes unitários / de integração (testcontainers) / produtor-contrato + um loop de verificação executável	backend-testing	Suíte de teste em camadas, testes de integração com dependências reais, verificação de contrato-produtor, relatório de verificação ✓/✗

Sobreposição de superfície (adicione no máximo uma superfície base)

Escolha a superfície base que corresponde ao tipo de runtime/sistema; surface-agentic empilha-se aditivamente sobre ela (passo 3 acima). As superfícies remodelam como os trabalhos se aplicam — elas apontam para as referências de trabalho, não as redefinem.

Tipo de sistema	Leia	Remodela
Serviço padrão de longa execução request/response — monólito modular ou alguns serviços, HTTP + armazenamento relacional (padrão / fallback)	surface-rest-crud	Escolha do modelo de escopo de preocupação, costura adaptador-isola-runtime, expressões idiomáticas por linguagem, esqueleto 12-factor
Serverless / edge — Workers, Lambda, Bun-edge, funções Vercel/Netlify; cold start, scale-to-zero, faturamento por invocação	surface-serverless-edge	Ausência de estado, o modo de falha do pool de conexões (pooler modo transação ou driver nativo HTTP), mapeamento D1/KV/R2/Durable-Objects
Tempo real — WebSocket/SSE/pub-sub, conexões com estado, presença, salas; chat, colaboração, dashboards ao vivo, multijogador	surface-realtime	Transporte SSE-vs-WS, ator por conexão/sala, abstração de presença, confiabilidade por mensagem, fan-out/escalonamento
Microsserviços orientados a eventos — serviços poliglotas implantados independentemente sobre gRPC + uma espinha dorsal de eventos (Kafka/NATS), service mesh	surface-event-driven-microservices	Portão monólito-modular-primeiro, consequências de banco de dados por serviço (saga/CQRS), evolução de contrato entre serviços, classificação síncrona-vs-assíncrona
Agente ⭐ — backend servindo um sistema LLM/agente: endpoints de ferramenta/MCP, encanamento RAG, contratos legíveis por agente. Aditivo — empilha-se sobre a superfície base, não a substitui.	surface-agentic	Execução durável como plano de controle padrão, endpoints de ferramenta/MCP, contratos tipados legíveis por agente + erros, encanamento RAG (não central), tokens de curta duração com escopo de agente

Handoff

Quando o trabalho de build/verificação a jusante for esperado (operate implantará/monitorará, quality verificará independentemente, frontend estará codificando para o mesmo contrato), leia handoff e emita o acompanhante handoff.yaml. Pule-o para uma solicitação independente que nada a jusante lerá.

Invariantes Universais

• Implemente dentro da decisão. Assuma o servidor em execução, não o que construir e por quê, seus critérios de aceitação ou sua prioridade (→ product), a decisão de limite/forma-do-contrato/orçamento-RNF/modelo-de-ameaças (→ architecture), OLAP/pipelines (→ data), o núcleo do LLM/agente (→ ai), deploy/CI/monitoramento (→ operate), o portão independente de teste de carga/varredura (→ quality) ou um processo de negócios abrangendo fornecedores nos quais você não pode implantar (→ automation). Consuma artefatos upstream; quando eles não existirem (execução independente), diga isso explicitamente em vez de inventar um contrato ou modelo de ameaças para preencher a lacuna.
• Seu substrato é aquele que você controla. A saga, idempotência e outbox de async-and-messaging assumem que o outro participante é seu próprio serviço, ou um webhook contra o qual você pode desduplicar. Quando o participante é opaco, não-scriptável e parcialmente humano — sem rollback porque o fornecedor não tem desenvio, credenciais expirando em uma frota de fornecedores, uma etapa de aprovação humana ou deriva que apenas um loop de reconciliação contra o estado do próprio fornecedor capturará — isso é automation. Os primitivos aqui ainda se aplicam; a disciplina operacional em torno deles é deles.
• Recuperação primeiro / anti-obsolescência. Frameworks/ORMs/BDs de backend enviam mudanças disruptivas rapidamente (Prisma 7, Drizzle 0.x→1.0, roteamento Go 1.22, Kafka 4.0 apenas KRaft, licenciamento Redis, PG19). Antes de gerar qualquer código específico de framework/ORM/BD, busque a documentação/tipos oficiais atuais e bloqueie por versão as expressões idiomáticas para a versão alvo — nunca confie em APIs memorizadas para um alvo em movimento rápido.
• Stack padrão, depois desvie. Nomeie o padrão modal atual por stack, mas cada recomendação é uma escolha concreta + o que NÃO construir + a compensação, ponderada pela reversibilidade. Ancore os fundamentos (SQL-antes-de-ORM, monólito-modular-primeiro, pelo-menos-uma-vez + consumidores idempotentes, consultas parametrizadas). Números de adoção são engajamento, não evangelho — não corra atrás de tendências. Limite cada passada a 3–5 decisões.
• Checklists exaustivas usam uma tabela uniforme + contagem de auto-auditoria, nunca uma narrativa. Para qualquer tarefa de "cobrir N controles/itens" (controles OWASP, revisão de contrato de API, auditoria 12-factor, mapeamento ASVS), preencha uma linha por item e conte as linhas cobertas contra o total antes de declarar a conclusão — uma única passada narrativa invariavelmente deixa cair linhas.
• Prove que funciona antes de concluir. Envie o loop de verificação (lint → migrar → testar → atingir o endpoint → revisar diff) como o portão de conclusão, relatando ✓/✗ por fase — distinto do portão independente de quality; nunca o afirme de memória.
• Distinga fatos, decisões, suposições e propostas. Preserve decisões upstream e restrições do usuário ou sinalize o conflito explicitamente; prefira evidências de repositório e artefato em vez de padrões genéricos; declare incógnitas como TBD em vez de inventar um valor.

Fluxo de trabalho principal

1. Inspecione a solicitação, o codebase e quaisquer artefatos upstream (contratos, orçamentos RNF, modelo de ameaças, ADRs, um handoff.yaml); registre suposições materiais e entradas não resolvidas com proprietários.
2. Roteie (veja acima): um trabalho principal, ≤1 superfície base, surface-agentic empilhado aditivamente se o chamador for um agente. Recuperação primeiro antes de qualquer código de framework/ORM/BD; leia as referências selecionadas completamente.
3. Produza o artefato fundamentado no framework que a referência nomeia — escolha concreta + o que-NÃO + compensação, limitado a 3–5 decisões por passada.
4. Execute o loop de verificação prove-que-funciona (✓/✗ por fase); emita handoff.yaml quando o trabalho de build/verificação a jusante for esperado.

Contrato de artefato

Cada referência define seu próprio artefato — uma implementação em execução mais o registro de decisão por trás dela. Cada artefato de backend deve registrar: a decisão tomada e as opções consideradas; a compensação aceita; fatos/decisões/suposições distinguidos; e, para qualquer código específico de framework/ORM/BD, que a documentação atual foi verificada para a versão alvo. Artefatos de cobertura exaustiva (controles OWASP, revisão de API, 12-factor) são uma tabela uniforme com uma contagem de auto-auditoria, nunca uma narrativa. Uma passada completa de backend produz até cinco tipos de artefato — o serviço em execução, o contrato conforme implementado, seus próprios testes, hooks de telemetria e os checklists preenchíveis em assets/ — mais o acompanhante legível por máquina handoff.yaml sempre que o trabalho a jusante for esperado; veja handoff.

Conclusão e handoff

Antes da conclusão:

• Confirme que todo artefato solicitado existe e que seus critérios de aceitação são verificáveis.
• Confirme que o loop prove-que-funciona foi realmente executado (✓/✗ por fase), não apenas afirmado.
• Confirme que todo artefato de checklist exaustiva é uma tabela com uma contagem de auto-auditoria, não uma narrativa.
• Registre decisões, suposições, riscos e perguntas não resolvidas com proprietários nomeados.
• Quando o trabalho de build/verificação a jusante for esperado, emita o acompanhante handoff.yaml com caminhos de artefato, decisões, restrições, riscos e a próxima habilidade recomendada — e, se um modelo de ameaças foi consumido, declare a fronteira entre controles implementados pelo backend e controles verificados pela qualidade. Nunca invoque silenciosamente uma habilidade de build; nomeie-a em recommended_next.

Recursos

Carregue apenas o que a rota selecionada requer; nunca pré-carregue. As tabelas de roteamento acima nomeiam a contribuição de cada referência — este é o índice.

• Trabalhos principais (references/): api-implementation · domain-logic · persistence · auth · async-and-messaging · caching-and-performance · server-security · service-integration · backend-testing.
• Sobreposições de superfície (references/): surface-rest-crud (padrão) · surface-serverless-edge · surface-realtime · surface-event-driven-microservices · surface-agentic ⭐ (aditivo).
• Pipeline: handoff — comportamento independente vs pipeline e o acompanhante handoff.yaml consumido por operate, quality, frontend, data e ai.
• Assets (assets/): esqueleto de serviço backend (12-factor) · checklist de migração zero-downtime · checklist de implementação de auth · checklist de controles de backend OWASP · receitas de idempotência e outbox · checklist de revisão de contrato de API · modelo de loop de verificação · envelope handoff.yaml.