Abra um repositório seis meses depois que uma funcionalidade foi lançada e você conseguirá reconstruir muita coisa. Dá para rastrear a arquitetura, inspecionar o esquema, ler os testes e ver exatamente quais linhas mudaram.
O que normalmente não dá para reconstruir é a conversa que tornou essas linhas necessárias.
O código não vai dizer que uma regra de validação existe porque um cliente envia exportações malformadas. Não vai explicar que uma política de retry estranha evita transações duplicadas em um sistema downstream. Não vai mostrar que a interface mais limpa foi rejeitada depois de um teste de acessibilidade, nem que um limite entre serviços reflete uma restrição contratual, e não uma preferência de engenharia.
O Git é excelente para preservar o histórico do código. Ele só preserva a intenção quando a equipe registra essa intenção de forma deliberada e a mantém conectada à implementação.
Essa lacuna sempre fez parte da engenharia de software. As ferramentas de codificação com IA a tornam mais visível. Um sistema pode ler todos os arquivos de um repositório, seguir cada símbolo e gerar um patch tecnicamente convincente, mas ainda assim resolver o problema errado.
O problema não é que o código seja enganoso. O código está respondendo a uma pergunta mais estreita.
Cinco camadas da verdade da engenharia
A maioria das mudanças de software que realmente importam depende de cinco camadas diferentes de evidência.
- Intenção — Qual resultado o usuário, cliente ou negócio está pedindo? Isso pode estar em uma especificação, ticket, conversa de suporte ou nota de reunião.
- Restrições — O que não pode quebrar? Promessas de compatibilidade, limites de segurança, regulações, contratos, orçamentos e prazos muitas vezes ficam fora do repositório.
- Implementação — Como o sistema funciona hoje? O código, os testes, os esquemas, as dependências e a configuração de deploy fornecem essa camada.
- Evidência em runtime — O que está acontecendo no sistema real? Logs, traces, métricas, dados de produção e relatórios de incidentes podem contradizer suposições que parecem razoáveis no código.
- Histórico de decisões — Por que a abordagem atual foi escolhida? Pull requests, discussões de design, alternativas rejeitadas e incidentes anteriores trazem a resposta.
O repositório é mais forte na terceira camada. Ele contém partes das outras, mas raramente o suficiente para representá-las por completo.
Isso importa porque falhas de software costumam aparecer nas fronteiras entre as camadas. A implementação corresponde a uma especificação desatualizada. A correção atende ao ticket, mas viola uma restrição operacional. Os testes passam porque codificam as premissas de ontem. O código é internamente consistente, enquanto os dados de produção seguem um padrão que ninguém documentou.
Um patch localmente correto ainda pode ser a mudança errada.
O que o repositório não consegue responder sozinho
Considere um usuário que edita um documento e depois procura a frase atualizada, apenas para ver a versão antiga nos resultados. “Faça a busca atualizar imediatamente” parece um pedido claro. O repositório revela vários pontos possíveis por onde começar, mas não consegue definir a correção certa por conta própria.
| Pergunta | Fonte provável |
|---|---|
| Qual versão do documento é a fonte de verdade? | Documento de origem e histórico de revisões |
| Onde o texto antigo ainda permanece? | Logs de sincronização, saída da extração, índice de busca ou cache |
| O que “imediatamente” significa para este produto? | Promessa do produto ou objetivo de serviço |
| As permissões do documento mudaram junto com o conteúdo? | Permissões de origem e histórico de auditoria |
| O resultado desatualizado se limita a um usuário, origem ou região? | Rastros de requisição e métricas de produção |
O código de busca pode explicar como os resultados são retornados. Ele não consegue dizer se o defeito real é atraso de sincronização, extração desatualizada, invalidação de cache, propagação de permissões ou uma expectativa que o produto nunca definiu.
Essa distinção se torna ainda mais importante em sistemas maduros. Um campo que parece obsoleto ainda pode dar suporte a um cliente legado. Um serviço que parece duplicado pode separar dados com requisitos de permissão diferentes. Uma verificação aparentemente excessiva pode ser o único vestígio no código de um incidente em produção que a equipe atual nunca viu.
Eliminar complexidade é valioso. Eliminar história disfarçada de complexidade sai caro.
Mais contexto ainda pode produzir a resposta errada
A solução óbvia é dar mais material à IA: o repositório inteiro, todos os tickets, todos os documentos, todas as mensagens e todos os logs.
Isso cria acesso, não entendimento.
As fontes podem estar desatualizadas, ser contraditórias, especulativas ou escritas para públicos diferentes. Um brainstorm não deve ter mais peso do que uma especificação aprovada. Um requisito de seis meses atrás não deve substituir silenciosamente a decisão de produto de ontem. Um log de produção deve estar vinculado à release, ao ambiente e ao caminho de código que o gerou. Uma solicitação de cliente não deve ser tratada como requisito universal sem verificar o escopo.
Um sistema de contexto sério, portanto, precisa de mais do que recuperação. Ele precisa de uma forma de raciocinar sobre:
- Autoridade: Qual fonte tem permissão para definir o requisito?
- Atualidade: Qual informação está vigente, e o que já foi substituído?
- Proveniência: De onde veio cada alegação, restrição ou conclusão?
- Relações: Quais issue, release, cliente, conjunto de dados e caminho de código pertencem ao mesmo contexto?
- Permissões: Quais fontes podem ser usadas para esta tarefa e mostradas a esta pessoa?
Contexto não é uma pilha de tokens. É um grafo com tempo, autoridade e limites.
Mais contexto deve produzir mais evidência, não mais confiança sem evidência.
A verdadeira unidade de trabalho é a mudança
Editores e ferramentas de programação são organizados em torno de arquivos porque arquivos são o que modificamos. Equipes de engenharia são organizadas em torno de mudanças.
Uma mudança começa com um motivo. Ela se transforma em um requisito, afeta código e dados, passa por revisão, chega à produção e cria novas evidências. Se essas etapas permanecerem desconectadas, toda tarefa futura começa com mais uma rodada de arqueologia.
Um sistema de IA que trabalha com software real deve seguir esse ciclo de vida.
Antes da implementação, ele deve identificar a solicitação, as restrições relevantes e quaisquer fontes conflitantes. Deve saber se está corrigindo um defeito, alterando um comportamento esperado ou introduzindo um novo contrato.
Durante a implementação, ele deve conectar cada escolha significativa a evidências. Por que este módulo? Por que esta estratégia de migração? Por que preservar este branch? A explicação deve sobreviver além do chat que produziu o código.
Após a implementação, ele deve anexar os resultados da verificação, as decisões de revisão e as restrições recém-descobertas à mudança. Caso contrário, a próxima pessoa — ou a próxima sessão de IA — terá de redescobri-los.
Essa é a diferença entre uma ferramenta que consegue editar um repositório e um sistema que consegue participar do trabalho de engenharia.
A IA deve reduzir a reconstrução, não eliminar o julgamento
Às vezes, um contexto melhor é apresentado como um caminho para o desenvolvimento autônomo de software. O valor imediato é menos dramático e mais útil: reduzir o custo de reconstruir a realidade antes de fazer uma mudança.
A IA pode trazer o requisito original para junto do código relevante. Pode trazer à tona o incidente que explica uma proteção incomum. Pode conectar uma métrica com falha à release que a alterou. Pode mostrar que duas fontes autorizadas discordam antes de a implementação começar.
Essas capacidades não eliminam o julgamento de engenharia. Elas tornam esse julgamento mais bem informado.
Uma pessoa ainda precisa decidir qual trade-off é aceitável, se um requisito está completo e quanto risco uma release pode carregar. O sistema deve tornar as evidências visíveis e o raciocínio inspecionável. Não deve esconder a incerteza atrás de um patch bem acabado.
O critério não é “ele consegue gerar código?”
O critério é “ele consegue explicar por que esta é a mudança certa agora?”
De consciente do repositório a consciente do trabalho
Os assistentes de programação começaram a se tornar úteis ao entender o arquivo diante do desenvolvedor. A consciência do repositório foi o próximo grande passo: encontrar código relacionado, seguir símbolos e aplicar mudanças em todo um projeto.
O próximo passo é ter consciência do trabalho ao redor do repositório.
Isso significa conectar o código à especificação que o solicitou, à conversa que o esclareceu, à evidência de produção que o contestou e à decisão que deve ser lembrada depois. Também significa excluir o contexto que é irrelevante, desatualizado ou está fora das permissões do usuário.
Ao construir a Dvina, esta é uma das ideias às quais sempre voltamos. O trabalho não acontece dentro de um único arquivo, aplicação ou conversa. O significado vive nas conexões entre eles e em como essas conexões mudam ao longo do tempo.
O repositório continua sendo essencial. Ele é a fonte executável da verdade sobre o comportamento do sistema. Só não é a fonte completa da verdade sobre a intenção do produto, a realidade operacional ou a memória organizacional.
A história completa muda o que é construído
Com apenas o código, a pergunta natural é:
Que mudança se encaixa neste sistema?
Com o contexto mais amplo, a pergunta passa a ser:
Que mudança se encaixa neste sistema, neste requisito, nesta história e neste momento?
Essa segunda pergunta identifica restrições antes que se transformem em regressões. Ela dá aos revisores o raciocínio por trás da implementação. Ajuda novos membros da equipe a entender por que o sistema é como é. E dá à IA um papel fundamentado: não o de um oráculo dentro do editor, mas o de uma participante capaz de reunir evidências de todo o trabalho.
Seu repositório nunca foi a história completa.
A oportunidade está em construir sistemas capazes de ler o restante dela — e mostrar seu trabalho.
