Meu último artigo aqui no blog foi publicado no dia 31 de dezembro de 2025. Desde então, o volume de trabalho tem sido intenso, dividindo meu tempo entre a gestão de produtos e o desenvolvimento de novos projetos, o que me afastou temporariamente da escrita. No entanto, uma observação recente me fez gravar um vídeo rápido no meu Instagram (@guireisbr.dev) e, posteriormente, me trouxe de volta a este espaço para uma reflexão mais profunda. O tema que abordei no vídeo e que detalho agora é uma mudança silenciosa, porém profunda, na forma como grandes e médias empresas de tecnologia estão gerenciando seus times.

As organizações estão exigindo que seus desenvolvedores não apenas escrevam código (seja com o auxílio de inteligência artificial ou não), mas que documentem os sistemas. Sabemos que a cobrança por documentação é antiga e, na prática, frequentemente negligenciada. A diferença, contudo, é que as empresas não estão mais pedindo a documentação do "o que" foi feito. Elas estão exigindo a documentação do "por que" foi feito de determinada maneira. Elas querem o contexto. E isso tem um motivo claro.

A inteligência artificial evoluiu de forma exponencial. O recém-lançado Claude Opus 4.6, por exemplo, demonstra uma capacidade de retenção e processamento de informações consideravelmente superior aos modelos do ano passado (arrisco dizer que sabe vinte vezes mais). Apesar de essas ferramentas terem ingerido quase todo o código público disponível (e talvez muito do privado) para consulta em milissegundos, e de quase sempre encontrarem uma forma de resolver uma demanda técnica, elas ainda apresentam uma falha estrutural.

A IA tem dificuldade em escolher a melhor opção entre dezenas de soluções viáveis para um mesmo problema. Falta a ela o contexto do negócio.
E é exatamente esse contexto que milhares de profissionais estão sendo obrigados a formalizar. A pergunta que fica é: ao entregarmos nosso raciocínio de bandeja, estamos acelerando o fim da nossa profissão?

A Evolução do Código: De 1997 aos Dias Atuais

Para entender o peso dessa mudança, considero útil olhar para o retrovisor. Comecei a programar em 1997, aos 13 anos, escrevendo linhas em COBOL. Naquela época, a preocupação era fazer o sistema compilar e executar a rotina no mainframe dentro da janela de tempo permitida. A documentação, quando existia, era um manual físico para o usuário final, não um registro de decisões arquiteturais.

Com o passar dos anos e minha transição para o desenvolvimento backend com linguagens como Python, Ruby e PHP, a indústria adotou novas práticas. Passamos a documentar APIs, criar fluxogramas de banco de dados e escrever comentários no código para explicar blocos de lógica complexa. O foco sempre esteve no "como". Como este serviço se comunica com aquele banco de dados? Como esta função calcula o imposto?

Como Head de Produto e tendo liderado diversas equipes ao longo dessas mais de duas décadas, acompanhei a transição de perto. A engenharia de software sempre tratou o contexto como uma tradição oral. As decisões críticas (por que não usamos um banco não-relacional aqui, por que ignoramos aquela convenção específica, por que priorizamos tempo de entrega em vez de performance naquele trimestre) viviam na cabeça dos desenvolvedores mais experientes. Eram conhecimentos repassados em reuniões, revisões de código ou conversas de corredor.

O que mudou na exigência corporativa?

O que vemos hoje é a institucionalização do Architecture Decision Record (ADR), ou Registro de Decisão Arquitetural, em uma escala sem precedentes. As empresas perceberam que o código em si tornou-se uma commodity. Se eu precisar de um script em Python para conectar a uma API externa e formatar um JSON, qualquer modelo de linguagem gera isso em três segundos.

No entanto, a IA não sabe responder por que escolhemos estruturar o banco de dados de uma forma que parece ineficiente no papel, mas que contorna um gargalo específico de um sistema legado da empresa. O modelo não sabe que a decisão de usar uma arquitetura de microsserviços não foi puramente técnica, mas política, para acomodar duas equipes que não conseguiam trabalhar no mesmo repositório.

