DEV Community: Wallace Laia

Spend Intelligence Where the Work Is Uncertain

Wallace Laia — Wed, 15 Jul 2026 12:58:58 +0000

The context window is not an execution engine

An enterprise agent rarely fails because it cannot produce one good answer. It fails because the work around that answer is messy.

The agent has to search several systems, filter results, follow permissions, call another tool, retain intermediate data, compare documents, retry a failed request, and decide whether the result is complete. Each step adds tool output to the context. Some of that information is essential for reasoning. Much of it is only plumbing.

When all of this orchestration happens through repeated model calls, the context window becomes a temporary database, workflow engine, scratchpad, and decision log at the same time. That is an expensive and fragile design. The model spends attention restating state instead of interpreting it.

A better question is not “How do we make the model do more?” It is “Which parts of this task actually require intelligence?”

Use the model in proportion to the surprise

Large language models are useful when the path is unclear. They can infer intent, weigh tradeoffs, connect information that was not explicitly linked, and adapt when the original plan stops fitting the evidence.

They are less valuable when the next action is already known:

iterate over a set of files;
apply the same filter to every result;
normalize data from different tools;
preserve intermediate output;
retry a request under a defined policy;
branch on a deterministic condition;
join records by an identifier;
write a report to a known location.

Those operations do not disappear when an agent performs them. They move to a different execution layer. Code is usually a better place for repeatable mechanics because it is explicit, testable, inspectable, and able to operate on large outputs without replaying them through the model’s context.

The model should step in when interpretation is needed: which result is relevant, whether two findings describe the same underlying issue, what tradeoff a team should accept, or whether the evidence is sufficient to make a recommendation.

This division of labor is the core design principle: code handles predictable mechanics; the model handles judgment under uncertainty.

A coding harness changes the shape of the problem

The approach described in Glean’s coding harness follows this principle. Instead of asking the model to orchestrate every tool call directly, the model writes code in a sandbox. That code coordinates the workflow, while the filesystem stores complete outputs and intermediate state.

The distinction matters.

Imagine an agent investigating a production incident across a ticketing system, deployment history, service catalog, logs, and ownership data. A naive workflow might return every result to the model after each call. The model then has to remember what it has seen, decide what to keep, and generate the next request repeatedly.

With a coding harness, the agent can write a small program that:

queries each source;
saves raw responses to files;
extracts only fields needed for comparison;
retries failed calls according to policy;
produces an intermediate summary;
asks the model to interpret the compressed, high-signal result.

The raw evidence remains available. The model does not need to carry all of it in active context at every step.

This is not merely an optimization for token usage. It creates a clearer boundary between execution and reasoning. The workflow can be inspected independently from the model’s final interpretation. Intermediate artifacts can be reused, compared, or audited. A long-running task has somewhere to put its state besides a conversation transcript.

The post about Glean’s harness reports 24% fewer tokens per request with the same output quality. That figure belongs to that implementation and should not be treated as a universal benchmark. The more durable lesson is architectural: repeated orchestration has a cost, and moving deterministic work outside the context window can reduce unnecessary model involvement. The original post describes the approach and result.

Not every workflow should become an agent loop

There is a temptation to put a model in the center of every enterprise process. That usually creates a system that is difficult to reason about.

A workflow that can be represented as a deterministic pipeline should remain one. If the input, transformations, validation rules, and outputs are known, ordinary code is easier to operate. An agent becomes useful at the boundaries where the system encounters incomplete information or needs to choose among plausible paths.

For example, consider a repository assessment. The mechanical work includes enumerating files, parsing manifests, building dependency graphs, locating API routes, calculating churn, and identifying references between components. These tasks benefit from reproducible analyzers and explicit artifacts.

The judgment layer is different. Someone must determine whether a dependency boundary reflects a real domain boundary, whether a hotspot is strategically dangerous, whether a migration seam is safe enough, or whether an apparent test suite provides meaningful protection. Those questions require context and interpretation.

Putting both layers inside one opaque agent loop makes it harder to know what happened. Was a conclusion based on a measured property, a tool response, an assumption, or the model’s guess? Separating execution from judgment makes that distinction visible.

Files are more than temporary storage

The filesystem in a coding harness is useful because it gives the agent durable working memory with a simple interface. It can store large responses, generated indexes, transformed datasets, failed attempts, and summaries at different levels of detail.

That changes how context can be managed:

