Meus 2 centavos sobre desenvolvimento agêntico

Em algum momento no início de 2026, percebi que estava escrevendo código por hábito, não por necessidade.

Não chegou como uma decisão. Em 2025, comecei a testar de verdade o que o Copilot entregava: era bom, mas ainda não era confiável para features inteiras. Aí, no início de 2026, com o lançamento do Claude Opus 4.6, a chave virou. Com quase nenhuma configuração extra, a qualidade era absurda. Foi então que parei de racionalizar e fui entender como devs de alto nível estavam usando isso de verdade.

Hoje, cerca de 99% do código que entra nas minhas PRs foi escrito por um agente. O que mudou não foi só a quantidade, foi o que eu faço com o tempo que sobrou.

Aqui estão algumas coisas que aprendi nesse processo.

O agente não precisa fazer tudo na mão

Algumas ferramentas já existiam antes da IA e economizam tempo e tokens simplesmente se você ensinar agente a usá-las.

A CLI do shadcn é um exemplo direto: é comum ver agentes reescrevendo componentes na mão sem necessidade. Uma instrução no CLAUDE.md já resolve:

## componentes UI
Sempre use a CLI do shadcn para adicionar componentes, nunca recrie manualmente:

npx shadcn@latest add [nome-do-componente]

E vale a distinção: scaffolding não é a mesma coisa que lib externa. É muito mais barato para o agente entender código que já está no projeto do que buscar documentação na web.

Linters também. Abuse deles. Quando o agente usa uma ferramenta de lint, ele consegue corrigir erros antes mesmo de abrir a PR e rodar o CI.

Testes automatizados: ninguém mais tem desculpa para postergar. Agentes escrevem testes rápido e os rodam sempre que terminam a implementação.

Ferramentas de qualidade como o SonarQube: sempre foram úteis, são mais ainda agora. O agente vai implementar o que for recomendado, sem dar bypass por preguiça.

Com isso junto, a PR chega muito mais pronta para revisar. Mais tempo e paz de espírito na hora do approve.

Boa arquitetura nunca foi tão importante

Aquela ideia de que a documentação precisa ser o próprio código é mais atual do que nunca.

Código espaguete impacta tanto em qualidade quanto em custo quando você trabalha com agentes. Assim como um dev humano chegando num projeto novo, quando o agente tem clareza sobre onde buscar contexto, ele é muito mais assertivo sobre o que precisa ser feito e consome muito menos tokens no processo.

Isso me fez rever minha stack de backend. Trabalhei por anos com Nest.js pela arquitetura bem estruturada que oferece para times mais sênior. Decorators, injeção de dependência, inversão de controle: tudo isso tem benefícios reais para humanos. Mas para desenvolvimento agêntico, a indireção que esse “código mágico” traz pode confundir os modelos e fazer com que carreguem mais contexto do que o necessário.

Tem outro problema. O ecossistema JavaScript tem o hábito de usar libs para tudo. Isso ajudava muito quando escrever código era o gargalo. Mas é muito comum agentes escreverem código baseado em versões desatualizadas de uma lib, o que gera retrabalho e força você a carregar documentação da versão nova toda vez.

Por isso tenho migrado o backend para Go. A arquitetura padrão é explícita. A comunidade não tem o hábito de depender de libs externas. E as bibliotecas da própria linguagem têm ótima retrocompatibilidade. O mesmo serviço, nos dois contextos:

// NestJS — para entender esse código, o agente precisa carregar
// o decorator, o módulo onde UserService está registrado,
// a config do TypeORM e o que Repository<User> faz internamente
@Injectable()
export class UserService {
  constructor(
    @InjectRepository(User)
    private readonly userRepo: Repository<User>,
  ) {}

  async findById(id: string): Promise<User | null> {
    return this.userRepo.findOneBy({ id });
  }
}

// Go — tudo que o agente precisa está aqui
type UserService struct {
    db *sql.DB
}