Quando planejei a arquitetura de um projeto SaaS recente voltado para Product Managers (o PM Partner), optei por um backend em Python usando FastAPI, um frontend em Next.js e Supabase para o banco de dados. A IA pode escrever o código para qualquer uma dessas ferramentas. Mas ela não poderia tomar essa decisão por mim. A escolha considerou a minha velocidade pessoal de desenvolvimento em Python, a necessidade de ter uma API performática desde o dia zero e a conveniência de um banco de dados gerenciado que reduzisse minha carga de infraestrutura inicial.

Ao exigir que os desenvolvedores escrevam o "porquê", as empresas estão tentando extrair o último reduto de valor inquestionável do ser humano: o julgamento baseado em restrições do mundo real.

Por que a IA falha no "Porquê"?

O problema central da inteligência artificial atual, mesmo em suas iterações mais avançadas, é que ela opera em um vácuo de consequências. Um modelo de linguagem não é demitido se o sistema sair do ar. Ele não precisa explicar para o conselho de administração por que o custo da infraestrutura na nuvem triplicou no último mês.

A IA tem acesso a todos os padrões de design de software já documentados, mas não tem acesso às idiossincrasias (gastei aqui, hein? rs) do seu ambiente de trabalho. É por isso que ela peca ao escolher entre as soluções. Se você pedir a um modelo para projetar um sistema de mensageria, ele pode sugerir Kafka, RabbitMQ ou SQS. Ele listará os prós e contras técnicos de cada um com precisão. Mas ele não sabe que a sua equipe de infraestrutura tem experiência zero com Kafka, que o orçamento do projeto é limitado, ou que o volume de mensagens atual não justifica a complexidade de manter um cluster próprio.

Sempre gostei muito da filosofia de David Heinemeier Hansson (DHH), o criador do Ruby on Rails. Ele frequentemente questiona o consenso da indústria e defende a simplicidade, a "compressão conceitual" e ferramentas que valorizem o tempo e a felicidade do desenvolvedor. Esse tipo de pensamento crítico, de ir contra a maré de "microsserviços para tudo" porque você entende a dor de manter sistemas complexos, é um traço puramente humano. A IA, por padrão, tende a sugerir o que é mais frequente em seus dados de treinamento, o que muitas vezes resulta em soluções engessadas e excessivamente complexas para problemas simples.

A dinâmica de poder corporativo

Chegamos então ao "elefante na sala". Por que essa urgência repentina em documentar o contexto? Precisamos ser transparentes e olhar para as motivações de negócios.

O conhecimento tácito sempre deu aos desenvolvedores um grande poder de barganha. O profissional que entende o funcionamento do sistema legado de ponta a ponta e sabe por que as coisas foram construídas daquela forma é difícil de ser substituído. Quando as lideranças técnicas e diretorias exigem a documentação do contexto, o objetivo é diminuir o bus factor (o risco associado à perda de membros da equipe que detêm conhecimento exclusivo).

Se uma empresa consegue transferir o "porquê" da cabeça do desenvolvedor para um banco de dados vetorial, ela capacita qualquer desenvolvedor júnior munido de um LLM (Large Language Model) a dar manutenção em sistemas complexos. O objetivo final de muitas corporações não é necessariamente melhorar o software, mas sim reduzir a dependência de profissionais seniores, cujos salários são mais altos, tornando a equipe mais intercambiável.

Isso é uma provocação necessária. Será que a iniciativa visa a excelência técnica, ou é uma estratégia de redução de custos disfarçada de boas práticas? Na minha experiência, os dois fatores andam de mãos dadas, mas o peso do fator econômico é subestimado em discussões técnicas.

Estamos acelerando o fim da nossa profissão?

Volto à pergunta que originou este post: ao documentarmos o nosso raciocínio, estamos ensinando a máquina a nos substituir de forma definitiva?

Eu acredito que não. A premissa de que a IA vai substituir o engenheiro de software baseia-se na ideia de que os requisitos de negócios são estáticos e que o ambiente de tecnologia é previsível. A realidade das trincheiras de desenvolvimento mostra exatamente o oposto.

O contexto não é uma foto; é um filme. O motivo pelo qual tomamos uma decisão de arquitetura em janeiro pode ser completamente invalidado em março devido a uma mudança na regulamentação, uma nova diretriz do cliente ou um corte de orçamento. A IA pode ler o contexto passado, mas não pode antecipar a negociação política necessária para aprovar uma refatoração de código com os stakeholders.

