A programação agêntica está a mudar a velocidades sem precedentes, mesmo para os padrões do mundo tecnológico. Os tutoriais e recursos disponíveis online cobrem principalmente funcionalidades individuais em cenários simples de raiz.

Durante a construção do Bob e ao interagir com inúmeros profissionais no campo, de uma vasta gama de indústrias, emergiu um conjunto de conceitos que ajudam a melhorar a eficácia e a experiência de utilização do Bob.

Esses conceitos aplicam-se também a projetos complexos que usam tecnologias menos comuns.

Conceito 1: O ciclo — explorar, planear, implementar, verificar

O ciclo explorar, planear, implementar, verificar, com um ciclo exterior para melhoria contínua de guias e sensores

O modo de falha mais comum na Engenharia de Software agêntica é a ausência de estrutura. A coerência conversacional imita a estrutura e ficamos tentados a condensar todos os passos de uma implementação numa única conversa. As sessões parecem produtivas, mas o custo só fica visível na revisão.

Escrever código à mão impunha uma estrutura própria. A implementação era cara, por isso planear antes de implementar parecia intuitivamente razoável. A compreensão acumulava-se enquanto se escrevia, e as suposições erradas tendiam a surgir durante esse processo. Os agentes de IA removem esse atrito. O código é barato agora, e isso também eliminou a nossa intuição para a estrutura. A estrutura que antes era um subproduto da lentidão agora tem de ser deliberada.

Usar este ciclo de forma deliberada pode fornecer essa estrutura:

Explorar produz compreensão
Planear produz decisões
Implementar produz código
Verificar produz evidências.

Seguir este ciclo ajuda-te a manteres-te focado, estruturado e a atingir os teus objetivos de forma mais rápida e consistente.

Uma única passagem pelo ciclo pode demorar vinte minutos ou três dias. Uma passagem pode conter sub-ciclos, e a forma como o tempo se divide entre as fases varia muito consoante a tarefa.

Um percurso detalhado pelo ciclo pode ser encontrado abaixo em Mergulho Fundo: Executar o Ciclo.

Conceito 2: A janela de contexto é o recurso escasso

Ser deliberado em relação à janela de contexto é o hábito com maior retorno.

O que é a janela de contexto?

Os modelos são stateless. Um chat não é uma sessão em execução com memória: cada turno reenvia todas as mensagens anteriores e acrescenta a nova resposta ao fim. A janela de contexto é a quantidade máxima de input que um modelo consegue aceitar num desses turnos. No Bob V2 são 270k tokens (gestão da janela de contexto).

A janela começa a encher antes da primeira mensagem:

Carregado à partida: o system prompt do Bob, a descrição do modo ativo, o agents.md do repositório, e uma descrição de cada ferramenta do Model Context Protocol (MCP) ligada (MCP no Bob).
Adicionado durante a sessão, de forma invisível: leituras de ficheiros, resultados de ferramentas, ficheiros de skills que o Bob carrega, output de subagentes.

A janela de contexto enche e é compactada num resumo

Quando a janela fica cheia, o Bob compacta a conversa. O Bob substitui a conversa até ao momento por um resumo, e o trabalho continua. Isso mantém a sessão ativa, e é lossy por design. O Bob decide automaticamente quais os detalhes que sobrevivem, e nada assinala os que não sobrevivem. Uma sessão que foi compactada duas vezes está a correr com base no resumo de um resumo.

Uma única chamada MCP pode devolver dezenas de milhares de tokens, e uma sequência de leituras de ficheiros dilui o que foi discutido antes na sessão. Descrições de modo, ficheiros de regras e servidores MCP fazem-no de forma mais lenta e menos visível. O Bob decompõe a janela por origem, e vale a pena abrir essa análise à medida que a configuração cresce.

O indicador da janela de contexto do Bob, expandido para mostrar a sessão atual dividida por origem

Os Bobcoins são calculados principalmente por token. Portanto, o custo de uma conversa cresce de forma quadrática em relação ao seu comprimento. Conversas mais longas custam muito mais Bobcoins do que conversas curtas! (documentação de Bobcoins)

Trabalha com a janela de contexto, não contra ela