raw material stays available without being repeatedly injected into prompts;
derived artifacts can be regenerated from known inputs;
intermediate state can be inspected after a failure;
separate steps can communicate through explicit files;
the final reasoning prompt can contain only the evidence relevant to the decision.

There is an important operational requirement here: state must be governed. A directory full of undocumented files is not automatically reliable. The workflow should define naming, ownership, retention, provenance, and the relationship between raw and derived artifacts.

The same applies to tool permissions. A sandbox that can search repositories, call internal services, and write files needs narrow credentials and clear boundaries. Moving orchestration into code does not remove security risk; it makes the execution layer more powerful. The harness must make network access, secrets, filesystem scope, and allowed tools explicit.

Design for evidence, not just completion

An agent can produce a plausible answer while hiding a weak process. For enterprise work, completion is not enough. A reviewer needs to know what supports the result and what remains uncertain.

A practical agent workflow should preserve at least four distinctions:

observed facts: directly returned by a tool or found in a source;
derived results: calculated from those facts by a deterministic step;
human-provided context: information supplied by an owner or operator;
model judgment: an interpretation, prioritization, or recommendation.

These categories should not be flattened into one narrative. If a workflow claims that a service owns a business capability, the repository may show code ownership, while the business meaning may still require confirmation. If a migration is described as low risk, the evidence may support the existence of a seam but not the operational impact of cutting it.

The agent should be able to say when the evidence is incomplete. That is a stronger design than forcing a confident answer for every question.

A practical architecture for agentic work

A robust enterprise agent often has five layers:

Connectors retrieve information from approved systems.
Deterministic processors filter, parse, normalize, calculate, and validate.
State and artifacts preserve raw inputs, intermediate results, and provenance.
Reasoning steps ask the model to interpret a constrained set of evidence.
Controls enforce permissions, budgets, retries, review gates, and audit trails.

The model may still write the orchestration code. But the surrounding system should treat that code as an executable artifact, not as an invisible side effect of a conversation.

Before introducing an agent loop, classify each step. Ask:

Is the operation repeatable with the same inputs?
Can it be expressed as a deterministic transformation?
Does it need semantic interpretation, or only extraction?
What evidence must survive for a reviewer?
What happens when a tool returns incomplete or contradictory data?
Can the step run without exposing all prior output to the model?

This classification usually reveals where intelligence is being overspent.

From execution to accountable decisions

The most useful enterprise agents will not be the ones that place a model in every step. They will be the ones that know where the model adds value and where it introduces unnecessary variability.

That means building workflows in which mechanical execution is explicit, state is durable, evidence is traceable, and uncertainty is allowed to remain visible. The model then receives a smaller but more meaningful slice of the problem: the part where context, tradeoffs, and judgment matter.

This principle also applies to software architecture work. ArchGenerator follows a related discipline in its architecture reports and SDD kits: repository findings are tied to concrete evidence, assumptions are labeled, and missing information is not presented as certainty. The point is not to replace engineering judgment, but to give that judgment a cleaner foundation before work begins.

Whether the execution layer is a coding harness, a build pipeline, or an architecture analysis workflow, the design question is the same: let predictable work run predictably, and reserve intelligence for the moments that contain real surprise.

Eficiência de contexto: como reduzir o custo real de agentes de código

Wallace Laia — Wed, 15 Jul 2026 12:47:49 +0000

Um agente de código recebe uma tarefa simples: alterar uma regra de validação em um serviço. Em vez de ler o módulo responsável, suas dependências diretas e os testes relacionados, a ferramenta despeja no contexto arquivos inteiros, configurações, documentação antiga e trechos de módulos que não participam daquela decisão.

O resultado pode até funcionar. Mas há uma conta escondida: o modelo processou informação que não precisava, o time pagou por ela e a resposta ficou mais difícil de revisar. Quando o preço acompanha o consumo, contexto mal selecionado deixa de ser apenas uma ineficiência técnica. Ele vira uma decisão de orçamento.

Relatos publicados após a adoção de cobrança baseada em uso do GitHub Copilot descreveram aumentos expressivos em fluxos agentivos, incluindo casos que teriam saído de cerca de US$ 29 para US$ 750 ou de US$ 50 para US$ 3.000 mensais conforme a reportagem. Os valores relatados não formam uma métrica universal de custo, mas expõem o problema: quando a unidade de cobrança muda, desperdício de contexto aparece no extrato.

O problema não é só o modelo escolhido

