Imported from ViniciusFrancelino/dev-agent (skills/development/SKILL.md). Install upstream with npx skills add ViniciusFrancelino/dev-agent --skill development. Copyright stays with the author.

Desenvolvimento transversal

Objetivo

Integrar incrementos verificáveis ao projeto, preservando comportamento existente, compatibilidade e escopo. Esta skill define a disciplina transversal; os detalhes de servidor, interface, contratos e dados ficam nas skills de domínio.

Quando usar

Ao implementar funcionalidades, corrigir comportamento ou refatorar código em qualquer tecnologia. Use em conjunto com as especialidades afetadas, sem executar todas por obrigação.

Quando não usar

Em pedidos somente de análise ou revisão, não transforme esta skill em autorização para editar. Não use um procedimento geral para substituir decisões específicas de frontend/backend ou para reestruturar áreas não relacionadas.

Entradas necessárias

Critérios de aceitação, plano e restrições; arquivos e chamadas afetados; convenções; comandos reais de execução e validação; configuração; versões e dependências; estado anterior do trabalho do usuário.

Pré-condições

Se houver código, comece pelo contexto, índice de requisitos, mapa e estado em knowledge/projects/<nome>/, quando disponíveis. Use-os para localizar um fluxo semelhante, consumidores e testes relevantes, confirmando no código e na documentação oficial o que afetar a mudança. Não varra o repositório inteiro por padrão. Em greenfield, crie ou confirme projects/<nome>/ e seu conhecimento correspondente antes da primeira escrita e use o diretório da aplicação como raiz para todo o incremento. Em brownfield, preserve o caminho existente e não o mova implicitamente. Se houver Git, examine estado e diff; sem Git, identifique os arquivos a preservar por comparação ou hash quando necessário. Entenda como reverter suas próprias mudanças sem desfazer trabalho alheio.

Responsabilidades

Organizar incrementos, manter consistência, limitar impacto, tratar erros/configuração, integrar dependências e registrar validação. Encaminhar decisões de domínio e interface às skills especializadas. Não criar camadas, flags ou bibliotecas como ritual.

Workflow

1. Localize o caminho de execução. Encontre entrada, regra, dependência e saída; leia os testes como evidência do comportamento vigente e confira sua correspondência com o requisito.
2. Confirme a fronteira de escrita. Em greenfield, resolva projects/<nome>/ e garanta que código, testes, configuração e documentação da aplicação não escapem desse diretório. Em brownfield, limite-se à raiz indicada e aos arquivos do agente realmente necessários.
3. Mapeie impacto. Liste consumidores, configuração, dados, contratos e documentação alterados. Identifique compatibilidade que precisa sobreviver e efeito externo irreversível.
4. Divida em incrementos. Prefira uma fatia funcional pequena que possa ser exercitada de ponta a ponta. Separe preparação estrutural de mudança de comportamento quando isso facilitar a revisão.
5. Defina a verificação. Escolha entradas, resultados e comandos antes de editar. Para bug, preserve uma reprodução; para regra nova, defina aceitação e casos negativos.
6. Implemente no padrão local. Use nomes do domínio, funções com uma responsabilidade e módulos com dependências claras. Extraia repetição quando a regra compartilhada estiver demonstrada.
7. Trate erros e configuração. Propague causa para a camada que sabe tratá-la; use mensagens públicas seguras. Valide configuração obrigatória no início sem imprimir valores sensíveis.
8. Adicione sinais úteis. Logs devem informar operação, resultado e correlação. Métricas devem medir um risco ou objetivo; traces só onde ajudam a localizar custo/falha.
9. Integre com consumidores. Confira serialização, defaults, nullability, APIs públicas e formatos persistidos. Execute migrations e etapas locais somente no ambiente autorizado.
10. Valide o incremento. Execute testes pertinentes, lint e build necessários a partir da raiz da aplicação; investigue falhas. Depois de passarem, amplie apenas quando houver dependências afetadas ou preocupação concreta.
11. Revise, documente e sincronize o índice. Compare o resultado ao escopo, remova código morto introduzido e atualize instruções/contratos. Atualize somente os arquivos de conhecimento afetados: mapa para estrutura, índice para rastreabilidade, estado para progresso, decisões para escolhas duráveis e validação para comandos comprovados. Registre resultados reais, pendências e reversão quando relevante.

Decisões técnicas

Feature flags não substituem autorização e não devem esconder funcionalidade obrigatória incompleta. Não acrescente um serviço de flags para um cenário resolvido pela configuração existente.

Regras obrigatórias

• Preserve stack, padrões úteis e trabalho do usuário; não faça upgrades em massa nem refatoração alheia ao requisito.
• Nunca crie artefatos de uma nova aplicação na raiz do agente; use somente projects/<nome>/ e não altere projetos irmãos.
• Separe regra de negócio do transporte e da renderização; não use captura genérica para transformar falha em sucesso.
• Não mantenha segredo em código, logs, exemplos ou valores de fallback.
• Configure timeout/cancelamento para operações externas pertinentes; não execute retry de escrita sem analisar duplicidade.
• Documente mudanças observáveis e os passos necessários para executar a versão entregue.
• Não faça commit, publicação ou ação externa irreversível apenas porque os testes passaram.

Anti-padrões e erros comuns

• Criar todos os arquivos antes de exercitar qualquer fluxo.
• Introduzir abstrações universais para um único caso ou serviços gigantes com domínios distintos.
• Mudar formato público e corrigir só os consumidores visíveis no mesmo diretório.
• Capturar exceção, registrar “erro” e continuar como se a operação tivesse sido concluída.
• Deixar flags sem prazo, defaults inseguros ou TODOs que escondem requisitos.
• Trocar testes por screenshots ou logs sem asserção de comportamento quando existe uma regra automatizável.

Checklist de execução

• Caminho e consumidores afetados compreendidos.
• Raiz da aplicação confirmada; nenhuma escrita de produto escapou dela.
• Alterações anteriores do usuário preservadas.
• Incremento tem critério observável e impacto limitado.
• Erros, configuração e sinais operacionais coerentes.
• Compatibilidade e dados antigos considerados.
• Dependências e flags introduzidas possuem motivo.
• Verificações pertinentes passaram e docs refletem o resultado.

Validação

Execute o fluxo alterado com entrada válida, inválida e falha de dependência pertinente. Compare o contrato antigo onde deve permanecer compatível. Confira o diff final por mudanças laterais, artefatos na raiz do agente e alterações em projetos irmãos. Use os comandos reais a partir da raiz do projeto; resultados “não aplicável” ou “não executado” não substituem build/teste necessário.

Evidências esperadas

Requisito/critério ligado ao incremento, arquivos alterados e motivo, testes/comandos e resultados, compatibilidade verificada, configuração documentada e riscos pendentes. Não inclua logs com segredos nem alegue desempenho sem medição.

Critério de conclusão

Conclua quando o incremento atende à aceitação, está integrado, passou nas verificações necessárias e tem documentação atualizada. Pare de ampliar o escopo depois disso. Se uma dependência externa impedir validação, registre o bloqueio, seu impacto e o próximo comando necessário; não declare a implementação validada.

Integração com outras Skills

Use requirements-analysis antes se faltar aceitação. Durante, aplique backend-development ou frontend-development e as skills de contrato/dados afetadas. Use testing em cada incremento e debugging diante de falhas. Finalize com code-review, security-review conforme o risco e documentation.