Divide o trabalho em conversas separadas. Uma tarefa, uma sessão. É o mesmo raciocínio da responsabilidade única no código. Uma conversa deve ter uma razão de existir, como "desenhar um diagrama de arquitetura do componente X" ou "criar um plano de implementação para a funcionalidade Y." Tudo o que está na janela de contexto influencia o que vem a seguir, incluindo as abordagens que não funcionaram. Uma sessão que ficou bloqueada tende a continuar bloqueada, porque as tentativas falhadas ainda estão lá, e o modelo lê-as como evidência sobre o que esta tarefa parece ser (context poisoning).
Faz rollback em vez de discutir com o Bob. Quando uma conversa deriva para um comportamento indesejado, faz rollback para a última mensagem boa, altera a mensagem e continua a partir daí. Isso também desfaz todas as alterações que o Bob fez localmente, o que mantém a janela de contexto pequena e limpa (rollback).
Guarda tudo o que vale a pena guardar num ficheiro, não no chat. Planos, descobertas e decisões pertencem a um ficheiro. Um colega pode rever um documento markdown e passá-lo a uma sessão nova; um log de chat não faz nenhuma das coisas.
Os subagentes mantêm o trabalho volumoso fora da janela de contexto. O Bob decide quando executar um, e só as descobertas voltam. Pedir um diretamente também funciona, quando uma tarefa vai produzir output que ninguém precisa de ler (subagents).
Tem atenção ao que vai para a janela de contexto e se acrescenta valor. Verifica os teus guias e sensores regularmente, como abordado no tópico seguinte, e investe tempo a melhorá-los.

Conceito 3: Dois tipos de blocos de construção — guias e sensores

Ao longo de um projeto longo, se a base de código melhora ou piora tem menos a ver com o Bob do que com o que molda o seu trabalho e verifica o seu output. Existem muitos blocos de construção disponíveis: rules, skills, modes, hooks, subagentes, linters externos e agentes de revisão. Quase todos fazem um de dois trabalhos.

Os guias orientam o Bob antes ou enquanto trabalha (Feedforward). Rules, skills e modes são todos guias.
Os sensores reportam depois de o Bob ter agido (Feedback). Testes, linters, verificadores de tipos, sessões interativas de browser e agentes de revisão são todos sensores.

Uma pessoa num portátil aponta uma seta para o Bob, e o Bob aponta uma seta para o código. Uma seta com a etiqueta "guias" entra no Bob por cima, anotada com rules, skills e modes. Uma seta com a etiqueta "sensores" vai do código de volta para o Bob, anotada com testes, linters e agentes de revisão.

1. Guias

Tudo o que é fornecido ao Bob para orientar o trabalho é um guia. Existem três blocos de construção principais que te ajudam com isso, e funcionam colocando texto na janela de contexto adicionalmente ao prompt que escreveste. Diferem em quando esse texto chega e o que o despoleta.

As rules estão sempre ativas, os modes são ativados pelo utilizador, as skills são ativadas pelo Bob

Rules estão sempre ativas. agents.md na raiz do repositório é a principal, e o principal conselho é mantê-la curta. Cada linha compete pela atenção em cada turno, por isso um ficheiro de rules longo torna o Bob pior a seguir qualquer rule individual nele (rules).
Modes são ativados pelo utilizador. Os modes integrados são: Ask é só de leitura. Plan trabalha através de um processo de planeamento e passa o resultado ao Agent, que toma ação. Modes personalizados podem ser adicionados facilmente (modes, adicionar um mode personalizado).
Skills são ativadas pelo Bob quando ele as considera relevantes. Apenas uma pequena descrição da skill está sempre ativa. O corpo principal da skill só é carregado no contexto a pedido. Isso torna as skills muito eficientes em termos de tokens (skills).

Tudo o que está no ficheiro de rules usa tokens em cada turno, quer esse turno precisasse ou não, por isso mantém-no mínimo e deixa o resto esperar até ser aplicável.

2. Sensores

Tudo o que dá ao Bob feedback sobre o trabalho produzido é um sensor. Quais os sinais que são úteis depende da base de código e da stack, por isso o conjunto que vale a pena ter difere de projeto para projeto e requer trabalho real para ser montado. Os sensores mais valiosos são executáveis por máquina e executados pelo Bob durante a fase de implementação. Os sensores podem ser divididos em duas categorias distintas.

Sensores computacionais são determinísticos: testes, linters, verificadores de tipos, compiladores. Os veredictos são exatos e repetíveis, baratos o suficiente para o Bob os executar frequentemente. A cobertura é limitada pelos sistemas que uma equipa construiu e mantém.
Sensores baseados em IA são flexíveis e não-determinísticos. Um agente de revisão lê para a intenção, e para as coisas para as quais um linter não tem regra. O output é julgamento, não medição. Varia entre execuções, e o custo e a duração limitam a frequência com que pode ser usado (code reviews).

Integrá-los tem várias opções, por ordem aproximada de fricção:

Hooks são a opção determinística de menor fricção. Uma verificação corre num ponto fixo, sempre, quer o Bob achasse relevante ou não. Vê a documentação de hooks.
Skills são frequentemente usadas como guias, mas uma skill que executa uma revisão é um sensor, e é a forma de menor fricção para adicionar uma verificação não-determinística. Vê a documentação de skills.
Integração contínua (CI) coloca um agente de revisão no pipeline, em cada pull request, para toda a equipa e não apenas para um developer. Vê o agente de revisão de PR em ação.