O trabalho do desenvolvedor de software nunca foi apenas digitar instruções para um compilador. Essa foi apenas a limitação imposta pelas ferramentas do passado. Nosso verdadeiro trabalho sempre foi navegar pela ambiguidade, traduzir necessidades humanas desordenadas em lógica estruturada e tomar decisões de compromisso (trade-offs).

Ao transferirmos a digitação do código para a IA e nos concentrarmos em documentar e definir o contexto, não estamos acabando com a nossa profissão; estamos, na verdade, destilando-a à sua essência. Estamos parando de atuar como tradutores de sintaxe e assumindo definitivamente o papel de engenheiros e tomadores de decisão.

A ferramenta certa e a falsa promessa da onisciência

Para tornar esta reflexão mais pragmática, proponho uma análise crítica comparando o uso de tecnologias e abordagens atuais para este problema de contexto.

ADRs vs. Comentários Inline

Historicamente, tentávamos colocar o contexto no próprio código. Comentários como // usando método X porque a API Y é instável eram comuns. O problema dessa abordagem é que ela perde o quadro geral. Quando as empresas hoje pedem contexto, elas pedem registros formais (ADRs) que detalham o problema, as opções consideradas, a decisão tomada e as consequências dessa decisão.

Ferramentas de IA conseguem analisar ADRs de forma muito mais eficiente do que tentar deduzir a arquitetura varrendo milhares de arquivos em busca de comentários dispersos. O ADR é estruturado, já o comentário é fragmentado.

Modelos Fechados vs. Modelos Locais

No que diz respeito à análise de contexto usando IA, há uma diferença substancial entre as abordagens. Ferramentas comerciais baseadas na nuvem (como o mencionado Claude, ou GPT-4o) oferecem capacidades de raciocínio avançadas. No entanto, enviar o contexto completo do negócio (que muitas vezes inclui estratégias não públicas, vulnerabilidades conhecidas de sistemas legados e informações proprietárias) para servidores de terceiros cria um risco de segurança e conformidade considerável.

Como já comentei em textos anteriores aqui no blog sobre o uso do GPT-OSS para análises locais e testes de código, a alternativa de rodar modelos de linguagem open-source no próprio ambiente da empresa resolve o problema da privacidade. Você pode alimentar o modelo local com todos os seus repositórios, wikis internas e ADRs, permitindo que a equipe tire dúvidas de contexto sem expor dados. A desvantagem atual é que modelos locais geralmente requerem hardware dedicado de alto custo e, dependendo do tamanho do parâmetro, ainda não possuem a mesma acurácia para deduções complexas que os modelos fechados de fronteira. Existe um trade-off claro entre capacidade de raciocínio de ponta e privacidade dos dados.

O futuro do desenvolvimento

A inteligência artificial transformou a escrita de código em um processo trivial. O que não é trivial é saber qual código escrever, onde inseri-lo e por que ele deve existir em primeiro lugar.

A exigência das empresas para que documentemos o contexto não deve ser vista como o canto do cisne da engenharia de software, mas como um rito de passagem. Deixamos para trás a era em que dominar a sintaxe de uma linguagem era o diferencial competitivo. Entramos na era em que a capacidade de analisar restrições, entender o negócio e tomar decisões estruturais é o que define o profissional.

Se o seu trabalho se resume a receber um ticket extremamente detalhado e transformar essas instruções exatas em código sem questionar, o seu emprego está, sim, em risco. No entanto, se você questiona o ticket, aponta falhas na lógica de negócios, sugere alternativas mais simples e entende o impacto de cada linha de código no produto final, a inteligência artificial será apenas a sua ferramenta de digitação mais eficiente.

Como você tem lidado com essa transição na sua equipe? O foco tem sido em gerar mais linhas de código, ou a sua empresa já percebeu que o gargalo real está na clareza das decisões?

Espero conseguir manter a frequência de publicações por aqui. Temos muito a debater sobre o impacto das novas tecnologias no nosso dia a dia. Se você tem interesse em se aprofundar nesses temas, recomendo conferir os outros artigos aqui do blog onde abordo tendências de inteligência artificial, inovações no mercado e dicas práticas de programação e arquitetura.

Deixe sua visão nos comentários e vamos continuar essa conversa.