func (s *UserService) FindById(ctx context.Context, id string) (*User, error) {
    var u User
    err := s.db.QueryRowContext(ctx,
        "SELECT id, name, email FROM users WHERE id = $1", id,
    ).Scan(&u.ID, &u.Name, &u.Email)
    return &u, err
}

Spec driven development

Desenvolvimento orientado a especificação é realmente eficaz, mas tem ressalvas.

Frameworks como Spec Kit e BMAD ajudam a garantir que requisitos e tarefas de implementação estejam bem escritos e contextualizados, incluindo rodadas de cobertura de edge cases. Mas tudo isso tem custo: tempo e tokens. Essas ferramentas carregam vários arquivos de instrução próprios e forçam o agente a olhar outros tantos antes de começar.

Você precisa decidir se esse fluxo faz sentido para mudar a cor de um botão.

Na minha experiência, eles brilham quando você precisa criar um módulo inteiro, especialmente quando a implementação pode exigir refatoração crítica. Para tarefas menores, um prompt bem escrito já é suficiente, desde que a arquitetura do projeto esteja em ordem.

Skills são algoritmos para agentes

Skills são basicamente algoritmos para agentes. Elas garantem que tarefas recorrentes tenham resultado consistente.

Você pode criar skills que se encaixam exatamente no seu workflow: criação de projetos do zero com sua stack favorita, padrão de mensagens de commit, descrição de PRs, integrações com terceiros, geração de relatórios. A criatividade é o limite.

O ponto de atenção é gerenciar quais skills ficam disponíveis. Não faz sentido carregar tudo toda vez que você abrir o chat. O que me leva para o próximo ponto.

Muito contexto pode ser pior

Saber quanto detalhe colocar nos arquivos guia, como CLAUDE.md, AGENT.md e afins, é extremamente importante.

Pense nesses arquivos como índices, não como documentação completa. O agente precisa abri-los e saber onde procurar o que precisa para a tarefa atual, sem precisar carregar as definições de design toda vez que for criar um endpoint.

# ❌ CLAUDE.md sobrecarregado

## Sobre o projeto
Plataforma de gestão financeira. Usamos Next.js 15, Tailwind v4...
[300 linhas de contexto que o agente vai carregar em toda sessão]

## Design system
As cores primárias são #1F3A36 e #F5F0E8. Nunca use vermelho puro...
[mais 150 linhas]

## Padrões de código
Sempre use async/await, nunca .then(). Prefira funções puras...
[mais 200 linhas]

# ✅ CLAUDE.md como índice

Plataforma de gestão financeira em Next.js 15.

- Arquitetura: @docs/architecture.md
- Design system: @docs/design-system.md
- Padrões de código: @docs/code-standards.md
- Skills disponíveis: @.claude/skills/

A diferença prática: no segundo, o agente carrega só o que é relevante para a tarefa atual.

Você ainda é o autor

Usar agentes não te libera da responsabilidade pelo código que vai ao ar.

O agente é uma ferramenta que escreve código. Você continua sendo o autor de cada linha entregue. Isso significa que não dá para aceitar código do qual você não tenha clareza sobre o que foi feito e, principalmente, sobre as tecnologias envolvidas.

É muito fácil aprovar uma PR onde o agente decidiu usar MongoDB sendo que você sempre usou SQL. Se você não conhece os trade-offs dessa decisão, não tem como prever os problemas que essa escolha pode causar na sua stack. Essa é a diferença entre vibe coding e desenvolvimento agêntico de verdade.

Janelas de contexto

Quando vale a pena fechar uma janela e abrir outra do zero?

Na minha experiência, só vale quando o assunto muda completamente. Se você trabalhou no módulo de pagamento e agora vai para a landing page, abrir uma janela nova faz sentido. Se ainda está no mesmo módulo, continue na atual: o agente já carregou o contexto relevante e vai precisar de menos esforço para continuar.

Se precisar limpar sem perder o fio, use /compact.