Mergulho Fundo: Executar o Ciclo

Os limites de fase são também limites de contexto, o que é a razão prática para os manter distintos: o chatter de exploração não tem nada a ver com a conversa onde o código é escrito.

1. Explorar

A exploração varia muito dependendo do teu papel e da tarefa em questão. Pode significar integrar uma nova base de código ou estimar o raio de impacto de uma grande refatorização. Alguns exemplos:

Pede ao Bob para produzir um diagrama de arquitetura do sistema existente antes de alterar qualquer coisa. Vê o tutorial de geração de diagramas de arquitetura, ou o mesmo em vídeo.
Pede um guia de introdução personalizado de dois ângulos, uma vez como utilizador a percorrer o produto e outra vez como developer a percorrer o código. Fornecer informações sobre a tua experiência e tarefa ajuda a personalizar o documento (inspecionar uma base de código).
No IBM Z e IBM i, usa as opções específicas da plataforma. O problema de exploração nesses sistemas é diferente e beneficia muito das ferramentas especializadas fornecidas nos pacotes premium. Vê o Premium Package for Z (docs) e o Premium Package for IBM i (docs).

A exploração pode também incluir construir coisas que pretendes eliminar. A implementação é barata agora, por isso um protótipo estreito é a forma mais rápida de descobrir se uma abordagem sobrevive ao contacto com a base de código. Kent Beck chamou a isto uma spike implementation há vinte e cinco anos, e a disciplina é a mesma: constrói para aprender algo, guarda a aprendizagem, descarta o código.

A implementação barata aumenta o valor da arquitetura e da qualidade do código em vez de o diminuir. Agora é fácil produzir uma grande quantidade de código que funciona e está errado.

2. Planear

A fase de planeamento é onde está a maior alavancagem. Tudo o que o plano acerta paga-se duas vezes: uma na implementação, e outra quando a alteração sai das mãos do autor e um colega tem de a rever.

O que um bom plano necessita:

Curto e preciso, ambos. Os planos precisam de ser lidos.
Explícito sobre o resultado pretendido, incluindo as partes incertas. Saber o que é desconhecido é a maior parte do trabalho, e descobrir é o resto.
Num ficheiro. Os planos não devem viver numa sessão de chat.

Há muitas formas de criar um plano, mas o Plan mode integrado é o ponto de partida mais fácil (como neste tutorial). O Plan Mode foi construído para ser concordante e tende a preencher as lacunas. Embora isso possibilite iterações rápidas em muitos casos, por vezes é necessário mais rigor. Pode construir um plano competente em torno de uma má suposição sem questionar a suposição. Uma skill dedicada que discute o plano — grill-me de Matt Pocock, por exemplo — é a forma mais barata de obter escrutínio antes que a suposição se torne código.

Sobre o desenvolvimento orientado a especificações (SDD). O termo cobre muito terreno e ainda está em fluxo. As pessoas tratam-no como uma decisão de sim ou não, mas está mais próximo de um espectro:

Spec-first: o plano vem antes da implementação. Isto está perto de ser inegociável.
Spec-anchored: a spec permanece após a implementação, como documentação e como padrão que as implementações devem cumprir.
Spec-as-source: a spec é o ficheiro fonte. O humano edita a spec; o humano não edita o código.

Qual o nível adequado depende da equipa, da criticidade/maturidade da base de código e da indústria. A sobrecarga dos níveis mais elevados de SDD pode ser dolorosa para iteração rápida. No setor automóvel, onde o desenvolvimento orientado a especificações precede a IA por décadas, o SDD encaixa muito bem na prática existente.

3. Implementar

A implementação é a fase direta, e o Bob trata de quase tudo.

Observar o Bob a trabalhar e interromper para clarificar é opcional e muitas vezes útil. Trata a frequência como um sinal: interrupção constante significa que o problema está no plano, e a correção é voltar atrás em vez de continuar a corrigir.

Não hesites em descartar uma implementação inteira e voltar ao Plan mode. O código é a parte barata.

4. Verificar

A verificação cai em duas categorias distintas: verificação automatizada e verificação manual.

A verificação automatizada é conduzida pelos sensores que o Bob tem disponíveis ou que são impostos via hooks. São executados frequentemente durante a fase de implementação sem intervenção humana. As principais categorias com alguns exemplos comuns são:

Validade: Compila, faz typecheck, faz parse?
- Medido: pass/fail, cobertura de tipos
- Ferramentas: tsc, mypy, cargo check, javac
Comportamento: Faz a coisa certa?
- Medido: taxa de sucesso, cobertura de branches
- Testes unitários, Testes de integração, Testes end-to-end
- Ferramentas: pytest, Jest, Playwright, Stryker
Manutenibilidade: Vale a pena manter este código?
- Medido: complexidade, duplicação, violações de fronteira
- Ferramentas: ESLint, Ruff, Lizard, ArchUnit
Segurança: Este código é seguro?
- Medido: findings por severidade, CVEs
- Ferramentas: Semgrep, CodeQL, gitleaks, npm audit

Permitem que o Bob detete os seus próprios erros e melhore a qualidade durante a fase de implementação. Uma boa cobertura de testes é proteção essencial contra regressões: garante que o Bob não quebrou nada.

Neste ciclo, a verificação é listada como uma fase separada no final do loop, o que se refere principalmente à verificação manual. A verificação manual começa por executar a alteração e comparar o comportamento observado com o comportamento que o plano especificou. Uma discrepância estreita-se principalmente a uma de duas causas:

A implementação desviou-se do plano. A correção está no código.
O plano não reflete o que pretendias construir. O plano precisa de ser refinado. Isto é muito mais comum.

A inspeção manual testa portanto o plano e a implementação ao mesmo tempo.

Verificação adicional deve acontecer nos pipelines de CI/CD. Esta é uma prática bem estabelecida em engenharia de software, mas pode ser melhorada usando agentes de codificação headless. Um exemplo: uma revisão automatizada em cada pull request, a correr através do Bob Shell, aumenta os revisores humanos em vez de os substituir. Vê o vídeo do agente de revisão de PR em ação e a documentação para executar o Bob Shell de forma não interativa.

Trabalhar em equipa

Tudo nas secções anteriores descreve o ciclo interno de um developer. O ciclo externo começa quando as alterações entram na fila de revisão. Cada diff chega agora mais rápido e com menos do seu raciocínio anexo, enquanto o revisor tem mais para ler e menos contexto em que ler.

A evidência tem de viajar com o trabalho. O porquê importa mais do que antes, relativamente ao como, porque o como já não é a parte cara de produzir.

Na prática, isto significa que o plano viaja com a alteração: as equipas anexam-no ao pull request ou adicionam-no de volta à issue original juntamente com a revisão. O mecanismo depende das ferramentas.

O que o ciclo externo faz ao processo de uma equipa é um assunto em si próprio, e será tema de um post futuro.

Algumas reflexões sobre prompting

Nos últimos anos, houve uma grande ênfase em fazer prompting correto aos LLMs, com uma categoria de trabalho inteira como "prompt engineer" a emergir disso. Neste momento, muito do prompting é tratado dentro do harness. A importância de técnicas especializadas de prompting diminuiu a favor de uma abordagem metodológica. Aqui ficam algumas diretrizes:

Iterar supera o prompting. Quando o Bob faz algo diferente do que pediste, faz rollback e reescreve a mensagem que o causou. Corrigir para a frente deixa a resposta errada, a queixa sobre ela e a nova tentativa todas na janela.
A metodologia supera o prompting. Um prompt tem scope para uma sessão. Um ficheiro de rules, ou uma verificação que o Bob pode executar por si próprio, continua a funcionar em cada sessão após aquela que o produziu, que é o único tipo de investimento aqui que acumula.
Dá ao Bob o briefing que um engenheiro sénior receberia. Um colega competente com uma tarefa vaga perguntará o que conta como feito e o que pode tocar; o Bob não perguntará, por isso inclui ambos na mensagem.
Diz o que fazer, não o que não fazer. "Não uses class components" descarta uma opção e deixa o resto do espaço aberto, por isso o Bob escolhe do que resta, que é outro palpite. Nomear o alvo em vez disso — function components com hooks — fecha-o numa única volta.
Qualquer instrução dada mais de duas vezes pertence a um ficheiro. É para isso que servem o agents.md e as skills.
Instruções de prompting mais detalhadas podem ser encontradas no tutorial de escrita de prompts eficazes.

Principais conclusões

A ausência de estrutura é o maior problema. Seguir o ciclo Explorar → Planear → Implementar → Verificar ajuda-te a manteres-te focado e a atingir os teus objetivos de forma mais rápida e consistente.
O contexto é o recurso escasso, e as fases são limites de contexto. Não tragas o chatter de exploração para a implementação.
O plano é o artefacto de revisão. Rever um plano supera rever um diff, para o autor e para o revisor.
Tudo o que vale a pena guardar sai do chat. Planos, decisões e descobertas pertencem a um ficheiro. Podes fazer diff, rever, versionar e passar um ficheiro a outro agente.
A verificação deve ser executável por máquina, o que significa que tens de a conceber durante o planeamento, não descobri-la depois.

Fontes e leitura adicional

Simon Willison, Agentic engineering patterns
Birgitta Böckeler, Harness engineering

Documentação e tutoriais do IBM Bob: