Agentic Coding

Há uma diferença fundamental entre usar um LLM como autocomplete glorificado e usar um LLM como agente que age no seu repositório. No primeiro caso, o modelo responde a uma pergunta ou completa um fragmento de código; o engenheiro copia, cola, adapta. No segundo caso, o modelo lê arquivos do repositório, edita código, executa comandos, lê o output, e itera — tudo dentro de um loop que pode produzir dezenas de mudanças sem intervenção humana entre elas. A diferença não é de grau, é de natureza. E ela muda radicalmente tanto o que é possível quanto o que pode dar errado.

Agentic coding é o paradigma em que um LLM opera como agente dentro de um ambiente de desenvolvimento: tem acesso a ferramentas (ler arquivo, escrever arquivo, executar shell, buscar no repositório, fazer requisição HTTP), toma decisões sobre qual ferramenta usar com base no contexto, observa o resultado, e decide o próximo passo. Claude Code é o exemplo mais direto: um agente de linha de comando que pode ler qualquer arquivo do repositório, editar código, rodar testes, e executar comandos — tudo guiado por linguagem natural. Cursor, GitHub Copilot Workspace, e Devin são variantes do mesmo paradigma com trade-offs diferentes de autonomia e controle.

Para o engenheiro sênior, entender agentic coding não é opcional. É o modo de trabalho com IA que está se tornando padrão para tarefas de mais de trivial — e é onde os riscos de LLMs se amplificam mais, porque o agente pode tomar decisões encadeadas sem que o humano intervenha entre elas. Saber quando deixar o agente rodar autonomamente, quando aprovar cada passo, e como estruturar o trabalho para maximizar o controle sem perder a velocidade é a habilidade central deste conceito.

Começamos pela arquitetura que torna agentic coding possível — o loop que transforma um modelo de linguagem em agente —, depois descemos para as ferramentas concretas e o ciclo de trabalho que emerge delas.

O loop agentivo: como um LLM se torna agente

Um LLM por si só é stateless: recebe um prompt, produz um output, termina. Para se tornar agente, precisa de um loop externo que mantém estado, fornece ferramentas, e decide quando parar. A arquitetura básica — descrita no paper "ReAct: Synergizing Reasoning and Acting in Language Models" (Yao et al., 2022) — alterna entre três fases: Thought (o modelo raciocina sobre o estado atual e o próximo passo), Action (o modelo escolhe uma ferramenta e fornece os argumentos), e Observation (o ambiente executa a ferramenta e retorna o resultado). O loop continua até o modelo considerar a tarefa completa ou um critério externo de parada ser atingido.

Na prática, o loop de Claude Code funciona assim: o usuário fornece uma instrução em linguagem natural ("adicione tratamento de erro ao handler de pagamentos seguindo o padrão do restante da base"). O agente lê o arquivo do handler, lê outros handlers como referência de padrão, propõe mudanças, edita o arquivo, roda os testes, lê o output dos testes, corrige se necessário, e retorna ao usuário com o resultado. Cada etapa é uma ferramenta: Read, Edit, Bash (para executar testes), Grep (para buscar padrões), e assim por diante.

O que torna isso qualitativamente diferente de chat com LLM é o contexto acumulado: o agente não está respondendo a um prompt estático — está operando em um ambiente que muda a cada ação. Quando edita um arquivo, o arquivo mudou; quando roda testes, o output dos testes é novo contexto; quando encontra um erro, ajusta o plano. Esse loop de feedback é o que permite ao agente resolver problemas que requerem múltiplos passos de diagnóstico e correção.

Claude Code — arquitetura e ferramentas

Claude Code é um agente de linha de comando desenvolvido pela Anthropic que roda diretamente no terminal, tem acesso ao sistema de arquivos local, e usa o modelo Claude como motor de raciocínio. Diferente de plugins de IDE, Claude Code tem acesso irrestrito ao repositório — pode ler qualquer arquivo, executar qualquer comando shell, fazer chamadas HTTP — o que o torna simultaneamente mais poderoso e mais arriscado que ferramentas mais restritas.

As ferramentas disponíveis ao agente incluem: Read (ler arquivo com offset e limite de linhas), Edit (substituição de string exata em arquivo existente), Write (criar ou sobrescrever arquivo), Bash (executar comando shell com timeout), Glob (encontrar arquivos por padrão), Grep (busca por conteúdo com regex), e Agent (subagente para tarefas paralelas). Esse conjunto é suficiente para operar em qualquer repositório sem necessidade de configuração especial.

A configuração primária do comportamento do agente é o arquivo CLAUDE.md na raiz do repositório (ou em subdiretórios). Esse arquivo é lido automaticamente no início de cada sessão e define: convenções do projeto, restrições de comportamento, padrões de código que o agente deve seguir, comandos úteis, e qualquer contexto de domínio que o agente precisaria para trabalhar corretamente. Um CLAUDE.md bem escrito reduz dramaticamente a quantidade de contexto que precisa ser fornecido em cada instrução — o agente já "sabe" as convenções da base.

O modelo de permissões do Claude Code é configurável: em modo padrão, o agente pergunta antes de executar ações destrutivas (deletar arquivos, executar comandos que modificam o sistema); em modo --dangerously-skip-permissions, executa tudo sem confirmação. Para uso em pipelines de CI ou scripts automatizados, o modo não-interativo com permissões pré-aprovadas é o padrão; para uso interativo, confirmar ações importantes mantém o controle humano.

Cursor — tab completion vs agent mode

Cursor é um editor de código (fork do VS Code) com LLM integrado em dois modos de operação distintos que servem a propósitos muito diferentes. Entender a diferença é essencial para usá-lo produtivamente.

Tab completion é o modo passivo: enquanto você escreve, o Cursor sugere completions baseados no arquivo atual, arquivos do repositório, e contexto da edição. A analogia é GitHub Copilot — o modelo observa o que você está escrevendo e propõe o próximo fragmento. O controle é total: cada keystroke é seu, cada tab que você pressiona para aceitar é uma decisão explícita. O risco é baixo porque o agente não age autonomamente.

Agent mode é o modo ativo: você fornece uma instrução em linguagem natural e o Cursor cria um plano, edita múltiplos arquivos, roda comandos, e apresenta as mudanças para aprovação. A diferença para Claude Code é de interface (IDE vs terminal) e de nível de automação: Cursor por padrão apresenta um diff de cada mudança para aprovação antes de aplicar, enquanto Claude Code aplica as mudanças e notifica depois (dependendo da configuração de permissões). Para engenheiros que querem aprovação granular, Cursor tem vantagem; para tarefas longas onde interrupção a cada mudança atrasaria, Claude Code com contexto rico e CLAUDE.md bem configurado é mais eficiente.

O novo ciclo de desenvolvimento com agente

O ciclo de trabalho com agentic coding é diferente do ciclo tradicional e requer ajuste de hábitos. O ciclo que emerge da experiência com times que adotaram as ferramentas tem quatro fases:

Fase 1 — Orientação do agente. Antes de instruir o agente, garantir que ele tem contexto suficiente: CLAUDE.md está atualizado com convenções relevantes, a instrução inclui referências a arquivos ou padrões que o agente deve seguir, e o escopo está claramente delimitado. Uma instrução vaga produz output que satisfaz a descrição vaga — o mesmo problema de prompt fraco do conceito anterior, mas amplificado porque o agente vai fazer múltiplas ações antes de você intervir.

Fase 2 — Execução com observação. O agente executa. O engenheiro observa o log de ações sem intervir a cada passo, mas monitorando se o agente está indo na direção certa. Se o agente toma uma decisão de design claramente errada logo no início (usa uma abstração errada, edita o arquivo errado), vale interromper cedo. Deixar o agente chegar ao final de um caminho errado e então corrigir custa mais contexto e tempo do que corrigir o rumo a tempo.

Fase 3 — Revisão do output. Quando o agente termina, o engenheiro revisa cada mudança com o mesmo rigor de um code review: o código faz o que a instrução pediu? Respeita as invariantes do domínio? Usa as abstrações corretas? Tem algum caso de borda não tratado? Tem alguma regressão em funcionalidade adjacente? A revisão não é superficial porque o agente rodou os testes — os testes podem estar passando e o código ainda estar errado em relação às invariantes de negócio que os testes não cobrem.

Fase 4 — Iteração dirigida. Se há problemas, o engenheiro instrui correções específicas ("o tratamento de erro no caso de timeout está faltando, deve seguir o padrão do handler de pedidos"). O agente corrige. O ciclo de revisão se repete até o código satisfazer o critério de aceitação. Iterações subsequentes são geralmente mais rápidas porque o agente tem mais contexto acumulado sobre o que está sendo construído.

Quando delegar e quando retomar controle

A decisão mais importante em agentic coding não é qual ferramenta usar — é qual nível de autonomia conceder ao agente para cada tipo de tarefa. A heurística que emerge de uso em produção divide as tarefas em três categorias.

Delegação completa — agente autônomo até o fim. Tarefas bem-definidas, mecânicas, com comportamento esperado claro e verificável por testes: gerar testes unitários para código existente, aplicar refactoring de nome em toda a base, migrar chamadas de uma versão de API para outra, gerar código boilerplate que segue padrão estabelecido, criar um endpoint seguindo exatamente o padrão de um endpoint existente. Nessas tarefas, o agente tem contexto suficiente, o comportamento esperado é não-ambíguo, e o risco de decisão errada encadeada é baixo.

Aprovação por passo — agente como par controlado. Tarefas que envolvem decisões de design, integração com múltiplos componentes, ou lógica de negócio não-trivial: implementar uma feature nova, refatorar uma abstração que afeta múltiplos módulos, integrar uma nova dependência. Aqui, o modo de Cursor com diff por mudança ou o uso de permissões explícitas no Claude Code garante que cada mudança significativa passa pelo olhar humano antes de ser aplicada.

Retomar controle — agente como pesquisador, humano como implementador. Decisões arquiteturais, escolha de padrões para funcionalidade nova em área complexa, código que afeta segurança ou integridade de dados. Nesses casos, o agente pode ser útil para explorar alternativas, ler código existente e sintetizar padrões, ou gerar um sketch inicial — mas a implementação final passa pelo engenheiro que entende as invariantes sistêmicas que o agente não conhece.

# CLAUDE.md — Projeto OrderService

## Stack
- .NET 10, ASP.NET Core Minimal API
- Entity Framework Core 9 + Postgres
- xUnit + FluentAssertions + NSubstitute
- Polly v8 para resiliência
- OpenTelemetry para observabilidade

## Convenções de código
- Handlers em `Features/{Domínio}/{Ação}Handler.cs`
- Padrão Result<T> para erros de domínio (não exceptions)
- Nunca usar `Task.Result` ou `.Wait()` — sempre await
- Logs com ILogger<T>, sempre structured: _log.Information("Order {OrderId} processed", id)
- Todos os endpoints têm teste de integração em `Tests/Integration/`

## Comandos úteis
- `dotnet test` — roda todos os testes
- `dotnet ef migrations add Nome` — nova migration
- `docker-compose up -d` — sobe Postgres + Redis local

## Restrições
- Nunca commitar secrets ou connection strings hardcoded
- Migrations devem ser zero-downtime (expand-contract)
- Não adicionar dependências sem discussão no PR

# Instrução eficaz para Claude Code em projeto FastAPI:

"""
Adiciona endpoint POST /api/v1/orders/{order_id}/cancel

Contexto:
- Olha o endpoint POST /api/v1/orders/{order_id}/confirm
  em src/routes/orders.py como referência de padrão
- Usa o mesmo padrão de autenticação (get_current_user)
- Usa OrderService.cancel_order() que já existe em
  src/services/order_service.py

Comportamento:
- Só owner do pedido pode cancelar (verificar user_id)
- Pedidos com status Shipped ou Delivered → 422 com
  mensagem "Order cannot be cancelled in current status"
- Em sucesso: dispara OrderCancelledEvent via event_bus
- Retorna OrderResponse com status atualizado

Testes:
- Cria test_cancel_order.py em tests/routes/ seguindo
  o padrão de test_confirm_order.py
- Cobre: sucesso, não-owner, status inválido, order não encontrada
"""

// Instrução ao agente:
// "Adiciona handler para DELETE /orders/{id} no router
// em cmd/api/routes.go. Segue o padrão do handler
// DELETE /products/{id} em internal/handlers/products.go.
// Soft delete: marca deleted_at, não remove do banco.
// Testa com go test ./internal/handlers/..."

// O agente vai:
// 1. Ler internal/handlers/products.go (padrão de referência)
// 2. Ler internal/handlers/orders.go (handlers existentes)
// 3. Ler internal/store/orders.go (interface do store)
// 4. Escrever o handler seguindo o padrão observado
// 5. Adicionar rota em cmd/api/routes.go
// 6. Escrever teste em internal/handlers/orders_test.go
// 7. Rodar: go test ./internal/handlers/...
// 8. Corrigir se algum teste falhar

// O engenheiro revisa:
// - O handler verifica que o usuário é dono do pedido?
// - O soft delete usa a coluna certa (deleted_at)?
// - O teste cobre o caso de pedido não encontrado?
// - O teste cobre o caso de não-owner tentando deletar?
// - A rota foi adicionada no lugar certo no router?

Gerenciando contexto em sessões longas

O contexto de uma sessão de agente tem limite: Claude Code usa compressão automática quando o contexto fica longo, mantendo um resumo das ações passadas em vez do histórico completo. Isso é geralmente transparente, mas tem implicações práticas para sessões muito longas.

Para tarefas longas — implementar um feature completo que envolve múltiplos arquivos e múltiplos ciclos de teste — a estratégia mais eficaz é dividir em sub-tarefas com pontos de checkpoint explícitos. Em vez de "implemente o sistema de notificações completo", quebre em: "1) crie a interface INotificationService e seus tipos; 2) implemente EmailNotificationService seguindo a interface; 3) implemente PushNotificationService; 4) adicione o handler que orquestra os dois". Cada sub-tarefa tem contexto mais focado, output mais verificável, e o risco de perda de contexto é menor.

O arquivo CLAUDE.md também mitiga o problema de contexto: como é lido no início de cada sessão, as convenções e restrições críticas estão sempre disponíveis independente de quanto contexto foi comprimido durante a sessão.

Agentic coding e o princípio do menor privilégio

Um agente com acesso irrestrito ao sistema de arquivos e ao shell é um risco potencial: pode deletar código importante, expor secrets em logs, fazer chamadas HTTP não-autorizadas, ou executar comandos com consequências difíceis de reverter. O princípio do menor privilégio — dar ao agente apenas o acesso que ele precisa para a tarefa — aplica-se aqui da mesma forma que aplica-se a serviços de software.

As mitigações práticas incluem: rodar o agente em um diretório de trabalho limitado quando possível; usar git como rede de segurança (todo trabalho em branch, nunca direto em main; commits frequentes durante a sessão para poder reverter); configurar o modo de permissões para confirmar antes de executar comandos destrutivos; e nunca deixar o agente rodar em ambiente com credenciais de produção ou acesso a dados sensíveis reais.

A configuração de hooks no Claude Code — comandos executados automaticamente em resposta a eventos do ciclo de vida do agente — permite adicionar camadas de verificação: um hook pre-tool-call pode logar cada ação antes de executar, um hook post-commit pode rodar linters automaticamente, um hook pre-bash pode bloquear comandos que correspondam a padrões proibidos. Hooks são a forma de institucionalizar restrições no nível do agente sem depender de instrução por instrução.

Devin, GitHub Copilot Workspace e o espectro de autonomia

Devin (Cognition AI, 2024) foi o primeiro agente de software amplamente divulgado com autonomia completa: dado um issue no GitHub ou uma descrição de feature, o agente cria um ambiente de desenvolvimento, implementa, testa, e abre um PR — sem intervenção humana no meio. Os resultados em benchmarks foram impressionantes; os resultados em uso real foram mais nuançados: Devin performa bem em tarefas bem-definidas com requisitos claros, e pior em tarefas que requerem julgamento contextual, conhecimento de domínio profundo, ou decisões arquiteturais.

GitHub Copilot Workspace ocupa o meio do espectro: dado um issue, propõe um plano de implementação que o engenheiro pode editar, depois executa o plano. A intervenção humana no plano — antes da execução — é a diferença arquitetural em relação ao Devin. Isso captura muito do ganho de velocidade enquanto mantém o engenheiro no loop para as decisões de design.

O espectro vai de autocomplete passivo (Copilot tab completion) até agente totalmente autônomo (Devin). O ponto correto no espectro depende da tarefa: autonomia alta para tarefas mecânicas e bem-definidas, aprovação humana para decisões de design, controle total para arquitetura e código de segurança crítica. Usar o mesmo nível de autonomia para todas as tarefas — sempre totalmente autônomo ou sempre aprovando cada keystroke — é sub-otimizar em alguma direção.

Como praticar

1. Criar um CLAUDE.md para o projeto atual. Documente as convenções que um novo engenheiro precisaria saber: estrutura de pastas, padrões de código, como rodar testes, restrições importantes. Use o CLAUDE.md por uma semana e observe quantas vezes você teria precisado repetir essa informação nas instruções sem ele. O arquivo cresce organicamente com cada convenção que você percebe que está faltando.
2. Exercício de delegação controlada. Escolha uma tarefa de complexidade média — um endpoint novo seguindo padrão existente, um conjunto de testes para código sem cobertura — e delegue completamente ao agente com instrução bem escrita. Não intervenha durante a execução. Ao final, faça code review rigoroso do output: o que o agente fez bem, o que errou, o que precisou de correção. Documente o padrão de instrução que produziu o melhor resultado.
3. Mapeamento de tarefas por nível de autonomia. Liste as dez tarefas de engenharia mais comuns no seu trabalho atual. Para cada uma, decida: delegação completa, aprovação por passo, ou controle total. Justifique cada decisão com base no risco, na definição da tarefa, e no conhecimento de domínio necessário. Esse mapeamento guia o uso produtivo de agentes sem precisar tomar a decisão de autonomia na hora em que a tarefa aparece.