A reação mais imediata costuma ser trocar o modelo. Um modelo menor pode custar menos por token; um modelo maior pode resolver tarefas difíceis com menos tentativas. Em alguns ambientes, equipes também adotam roteamento: tarefas simples vão para modelos menores e casos ambíguos são escalados.

Essas estratégias são úteis, mas não corrigem a causa principal quando o agente recebe informação demais. Um modelo caro, alimentado por um repositório inteiro para modificar uma função, continua sendo uma solução cara. Um modelo barato, submetido a contexto irrelevante, pode gastar tokens em hipóteses que nunca precisaria considerar.

O ponto central é outro: o agente precisa receber o contexto necessário para tomar a decisão, não o máximo de contexto disponível.

Essa diferença parece óbvia, mas muda a forma de construir ferramentas de desenvolvimento assistido por IA. O repositório não é um prompt. É um sistema com fronteiras, dependências, contratos, convenções e histórico. O trabalho da ferramenta não deveria ser simplesmente copiar arquivos; deveria ser selecionar evidências.

Contexto bruto não é contexto útil

Considere uma solicitação para adicionar uma política de retry a um cliente HTTP. O arquivo do cliente é necessário, mas provavelmente não é suficiente. Também podem importar:

o contrato da interface usada pelo cliente;
os adapters que implementam esse contrato;
os testes de timeout e tratamento de erro;
a configuração de observabilidade;
as regras existentes para circuit breaker;
os consumidores que dependem da semântica atual.

Ao mesmo tempo, não é necessariamente útil enviar todos os handlers da aplicação, o histórico completo do repositório ou cada arquivo de configuração. Esses itens podem aumentar a superfície de busca sem melhorar a decisão.

Contexto relevante tem pelo menos três dimensões:

Dados: quais entidades, endpoints, tabelas ou eventos participam da mudança.
Dependências: quais módulos chamam, implementam ou são afetados pelo componente alterado.
Intenção: qual comportamento deve mudar, quais invariantes precisam permanecer e como o resultado será verificado.

A terceira dimensão é frequentemente esquecida. Um agente pode encontrar o código correto e ainda produzir uma alteração errada se não souber o motivo da mudança. “Adicionar cache” é uma instrução incompleta. Cache de quê? Com qual validade? O que acontece depois de uma atualização? Qual dado não pode ser servido fora da fronteira do usuário?

Sem intenção, a ferramenta tende a inferir. E inferência é uma fonte de retrabalho, especialmente em sistemas legados onde o comportamento real está distribuído entre código, configuração e operação.

Menos tokens não significa menos rigor

Reduzir contexto não é cortar informação de forma cega. É aumentar a densidade de informação útil.

Uma solicitação eficiente pode incluir o arquivo-alvo, as interfaces relacionadas, dois testes representativos e uma regra explícita de aceitação. Uma solicitação ineficiente pode incluir cinquenta arquivos e nenhuma descrição do comportamento esperado. A primeira é menor e, ao mesmo tempo, mais rigorosa.

O ganho aparece em quatro pontos:

Custo: menos tokens de entrada reduzem o consumo por tarefa, dependendo do modelo e do mecanismo de cobrança.
Foco: o agente passa menos tempo distinguindo sinal de ruído.
Previsibilidade: prompts e resultados ficam mais comparáveis entre execuções.
Revisão: o desenvolvedor consegue entender quais evidências sustentaram a alteração.

Isso também ajuda a evitar uma confusão comum: uma resposta curta não é necessariamente uma resposta eficiente. Se o agente omite uma dependência importante e precisa refazer a tarefa três vezes, o contexto economizado na primeira execução pode custar mais no total.

A métrica útil não é apenas tokens por chamada. É o custo para chegar a uma alteração correta, verificável e pronta para revisão. Esse custo inclui tentativas, correções manuais, execução de testes e tempo humano gasto investigando uma mudança que não tinha premissas claras.

Como curar o contexto de um agente

A curadoria começa antes da chamada ao modelo. Ela deve ser tratada como parte da engenharia do fluxo, não como um detalhe do prompt.

1. Comece pelo comportamento, não pelo arquivo

Descreva a mudança em termos de comportamento observável. Liste o que deve acontecer, o que deve continuar igual e quais casos de erro precisam ser tratados. Só então localize os arquivos que implementam esse comportamento.

Essa ordem evita que o agente confunda o primeiro arquivo encontrado com a fronteira real da mudança.

2. Construa um cone de dependências

