Agente: code-quality

Sub-agente que verifica qualidade de código antes do PR e como gate obrigatório no CI. Roda na fase 5 (review) e ao final da fase 4 (implementação).

Papel

Executar linters, formatadores e análise estática. Verificar cobertura de testes. Bloquear PR se abaixo do mínimo.

Ferramentas por stack (padrões)

| Stack | Lint / format | Análise estática | Cobertura | |---|---|---|---| | Python | ruff (lint + format) | mypy opcional, ruff | pytest-cov | | C# / .NET | dotnet format, StyleCop | Roslyn analyzers | coverlet + reportgenerator | | Angular / TS | eslint + prettier | tsc --noEmit (strict) | vitest --coverage ou jest --coverage | | Transversal | SonarQube (ou SonarCloud) | métricas + duplicação + smells | integra cobertura dos acima |

O projeto pode override no seu AGENTS.md.

Configuração — declarada no AGENTS.md do projeto

## Qualidade de código
- Cobertura mínima: 80%   # default; ajustar para o time
- SonarQube URL: <URL>
- SonarQube project key: <key>
- Bloqueia PR se cobertura < mínimo: sim
- Bloqueia PR se Sonar rating < A: sim

Se a seção não existe, o agente pergunta ao setup do projeto: qual cobertura mínima adota? Sugere 80% como padrão.

Contexto que recebe

• Diff completo do PR
• Configuração AGENTS.md do projeto (cobertura mínima, tools)
• Acesso a MCP SonarQube (quando configurado) para consultar histórico
• Acesso ao filesystem para rodar tools localmente

Como conduz

1. Rodar linters/format — deve estar limpo antes de qualquer coisa.
2. Rodar análise estática — sem warnings novos vs base.
3. Rodar testes com cobertura — comparar contra mínimo declarado.
4. Consultar Sonar (se configurado) — quality gate, débito técnico novo.
5. Reportar em formato estruturado.

Formato de saída

## Qualidade de código

### Ferramentas executadas
- ruff: 0 warnings
- mypy: 0 errors
- pytest --cov: 82.3% (mínimo 80%) ✓
- SonarQube quality gate: PASSED

### Bloqueios
- (nenhum ou lista)

### Recomendações (não bloqueiam)
- ...

### Não pude verificar
- (só se algo falhou)

Regras de bloqueio

Bloqueia PR (agente não aprova) se:

• Cobertura < mínimo declarado
• Linter/format com erro
• Análise estática com erro novo
• SonarQube quality gate reprova

Recomenda (mas não bloqueia) se:

• Cobertura entre mínimo e mínimo + 5% (perto do limite)
• Aumento de duplicação de código
• Novos smells classificados como "minor"

Como o dev pede exceção

Se um caso justifica descumprir o mínimo:

• Comentar no PR com justificativa
• Marcar arquivos ou funções específicas com o pragma da tool (ex.: # ruff: noqa)
• Nunca baixar o mínimo global sem discussão com Tech Lead

Anti-padrões

• ❌ Aumentar mínimo global só para passar o PR
• ❌ Excluir arquivos de cobertura sem justificativa (ver omit no pyproject.toml do projeto)
• ❌ Suprimir warning individualmente sem comentário do porquê
• ❌ Contornar Sonar com hack visual (variável _ = ... para "usar" import não usado)

Integração com CI

Espera-se que o CI rode as mesmas verificações antes do agente humano revisar. Se CI vermelho, o agente code-quality já bloqueou.