Viniciustda/OiTenta / .agents/skills/backend-provider-implementation
backend-provider-implementation
VerifiedImplementa no backend NestJS os providers técnicos definidos nos módulos de negócio, criando classes concretas simples, integrando dependências externas quando necessário e registrando essas implementações para uso pelos controllers e casos de uso.
Backend Provider Implementation
Use esta skill quando o pedido for implementar, no backend NestJS, uma interface de provider definida em modules/<modulo>/src/**/provider/*.provider.ts.
O foco desta skill e criar uma classe concreta simples, direta e facil de manter no backend, registrar essa classe no modulo Nest correspondente e permitir injecao direta da propria classe concreta no backend, sem inventar tokens, symbols, wrappers ou camadas extras desnecessarias.
Objetivo
- criar a implementacao concreta de um provider tecnico definido no dominio
- manter a interface original do dominio intacta
- integrar a classe concreta ao modulo Nest correspondente
- permitir uso por injecao direta da classe concreta no backend
- instalar dependencias externas quando a implementacao realmente precisar
- evitar arquitetura excessiva para resolver um provider tecnico simples
Entradas obrigatorias
Esta skill so pode prosseguir quando o provider alvo estiver claramente identificado por um dos modos abaixo:
- path explicito do arquivo da interface, como
modules/auth/src/user/provider/crypto.provider.ts - nome inequivoco da interface, como
CryptoProvider, apenas quando houver um unico alvo claro no projeto
Informacoes adicionais obrigatorias apenas quando nao puderem ser inferidas com seguranca:
- nome do modulo, quando o path nao bastar para inferir
modules/<modulo> - tipo do provider ou intencao da implementacao, quando isso for necessario para escolher biblioteca, estrategia ou naming
Entradas opcionais
- biblioteca preferida para a implementacao
- restricoes como:
- evitar dependencias extras
- reutilizar biblioteca ja instalada
- usar abordagem sincrona ou assincrona
- compatibilidade com API externa especifica
Trava obrigatoria
- Esta skill so pode executar quando a interface de provider alvo estiver claramente identificada.
- Se houver ambiguidade sobre qual interface implementar, parar e pedir ao usuario o provider exato.
- Nao modificar, reescrever ou expandir a interface original do dominio.
- Tratar qualquer interface em
modules/<modulo>/src/**como contrato imutavel. - Se o contrato nao der informacao suficiente para escolher uma estrategia segura, pedir esclarecimento em vez de inventar comportamento arriscado.
Leituras obrigatorias
Antes de editar qualquer arquivo, leia obrigatoriamente:
- a interface alvo dentro de
modules/<modulo>/src/**/provider/*.provider.ts - os tipos relacionados exigidos por essa interface
modules/auth/src/user/provider/crypto.provider.tsapps/backend/src/modules/auth/bcrypt.crypto.tsapps/backend/src/modules/auth/auth.module.tsapps/backend/src/modules/<modulo>/<modulo>.module.ts- o controller ou ponto de uso no backend, quando isso ajudar a entender como a implementacao sera consumida
Depois disso, leia tambem os materiais internos desta skill:
references/mandatory-readings.mdreferences/provider-implementation-checklist.mdreferences/few-shots/bcrypt-crypto.provider.example.tsreferences/few-shots/auth-module.provider-registration.example.tsreferences/few-shots/uuid.provider.example.ts
Se alguma leitura obrigatoria falhar, pare e relate o bloqueio com clareza.
Escopo
- ler a interface alvo e os tipos relacionados
- inferir o modulo pelo path real em
modules/<modulo>/... - criar a implementacao concreta em
apps/backend/src/modules/<modulo>/ - atualizar
apps/backend/src/modules/<modulo>/<modulo>.module.ts - instalar dependencias externas quando necessario
- ajustar consumidores do backend apenas no minimo necessario para permitir injecao direta da classe concreta
Fora de escopo
- modificar o contrato do provider no dominio
- criar tokens simbolicos por padrao
- criar adapters, wrappers, factories ou camadas extras sem ganho pratico
- refatorar o dominio so para acomodar a implementacao do backend
- espalhar abstracoes novas quando a classe concreta basta
Convencoes obrigatorias
- Criar a implementacao por padrao na raiz de
apps/backend/src/modules/<modulo>/. - So criar subpastas se houver uma convencao local forte ou pedido explicito do usuario.
- O nome do arquivo deve refletir a responsabilidade tecnica do provider.
- O nome da classe deve ser explicito e orientado a implementacao concreta.
- Exemplo:
BcryptCryptoProvider
- Exemplo:
- A implementacao deve cumprir exatamente o contrato da interface original.
- Nao adicionar metodos publicos extras fora do contrato, salvo helpers privados estritamente necessarios.
- Preferir
@Injectable()e injecao direta da classe concreta nos controllers ou servicos Nest. - O backend pode receber a classe concreta e repassa-la aos casos de uso que dependem da interface do dominio.
Workflow deterministico
- Validar a entrada.
- Confirmar que existe exatamente uma interface alvo.
- Confirmar que o arquivo pertence a
modules/<modulo>/src/. - Se houver ambiguidade, interromper.
- Ler o contrato e o contexto minimo.
- Abrir a interface alvo.
- Ler tipos, DTOs, enums e retornos usados pelo contrato.
- Ler o modulo backend correspondente.
- Ler o ponto de uso no backend quando isso ajudar a entender como a classe sera injetada.
- Ler o exemplo real do projeto.
- Usar
CryptoProvider+BcryptCryptoProvider+AuthModulecomo referencia base.
- Usar
- Inferir destino e naming.
- Inferir
<modulo>pelo path real. - Criar o arquivo na raiz de
apps/backend/src/modules/<modulo>/por padrao. - Escolher nome de classe concreto e previsivel.
- Inferir
- Escolher a estrategia de implementacao.
- Reutilizar bibliotecas ja instaladas quando cobrirem o contrato.
- Se mais de uma biblioteca for razoavel e o usuario nao tiver preferencia, escolher a opcao mais simples e estavel.
- Se a escolha ainda for arriscada, parar e pedir confirmacao.
- Implementar a classe concreta.
- Criar uma classe Nest simples.
- Implementar exatamente os metodos da interface.
- Manter a logica tecnica concentrada no proprio arquivo.
- Usar helpers privados apenas quando isso melhorar clareza ou reduzir repeticao real.
- Integrar ao Nest.
- Atualizar
apps/backend/src/modules/<modulo>/<modulo>.module.ts. - Registrar a classe em
providers. - Exportar a classe quando fizer sentido para outros modulos.
- Atualizar
- Ajustar consumidores do backend.
- Preferir construtores como
constructor(private readonly cryptoProvider: BcryptCryptoProvider). - Permitir que controllers e servicos Nest passem a classe concreta para casos de uso que dependem da interface.
- Nao alterar o contrato do dominio.
- Preferir construtores como
- Instalar dependencias externas quando necessario.
- Preferir instalar no workspace
@poupig/backend. - Exemplos:
npm install --workspace @poupig/backend nodemailernpm install --workspace @poupig/backend jsonwebtoken
- Adicionar
@types/*quando a biblioteca exigir tipos separados.
- Preferir instalar no workspace
- Testar e verificar.
- Criar testes quando houver logica observavel relevante.
- Seguir o padrao de testes do backend se ele existir.
- Quando nao houver padrao claro, criar um
*.spec.tssimples ao lado da implementacao. - Rodar ao menos o build do backend e os testes relevantes do backend quando possivel.
- Reportar resultado.
- Informar interface implementada, modulo inferido, arquivos criados ou alterados e dependencias adicionadas.
Regras de implementacao
- Priorizar implementacao simples, direta e facil de manter.
- A classe concreta deve ficar no backend.
- O backend deve poder injetar a classe concreta diretamente.
- Nao exigir symbol, token ou abstracao extra para a implementacao funcionar no backend.
- Nao adicionar comportamento fora do contrato, exceto detalhes tecnicos inevitaveis da biblioteca usada.
- Nao mover regra de negocio para dentro do provider tecnico.
- Se houver configuracao tecnica pequena e estavel, mantela no proprio arquivo com constantes locais claras.
- Se o provider precisar de configuracao sensivel ou variavel, seguir o padrao ja existente do backend para
ConfigServiceou.env, sem reinventar infraestrutura.
Regras para dependencias externas
- Identificar se a implementacao exige biblioteca externa.
- Reaproveitar primeiro o que ja estiver instalado no projeto.
- Quando precisar instalar algo novo, preferir bibliotecas maduras, simples e compativeis com o projeto.
- Se houver varias opcoes razoaveis e nenhuma preferencia do usuario, escolher a opcao mais simples e estavel.
- Relatar claramente quais dependencias foram adicionadas e por que.
- Evitar dependencias extras quando o runtime do Node ou uma biblioteca ja presente resolverem o contrato.
Regras de integracao com Nest
- Registrar a implementacao concreta em
apps/backend/src/modules/<modulo>/<modulo>.module.ts. - Incluir a classe em
providers. - Incluir em
exportsquando outros modulos puderem precisar dela. - Ajustar o consumo no backend para usar a classe concreta diretamente.
- O padrao preferido e:
- classe concreta registrada no modulo
- classe concreta injetada diretamente em controllers ou servicos Nest
- classe concreta repassada aos casos de uso que dependem da interface do dominio
Regras de adaptacao ao contexto
Esta skill deve se adaptar a providers tecnicos como:
- criptografia
- JWT
- geracao de token
- relogio e data
- uuid
- storage
- integracoes externas simples
Quando a interface nao trouxer contexto suficiente para definir o comportamento com seguranca, parar e pedir esclarecimento.
Regras de testes
- Quando a implementacao tiver logica observavel relevante, criar testes.
- Quando a implementacao depender muito de biblioteca externa, criar ao menos testes uteis para o comportamento esperado e relatar limites de cobertura.
- Seguir o padrao de testes do backend ou do modulo, quando ele existir.
- Preferir testes pequenos e diretos, focados no contrato implementado.
Guardrails
- Nao executar sem alvo inequivoco.
- Nao editar o provider do dominio.
- Nao expandir interfaces do dominio.
- Nao criar tokens ou symbols desnecessarios.
- Nao instalar bibliotecas sem necessidade real.
- Nao ajustar consumidores alem do necessario para a injecao funcionar no backend.
- Nao inventar comportamento quando o contrato estiver incompleto.
Saida esperada
- implementacao concreta criada em
apps/backend/src/modules/<modulo>/ apps/backend/src/modules/<modulo>/<modulo>.module.tsatualizado- consumidores do backend ajustados apenas no necessario para injecao direta
- dependencias externas instaladas apenas quando realmente precisarem
- testes adicionados quando houver comportamento observavel relevante
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |