charlenopires/diretrizes.md

## diretrizes.md

      
    Raw
  

              diretrizes.md
            
          
    Diretrizes Universais de Desenvolvimento de Software

Este documento contém diretrizes críticas e boas práticas para desenvolvimento de software moderno, aplicáveis a qualquer projeto, linguagem ou framework.
Diretrizes Fundamentais

1. Diretriz Research-First (Pesquisa Primeiro)

DIRETRIZ CRÍTICA: Ao encontrar informações desconhecidas, comandos, tecnologias ou recursos não familiares, SEMPRE pesquise informações atualizadas antes de fornecer respostas ou implementar soluções.
Abordagem Research-First: Sempre pesquise e aplique conhecimento de fontes atuais, especialmente para:

Novas versões de frameworks e suas features
Práticas de segurança atualizadas (OWASP Top 10)
Técnicas de otimização de performance
Padrões de desenvolvimento modernos
Configurações específicas de ferramentas
Breaking changes em dependências
Vulnerabilidades conhecidas (CVEs)

Implementação:
# Antes de implementar qualquer solução nova
1. Verificar documentação oficial
2. Pesquisar best practices atuais
3. Validar compatibilidade de versões
4. Checar issues conhecidas
5. Consultar casos de uso reais
2. Diretriz de Limpeza de Cache e Estado

DIRETRIZ DE CACHE: Ao corrigir ou restaurar funcionalidades que estavam funcionando anteriormente:

Verificar Histórico: Use controle de versão (git log, git show) para identificar versão funcional
Restaurar Versão Correta: Use código exato do histórico, não suposições
Limpar Todos os Caches:

Browser cache
Application cache
Build cache
CDN cache
Database query cache


Verificar Restauração: Garantir que código restaurado corresponde exatamente ao funcional
Documentar Mudanças: Adicionar comentários sobre o que foi restaurado e por quê

Estratégias de Cache Management:

Implementar cache invalidation strategies
Usar cache versioning
Aplicar cache-aside pattern
Configurar TTL apropriado

3. Diretriz de Consistência de Linguagem

DIRETRIZ DE CONSISTÊNCIA: Mantenha consistência na escolha de linguagens e tecnologias em todo o projeto.
Regras Críticas:

Linguagem Principal: Defina e mantenha uma linguagem principal para o core do projeto
Scripts e Automação: Use a mesma linguagem do projeto para scripts quando possível
Ferramentas Auxiliares: Minimize o número de linguagens diferentes
Documentação: Mantenha documentação na mesma estrutura do projeto

Benefícios:

✅ Reduz complexidade cognitiva
✅ Facilita onboarding de novos desenvolvedores
✅ Simplifica CI/CD pipeline
✅ Reduz dependências e vulnerabilidades
✅ Melhora manutenibilidade

4. Diretriz de Análise de Existência de Arquivos

DIRETRIZ DE ANÁLISE: Antes de criar ou modificar qualquer arquivo, SEMPRE analise se o arquivo existe e entenda sua estrutura atual.
Regras Críticas:

Verificar Existência: Sempre cheque se arquivo existe antes de criar/sobrescrever
Analisar Estrutura: Entenda padrões de código, imports e arquitetura existentes
Preservar Padrões: Mantenha estilo de código, convenções de nomenclatura
Preferir Edição: Use modificação incremental ao invés de reescrita completa
Verificar Dependências: Valide compatibilidade com código existente

Workflow:
// ✅ Correto
if (fileExists(path)) {
    const content = readFile(path);
    const modified = modifyContent(content);
    updateFile(path, modified);
} else {
    createFile(path, newContent);
}

// ❌ Incorreto
writeFile(path, newContent); // Pode sobrescrever sem verificar
5. Diretriz de Desenvolvimento Modular

DIRETRIZ MODULAR: Todo desenvolvimento deve seguir princípios de arquitetura modular com clara separação de responsabilidades.
Regras Fundamentais:

Separação de Componentes: Cada feature em seu próprio módulo
Interfaces Claras: APIs explícitas entre módulos
Responsabilidade Única: Cada módulo com um propósito claro (SRP)
Injeção de Dependência: Módulos recebem dependências, não as criam
Componentes Reutilizáveis: Construa para reutilização

Estrutura Recomendada:
/module
  /domain       # Lógica de negócio
  /application  # Casos de uso
  /infrastructure # Implementações externas
  /presentation # Interface/API
  /tests       # Testes do módulo

Diretrizes de Arquitetura

6. Diretriz Clean Architecture

DIRETRIZ DE ARQUITETURA LIMPA: Implemente separação clara entre lógica de negócio e dependências externas.
Princípios:

Regra de Dependência: Dependências apontam apenas para dentro
Independência de Framework: Core não depende de frameworks
Testabilidade: Lógica de negócio testável isoladamente
Independência de UI: Lógica separada da apresentação
Independência de Database: Regras de negócio não conhecem persistência

Camadas:

Entities (Core): Regras de negócio empresariais
Use Cases: Regras de negócio da aplicação
Interface Adapters: Conversão de dados
Frameworks & Drivers: Detalhes externos

7. Diretriz de Design Patterns

DIRETRIZ DE PADRÕES: Use design patterns apropriados para resolver problemas recorrentes.
Padrões Essenciais:

Repository Pattern: Abstração de acesso a dados
Factory Pattern: Criação complexa de objetos
Strategy Pattern: Algoritmos intercambiáveis
Observer Pattern: Notificações de mudanças
Decorator Pattern: Extensão de funcionalidades

Anti-Patterns a Evitar:

God Objects/Classes
Spaghetti Code
Copy-Paste Programming
Magic Numbers/Strings
Premature Optimization

8. Diretriz SOLID

DIRETRIZ SOLID: Aplique os cinco princípios SOLID em todo código orientado a objetos.
S - Single Responsibility:
// ✅ Bom
class UserValidator {
  validate(user: User): ValidationResult { }
}

class UserRepository {
  save(user: User): Promise<void> { }
}

// ❌ Ruim
class UserManager {
  validate(user: User) { }
  save(user: User) { }
  sendEmail(user: User) { }
}
O - Open/Closed: Aberto para extensão, fechado para modificação
L - Liskov Substitution: Subtipos devem ser substituíveis por seus tipos base
I - Interface Segregation: Interfaces específicas são melhores que uma geral
D - Dependency Inversion: Dependa de abstrações, não de concreções
Diretrizes de Qualidade de Código

9. Diretriz Clean Code

DIRETRIZ DE CÓDIGO LIMPO: Escreva código que seja fácil de ler, entender e manter.
Nomenclatura:

Nomes revelam intenção
Evite abreviações desnecessárias
Use nomes pronunciáveis e pesquisáveis
Classes: substantivos, Métodos: verbos

Funções:

Pequenas (< 20 linhas idealmente)
Fazem uma coisa bem feita
Um nível de abstração
Máximo 3 parâmetros

Comentários:

Explique o "porquê", não o "quê"
Evite comentários redundantes
Mantenha comentários atualizados
Prefira código autoexplicativo

10. Diretriz DRY (Don't Repeat Yourself)

DIRETRIZ DRY: Evite duplicação de conhecimento e lógica.
Implementação:

Extraia código comum em funções/módulos
Use constantes para valores repetidos
Centralize configurações
Crie abstrações apropriadas

Exceções Válidas:

Quando abstração adiciona complexidade desnecessária
Testes podem ter alguma duplicação para clareza
Quando domínios diferentes coincidentemente têm lógica similar

11. Diretriz KISS (Keep It Simple, Stupid)

DIRETRIZ SIMPLICIDADE: Prefira soluções simples e diretas.
Princípios:

Evite over-engineering
Resolva o problema atual, não futuros hipotéticos
Código simples é mais fácil de manter
Complexidade deve ser justificada

12. Diretriz YAGNI (You Aren't Gonna Need It)

DIRETRIZ YAGNI: Não adicione funcionalidade até que seja necessária.
Aplicação:

Implemente apenas requisitos atuais
Evite "gold plating"
Remova código morto
Simplifique antes de estender

Diretrizes de Testes

13. Diretriz Test-First

DIRETRIZ TDD: Considere escrever testes antes do código de produção.
Ciclo TDD:

Red: Escreva teste que falha
Green: Código mínimo para passar
Refactor: Melhore mantendo testes verdes

Benefícios:

Design emergente melhor
Documentação viva
Confiança para refatoração
Menos bugs em produção

14. Diretriz de Pirâmide de Testes

DIRETRIZ DE TESTES: Mantenha proporção adequada de tipos de testes.
Distribuição Recomendada:

70% Unit Tests: Rápidos, isolados, numerosos
20% Integration Tests: Validam interações
10% E2E Tests: Validam fluxos completos

Qualidade sobre Quantidade:

Foque em testes significativos
Evite testes frágeis
Mantenha testes independentes
Use mocks apropriadamente

15. Diretriz de Cobertura de Testes

DIRETRIZ DE COBERTURA: Mantenha cobertura de testes adequada.
Métricas:

Código crítico: > 90% cobertura
Código geral: > 80% cobertura
Focar em cobertura de caminhos, não apenas linhas
Mutation testing para validar qualidade

Diretrizes de Segurança

16. Diretriz Security by Design

DIRETRIZ DE SEGURANÇA: Incorpore segurança desde o início do desenvolvimento.
Princípios OWASP:

Minimize Attack Surface: Exponha apenas o necessário
Defense in Depth: Múltiplas camadas de segurança
Principle of Least Privilege: Permissões mínimas necessárias
Secure Defaults: Configurações seguras por padrão
Fail Securely: Falhas não devem comprometer segurança

17. Diretriz de Validação de Input

DIRETRIZ DE VALIDAÇÃO: Sempre valide e sanitize todas as entradas.
Implementação:
// Validação em múltiplas camadas
function validateInput(input) {
  // 1. Type checking
  if (typeof input !== 'string') return false;
  
  // 2. Length validation
  if (input.length > MAX_LENGTH) return false;
  
  // 3. Pattern validation
  if (!VALID_PATTERN.test(input)) return false;
  
  // 4. Sanitization
  return sanitize(input);
}
18. Diretriz de Autenticação e Autorização

DIRETRIZ AUTH: Implemente autenticação e autorização robustas.
Requisitos:

Use bibliotecas estabelecidas (não reinvente)
Implemente MFA quando apropriado
Use tokens seguros (JWT com expiração)
Princípio do menor privilégio
Audit logging de acessos

19. Diretriz de Criptografia

DIRETRIZ CRYPTO: Use criptografia apropriada para dados sensíveis.
Regras:

Nunca implemente própria criptografia
Use algoritmos modernos e seguros
Criptografe dados em trânsito (TLS)
Criptografe dados em repouso quando necessário
Gerencie chaves apropriadamente

Diretrizes de Performance

20. Diretriz de Otimização Prematura

DIRETRIZ PERFORMANCE: Evite otimização prematura, mas projete para performance.
Abordagem:

Meça primeiro: Profile antes de otimizar
Identifique gargalos: Foque nos 20% que causam 80% dos problemas
Otimize com dados: Use métricas para guiar otimizações
Valide melhorias: Confirme que otimizações funcionaram

21. Diretriz de Caching

DIRETRIZ CACHE: Implemente caching estratégico para melhorar performance.
Estratégias:

Cache-aside pattern
Write-through cache
Write-behind cache
Refresh-ahead

Níveis de Cache:

Browser cache
CDN cache
Application cache
Database cache

22. Diretriz de Lazy Loading

DIRETRIZ LAZY: Carregue recursos apenas quando necessário.
Aplicações:

Imagens fora da viewport
Módulos JavaScript não críticos
Dados paginados
Features opcionais

23. Diretriz de Database Performance

DIRETRIZ DB: Otimize queries e estrutura de banco de dados.
Práticas:

Evite N+1 queries
Use índices apropriadamente
Normalize quando apropriado
Desnormalize para performance quando justificado
Use query optimization tools

Diretrizes de DevOps

24. Diretriz CI/CD

DIRETRIZ CI/CD: Automatize build, teste e deploy.
Pipeline Mínimo:

Commit Stage: Compile e testes unitários
Acceptance Stage: Testes de integração
Performance Stage: Testes de performance
Security Stage: Security scanning
Deploy Stage: Deploy automatizado

Métricas DORA:

Deployment Frequency: >= Daily
Lead Time: < 1 dia
Change Failure Rate: < 15%
MTTR: < 1 hora

25. Diretriz Infrastructure as Code

DIRETRIZ IaC: Gerencie infraestrutura como código.
Implementação:

Versionamento de toda infraestrutura
Ambientes reproduzíveis
Automated provisioning
Configuration management
Immutable infrastructure

26. Diretriz de Monitoring e Observability

DIRETRIZ OBSERVABILITY: Implemente observabilidade completa.
Três Pilares:

Logs: Eventos estruturados e searchable
Metrics: Métricas de negócio e técnicas
Traces: Distributed tracing

Alerting:

Alerte em sintomas, não causas
Evite alert fatigue
Defina SLIs e SLOs claros
Runbooks para cada alerta

Diretrizes de Documentação

27. Diretriz de Documentação como Código

DIRETRIZ DOCS: Trate documentação como código.
Práticas:

Documentação no repositório
Versionada com código
Review em pull requests
Geração automatizada quando possível
Testes de documentação

28. Diretriz de README

DIRETRIZ README: Todo projeto deve ter README completo.
Estrutura Essencial:
# Nome do Projeto
Descrição clara e objetiva

## Instalação
Passo a passo para setup

## Uso Rápido
Exemplo básico funcional

## Documentação
Links para docs detalhadas

## Contribuindo
Como contribuir

## Licença
Informações de licenciamento
29. Diretriz de ADRs

DIRETRIZ ADR: Documente decisões arquiteturais importantes.
Template ADR:
# ADR-XXX: Título

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
Problema a ser resolvido

## Decision
Solução escolhida

## Consequences
Positivas e negativas
30. Diretriz de API Documentation

DIRETRIZ API: Documente APIs completamente.
Requisitos:

OpenAPI/Swagger specification
Exemplos de requests/responses
Códigos de erro documentados
Versionamento claro
Authentication requirements

Diretrizes de Versionamento

31. Diretriz de Semantic Versioning

DIRETRIZ SEMVER: Use versionamento semântico.
Formato: MAJOR.MINOR.PATCH
Regras:

MAJOR: Breaking changes
MINOR: Novas features (backward compatible)
PATCH: Bug fixes (backward compatible)

32. Diretriz de Git Flow

DIRETRIZ GIT: Use estratégia de branching consistente.
Branches:

main/master: Código em produção
develop: Integração de features
feature/*: Desenvolvimento de features
hotfix/*: Correções urgentes
release/*: Preparação de releases

33. Diretriz de Conventional Commits

DIRETRIZ COMMITS: Use conventional commits.
Formato:
<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

feat: Nova feature
fix: Correção de bug
docs: Documentação
style: Formatação
refactor: Refatoração
test: Testes
chore: Manutenção

Diretrizes de Colaboração

34. Diretriz de Code Review

DIRETRIZ REVIEW: Todo código deve passar por review.
Checklist de Review:

 Código atende requisitos
 Testes adequados incluídos
 Sem código duplicado
 Performance aceitável
 Segurança verificada
 Documentação atualizada

35. Diretriz de Pair Programming

DIRETRIZ PAIR: Use pair programming para código crítico.
Quando Aplicar:

Código complexo ou crítico
Onboarding de novos membros
Debugging difícil
Design de nova arquitetura

36. Diretriz de Knowledge Sharing

DIRETRIZ KNOWLEDGE: Compartilhe conhecimento ativamente.
Práticas:

Documentação técnica
Tech talks regulares
Pair programming
Code reviews educativos
Runbooks e playbooks

Diretrizes de Acessibilidade e Internacionalização

37. Diretriz de Acessibilidade

DIRETRIZ A11Y: Desenvolva com acessibilidade em mente.
WCAG 2.1 Guidelines:

Perceivable: Informação apresentável a todos
Operable: Interface utilizável por todos
Understandable: Informação e UI compreensíveis
Robust: Compatível com tecnologias assistivas

38. Diretriz de Internacionalização

DIRETRIZ I18N: Prepare aplicação para múltiplos idiomas.
Implementação:

Externalize strings
Use Unicode (UTF-8)
Considere direção de texto (RTL/LTR)
Formate datas/números por locale
Planeje para expansão de texto

Diretrizes de Tratamento de Erros

39. Diretriz de Error Handling

DIRETRIZ ERRORS: Implemente tratamento de erros robusto.
Estratégias:
// Estrutura de erro consistente
class AppError extends Error {
  constructor(message, code, statusCode) {
    super(message);
    this.code = code;
    this.statusCode = statusCode;
    this.timestamp = new Date();
  }
}

// Tratamento centralizado
function errorHandler(error, req, res, next) {
  logger.error(error);
  
  if (error instanceof AppError) {
    return res.status(error.statusCode).json({
      error: {
        code: error.code,
        message: error.message
      }
    });
  }
  
  // Error genérico
  res.status(500).json({
    error: {
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred'
    }
  });
}
40. Diretriz de Logging

DIRETRIZ LOGS: Implemente logging estruturado e útil.
Níveis de Log:

TRACE: Debug muito detalhado
DEBUG: Informação de debug
INFO: Fluxo normal da aplicação
WARN: Situações potencialmente problemáticas
ERROR: Erros que permitem continuação
FATAL: Erros que forçam shutdown

Structured Logging:
{
  "timestamp": "2025-01-08T10:30:00Z",
  "level": "ERROR",
  "service": "user-service",
  "traceId": "abc-123",
  "userId": "user-456",
  "message": "Failed to process payment",
  "error": {
    "type": "PaymentGatewayError",
    "code": "INSUFFICIENT_FUNDS"
  }
}
Diretrizes de Melhoria Contínua

41. Diretriz de Refactoring

DIRETRIZ REFACTOR: Refatore continuamente.
Boy Scout Rule: "Deixe o código melhor do que encontrou"
Quando Refatorar:

Ao adicionar feature
Ao corrigir bug
Durante code review
Quando identificar code smell

42. Diretriz de Technical Debt

DIRETRIZ DEBT: Gerencie débito técnico ativamente.
Gestão:

Documente débito técnico
Priorize pagamento
Aloque tempo para refactoring
Evite acúmulo excessivo

43. Diretriz de Learning Culture

DIRETRIZ LEARNING: Promova cultura de aprendizado.
Práticas:

20% do tempo para aprendizado
Hackathons e innovation days
Conferências e treinamentos
Experimentação segura
Post-mortems sem culpa

Implementação e Adoção

Roadmap de Implementação

Fase 1 - Fundamentos (Meses 1-2):

Estabelecer versionamento e branching
Implementar CI/CD básico
Definir code standards
Setup de ferramentas de análise

Fase 2 - Qualidade (Meses 3-4):

Implementar testes automatizados
Code review process
Documentação básica
Monitoring essencial

Fase 3 - Otimização (Meses 5-6):

Performance optimization
Security hardening
Advanced monitoring
Documentation completa

Fase 4 - Excelência (Contínuo):

Refinamento contínuo
Automação avançada
Innovation time
Knowledge sharing

Métricas de Sucesso

Qualidade:

Bug rate: < 5 por sprint
Code coverage: > 80%
Technical debt ratio: < 5%
Security vulnerabilities: Zero críticas

Produtividade:

Lead time: < 2 dias
Deploy frequency: Daily
MTTR: < 1 hora
Change failure rate: < 10%

Satisfação:

Developer happiness: > 8/10
Code quality satisfaction: > 7/10
Tool satisfaction: > 8/10

Considerações Finais

Estas diretrizes representam as melhores práticas da indústria de software. A implementação deve ser:

Gradual: Não tente implementar tudo de uma vez
Adaptada: Ajuste ao contexto do seu projeto
Medida: Use métricas para validar eficácia
Revisada: Atualize diretrizes conforme necessário
Compartilhada: Garanta que toda equipe conhece e segue

O sucesso depende do comprometimento da equipe e da liderança em seguir e evoluir estas práticas continuamente.

Versão: 1.0.0 | Última atualização: Janeiro 2025
No results found