Para cada arquivo candidato, examine quem o chama, quais interfaces ele implementa e quais componentes dependem de sua saída. O cone não precisa incluir o repositório inteiro. Deve alcançar as partes que podem invalidar a alteração.

Em mudanças de integração, por exemplo, o cone deve incluir timeout, retry, tratamento de erro e observabilidade. Em mudanças de domínio, pode precisar incluir regras de consistência, eventos publicados e consumidores desses eventos.

3. Envie contratos e invariantes

Uma assinatura de função raramente captura todas as regras de um sistema. Inclua invariantes relevantes: idempotência, autorização, ordenação, compatibilidade de payload, limites de latência ou comportamento diante de falhas.

Quando uma regra não está documentada, isso também é informação. O agente deve poder marcar a lacuna como uma pergunta, em vez de preencher o vazio com uma suposição.

4. Faça o agente provar a mudança

O resultado não deve ser apenas um diff. Peça testes, referências aos arquivos alterados e uma explicação das decisões. Se a ferramenta não encontrou evidência suficiente, o resultado deve registrar essa incerteza.

Esse mecanismo cria uma separação importante entre fato e hipótese. “A interface é usada por três adapters” é uma afirmação verificável. “Este adapter não será afetado” é uma conclusão que precisa de análise. Misturar as duas coisas torna a revisão mais lenta e o risco menos visível.

O que medir no fluxo

A equipe não precisa começar com um painel complexo. Algumas perguntas já revelam desperdício:

Quantos tokens de contexto entram em tarefas de tamanho semelhante?
Quantos arquivos foram enviados, e quantos apareceram no diff final?
Quantas execuções terminam em alteração descartada?
Quantas tarefas precisam de uma segunda rodada por contexto ausente?
Quais tipos de mudança geram mais retrabalho?
O tempo economizado pelo agente supera o tempo de revisão e correção?

Não transforme essas perguntas em metas artificiais. Um contexto pequeno pode ser inadequado para uma migração ampla; um contexto grande pode ser necessário para uma mudança transversal. O objetivo é entender a relação entre contexto, evidência e resultado.

Também vale separar custo de exploração de custo de execução. Uma tarefa agentiva pode gastar tokens para descobrir onde está a regra e depois gastar mais para implementá-la. Um inventário confiável, um grafo de dependências ou um mapa de integração reduzem a necessidade de repetir essa exploração em cada chamada.

Onde uma análise arquitetural ajuda

A eficiência do agente depende da qualidade do mapa que ele usa para navegar. Se o time não sabe quais módulos formam o núcleo, onde estão os hotspots de mudança ou quais integrações possuem tratamento de erro frágil, a ferramenta terá de descobrir isso de maneira repetida e cara.

É nesse ponto que uma análise arquitetural pode somar ao fluxo de desenvolvimento assistido por IA. Um diagnóstico baseado no repositório pode fornecer evidências sobre dependências, fronteiras, seams legados, superfície de API, hotspots e saúde dos testes. Esses artefatos não substituem a decisão do desenvolvedor, mas ajudam a montar um contexto menor e mais confiável para cada tarefa.

O ArchGenerator segue essa lógica: conecta-se ao repositório e apresenta achados com evidência de arquivo e linha; quando não há dado suficiente, declara o resultado inconclusivo. A partir do diagnóstico, também é possível gerar um kit SDD com especificações, contratos, prioridades e sensores de progresso para orientar a execução. O valor, nesse cenário, não está em entregar mais texto ao agente, mas em entregar contexto rastreável.

Eficiência é uma disciplina de engenharia

A cobrança por consumo apenas torna visível um problema que já existia. Contexto excessivo sempre teve custo: respostas menos focadas, revisões mais difíceis, maior chance de alteração fora da fronteira e mais tempo gasto corrigindo interpretações.

A solução não é escolher entre modelos grandes e pequenos como se essa fosse a única variável. É construir um fluxo que saiba localizar a mudança, selecionar dependências, declarar intenção, preservar invariantes e exigir evidência do resultado.

Agentes de código funcionam melhor quando recebem um mapa, não um depósito de arquivos. Para o time, isso significa tratar contexto como um artefato curado: limitado o suficiente para ser eficiente, completo o suficiente para sustentar a decisão e rastreável o suficiente para ser revisado. Quando essa disciplina existe, economizar tokens deixa de ser uma otimização financeira isolada e passa a melhorar a qualidade do próprio desenvolvimento.