Olá! Seja bem-vindo ao Módulo 9.
Na última lição, você montou um fluxo de trabalho completo e, crucialmente, observável para seu agente. Ele agora pode executar uma tarefa do Jira de ponta a ponta e fornecer a rastreabilidade necessária para depuração e auditoria. Agora que o ciclo funcional está estabelecido, nosso foco muda para a qualidade do que o agente produz.
Um agente que gera código que não segue os padrões da sua equipe cria mais trabalho, não menos. Ele deve produzir código que seja limpo, consistente e que se alinhe com as convenções existentes. Esta lição aborda a primeira e mais fundamental camada de garantia de qualidade, focando no resultado de aprendizagem: integrar ferramentas de linting automatizado para verificar o código gerado em relação às convenções do projeto.
Veremos como usar ferramentas de análise de código estático (linters) para criar um portão de qualidade automático, garantindo que a saída do seu agente seja profissional e consistente, independentemente da linguagem.
1. O Papel do Linting na Geração de Código por IA
Você, como desenvolvedor experiente, já está familiarizado com linters. São ferramentas que analisam o código-fonte para sinalizar erros de programação, bugs, erros estilísticos e construções suspeitas, sem a necessidade de compilar ou executar o programa. Exemplos comuns incluem Roslyn Analyzers para C# e ESLint para JavaScript.
Quando se trata de código gerado por IA, o linting se torna ainda mais crítico. Embora os LLMs sejam excelentes na geração de lógica funcional, eles podem ser inconsistentes em:
- Estilo de formatação: Espaçamento, quebra de linhas e uso de chaves podem variar.
- Convenções de nomenclatura: Podem não seguir estritamente as convenções
camelCaseouPascalCasedo seu projeto. - Padrões específicos do projeto: Podem não saber que sua equipe prefere, por exemplo,
guard clausesem vez de blocosif-elseaninhados.
O linting automatiza o feedback sobre essas regras, transformando-as de preferências subjetivas em requisitos verificáveis. Para seu agente, isso estabelece um portão de qualidade claro: o código só é aceitável se passar nas verificações do linter.
2. Implementando Linting em Projetos .NET
No ecossistema .NET, a análise estática de código é uma capacidade de primeira classe, fornecida pelos Roslyn Analyzers. Eles são integrados ao processo de build, permitindo que você aplique regras de qualidade de forma consistente.
Para garantir que essas regras sejam aplicadas de forma rigorosa em um ambiente de automação, usamos algumas configurações chave.
Continuous Integration Will Give You Superpowers | GitHub Actions + .NET
O vídeo 'Continuous Integration Will Give You Superpowers' de Milan Jovanović demonstra de forma concisa como configurar um projeto .NET para uma análise de código rigorosa. Os conceitos são diretamente aplicáveis à garantia de qualidade do código do seu agente.
Assista a estas seções para entender os três principais arquivos de configuração: 00:00 - 01:41: Preste atenção na configuração <TreatWarningsAsErrors>true</TreatWarningsAsErrors>. Em um fluxo de trabalho de CI/CD, transformar avisos de qualidade em erros de build é a maneira mais eficaz de garantir que eles não sejam ignorados. 02:25 - 03:36: Veja como o arquivo .editorconfig é usado para definir regras de estilo e, mais importante, para configurar a severidade de regras específicas do analisador (ou até mesmo desativá-las) para alinhar com as convenções da sua equipe. 03:36 - 04:26: Entenda o papel do Directory.Build.props. Este arquivo é extremamente útil para aplicar configurações de build, como TreatWarningsAsErrors, a todos os projetos em uma solução, garantindo consistência sem precisar editar cada arquivo .csproj individualmente.
Para integrar isso ao fluxo de trabalho do seu agente, o processo de CI (Continuous Integration) acionado pela criação do Pull Request deve incluir uma etapa para verificar a formatação. A ferramenta dotnet format é perfeita para isso.
Em seu fluxo de trabalho do GitHub Actions, você adicionaria uma etapa como esta:
- name: Check Formatting
run: dotnet format --verify-no-changes --verbosity diagnostic
Se dotnet format encontrar qualquer inconsistência de estilo, o comando falhará (retornando um código de saída diferente de zero), fazendo com que a verificação do CI falhe.
3. Implementando Linting em Projetos React/JavaScript
Para o seu frontend em React e JavaScript, as ferramentas padrão da indústria são ESLint (para qualidade e regras de código) e Prettier (para formatação de código opinativa). Para automatizar sua execução, usamos Husky para gerenciar Git hooks (como pré-commit) e GitHub Actions para a verificação no lado do servidor.
O vídeo a seguir oferece um guia completo sobre como configurar todo esse pipeline.
CI/CD Pipeline in React.js Project with Github Workflows using Eslint Prettier Pre-commit and Husky
O vídeo 'CI/CD Pipeline in React.js Project with Github Workflows' de Programming with Umair cobre todo o processo, desde a configuração local com ESLint e Husky até a automação no CI com GitHub Actions.
Siga estas seções para configurar seu projeto React: 07:06 - 08:14: Veja como instalar os pacotes necessários: eslint, prettier e seus plugins. 08:14 - 10:29: Foque na criação e configuração dos arquivos de regras: .eslintrc.cjs para as regras do ESLint e .prettierrc para as regras do Prettier. 10:29 - 12:26: Aprenda a adicionar scripts ao seu package.json, como lint, lint:fix e format, que encapsulam os comandos da CLI para facilitar a execução. 12:26 - 15:15: Esta seção explica como usar Husky e lint-staged para executar automaticamente seus scripts de linting antes de cada commit. Isso cria uma primeira linha de defesa local. 25:22 - 33:21: Esta é a parte mais crucial para a automação do agente. Veja como criar um arquivo de fluxo de trabalho do GitHub Actions (.github/workflows/ci.yml) que executa os scripts de linting (npm run lint) no servidor sempre que um pull request é criado ou atualizado. Isso serve como o portão de qualidade final e não pode ser contornado.
O passo chave no seu arquivo ci.yml seria semelhante a este:
- name: Run Linters
run: npm run lint
Assim como no .NET, se o script lint detectar problemas, ele sairá com um erro, e a verificação do CI falhará, bloqueando o merge do Pull Request.
4. Estratégias para o Agente Interagir com Linters
Agora que os portões de qualidade estão configurados, como seu agente de codificação deve interagir com eles? Existem algumas abordagens.
Abordagem 1: Gerar e Deixar o CI Verificar (Reativa)
A abordagem mais simples é fazer com que o agente gere o código, crie o Pull Request e deixe o pipeline de CI fazer seu trabalho. Se o linting falhar, o status do PR indicará o erro.
- Vantagem: Simples de implementar. A lógica do agente não precisa se preocupar com o linting.
- Desvantagem: É reativo. Requer intervenção (humana ou do próprio agente em uma segunda passagem) para corrigir o PR com falha, tornando o processo menos eficiente.
Abordagem 2: Gerar, Verificar e Auto-Corrigir (Proativa)
Uma abordagem mais sofisticada é capacitar o agente a usar as ferramentas de linting como uma de suas tools.
- Geração: O agente gera o bloco de código inicial.
- Verificação: O agente executa o comando de lint localmente (ex:
npm run lintoudotnet format --verify-no-changes) e captura a saída. - Refinamento: Se o comando falhar, o agente pega a saída do erro do linter e a usa como contexto adicional em um novo prompt para o LLM. Por exemplo: "O código que você gerou falhou na verificação de linting com os seguintes erros: [saída do linter]. Por favor, corrija o código para resolver esses problemas."
- Repetição: O agente repete os passos 2 e 3 até que a verificação de linting passe.
- Commit: Apenas o código limpo e verificado é enviado para o repositório.
Coding with AI Agents | Qlty Docs
O documento 'Coding with AI Agents' da Qlty Docs, embora focado em sua própria ferramenta, descreve perfeitamente a estratégia de auto-correção. Os princípios são universais e aplicáveis a qualquer ferramenta de linting via CLI.
Leia estas seções para entender como instruir um agente a usar ferramentas de qualidade: 'Use Qlty CLI with AI Coding Agents': Entenda o conceito de um 'quality gate' que o agente pode executar como parte de seu fluxo de trabalho. 'Integration methods': Observe as diferentes maneiras de integrar essa verificação, incluindo 'Project memory/instructions'. Exemplo de instrução: A instrução - Before finishing, ALWAYS run 'qlty check --fix' é um exemplo perfeito de como você pode instruir seu agente em Rovo a executar seus próprios scripts (npm run lint ou dotnet format).
Abordagem 3: Delegar ao Rovo Dev e Evitar Redundância
O Atlassian Rovo Dev já inclui um agente de revisão de código que analisa Pull Requests. Se você tem um pipeline de CI robusto que já verifica a formatação, é ineficiente fazer o agente de revisão do Rovo comentar sobre os mesmos problemas.
Nesse caso, você deve instruir o Rovo a ignorar problemas de formatação e focar em questões de nível superior, como lógica, arquitetura e segurança.
Set custom instructions for code reviews | Rovo - Atlassian Support
A documentação do Rovo Dev explica como personalizar o agente de revisão de código. Isso é fundamental para criar uma sinergia entre seus linters automatizados e a revisão por IA.
Leia estas seções para aprender a configurar o agente de revisão: 'Set custom instructions for a repository': Veja como criar o arquivo de configuração .rovodev/.review-agent.md no seu repositório. 'How to write effective custom instructions': Entenda as melhores práticas para escrever instruções claras. 'Examples of custom instructions': Role até a seção 'Review topics to exclude'. A instrução When you find non-critical code formatting issues, you should avoid leaving any suggestions because we have linter rules in place to cover these issues. é exatamente o que você precisa. Ela diz ao Rovo para confiar no seu pipeline de CI para formatação e se concentrar em feedback mais valioso.
Conclusão
Nesta lição, você aprendeu a estabelecer a primeira e mais importante linha de defesa para a qualidade do código gerado pelo seu agente: o linting automatizado.
Principais Pontos:
- Linting é essencial para garantir que o código gerado por IA siga os padrões de estilo e convenções do seu projeto.
- A melhor maneira de aplicar as regras de linting é como uma etapa obrigatória no seu pipeline de CI/CD (usando GitHub Actions), que atua como um portão de qualidade final.
- Para projetos .NET, você pode usar
dotnet formate configurar Roslyn Analyzers através de arquivosDirectory.Build.propse.editorconfig. - Para projetos JavaScript/React, a combinação de ESLint, Prettier e scripts
npmno CI é a abordagem padrão. - Você pode projetar seu agente para ser proativo, executando linters como uma ferramenta de auto-correção, ou reativo, deixando o CI reportar as falhas.
- Ao usar agentes de revisão como o Rovo Dev, você deve instruí-los a ignorar problemas de formatação já cobertos pelo seu pipeline de CI para evitar feedback redundante.
Com os linters configurados, você tem a garantia de que o código do agente está estilisticamente correto. No entanto, um código bem formatado ainda pode não funcionar.
Na próxima lição, daremos o próximo passo na garantia de qualidade: acionar o processo de build para verificar a sintaxe e a correção das dependências, garantindo que o código gerado pelo menos compile com sucesso.