IA na Codificação de Projetos Brownfield: Como Fazer IA Funcionar em Códigos Reais

Introdução: O Problema Brownfield

Imagine a cena: você acabou de assistir um agente de codificação com IA construir um aplicativo Next.js completo em 45 minutos. Seu gerente de engenharia entra no seu escritório com estrelas nos olhos, pronto para liberar essa mágica na sua base de código legada de 300.000 linhas. Você sabe o que acontece a seguir.

Aqui está a verdade desconfortável sobre ferramentas de codificação com IA no final de 2024: elas são incríveis para construir novos projetos do zero e péssimas para trabalhar com bases de código do mundo real.

O estudo de Stanford sobre o impacto da IA na produtividade do desenvolvedor confirmou o que muitas equipes de engenharia já sabiam:

Ferramentas de IA funcionam muito bem para projetos greenfield e pequenas mudanças
Em bases de código grandes e estabelecidas, elas frequentemente tornam os desenvolvedores menos produtivos
Muito do "código gerado por IA" é apenas retrabalho da porcaria que foi enviada na semana passada

A resposta comum varia entre pessimismo ("isso nunca vai funcionar para código real") e otimismo cauteloso ("talvez quando os modelos ficarem mais inteligentes"). Mas há uma terceira opção: fluxos de trabalho sistemáticos que fazem os modelos de hoje funcionarem em projetos brownfield.

Nos últimos meses, equipes usando essas técnicas conseguiram:

Corrigir bugs em bases de código Rust de 300.000 linhas que nunca tinham visto antes (em menos de uma hora)
Entregar 35.000 linhas de código funcional adicionando recursos importantes a sistemas complexos (em 7 horas)
Manter qualidade de código que passa pela revisão de engenheiros seniores

Isso não é teórico. Este é código de produção, em bases de código desconhecidas, frequentemente em linguagens que os desenvolvedores mal conhecem.

Como? Eles resolveram o problema brownfield.

Na FMKTech, ajudamos organizações a implementar esses fluxos de trabalho sistemáticos para fazer agentes de codificação com IA funcionarem em bases de código legadas do mundo real—não apenas demos impressionantes. Seja você explorando desenvolvimento assistido por IA para sua equipe ou procurando escalar implementações existentes, entender como navegar a complexidade brownfield é essencial para obter valor real de ferramentas de codificação com IA.

O Que Torna Brownfield Diferente?

Greenfield: A Zona de Conforto da IA

Quando você inicia um novo projeto:

Nenhum código existente para entender
Você define todos os padrões e convenções
Toda a base de código cabe facilmente no contexto
Erros são baratos—apenas delete e regenere

Agentes de codificação com IA se destacam aqui. Dê ao Claude uma especificação para um novo app Next.js e assista ele construir um protótipo funcional em uma hora. O contexto é limpo, os requisitos são claros, e não há legado para navegar.

Brownfield: O Desafio do Mundo Real

Quando você trabalha em uma base de código existente, tudo muda.

Conhecimento implícito: Decisões arquiteturais tomadas anos atrás, documentadas em lugar nenhum

Três anos atrás, alguém escolheu dividir sessões de usuário entre Redis e PostgreSQL. Metade dos dados da sessão vive em cada um. Por quê? Talvez o Redis ficasse sem memória. Talvez houvesse uma preocupação com confiabilidade. Talvez tenha sido apenas uma decisão ruim. O código não diz, os commits não explicam, e a pessoa que tomou a decisão deixou a empresa.

Então quando a IA vê esse padrão, parece um erro. Redundante. Ineficiente. A "correção óbvia" é consolidar tudo em um único armazenamento de dados. Exceto que isso quebra o failover de sessão de maneiras sutis que só aparecem sob carga.

Sem entender as decisões arquiteturais implícitas—e por que elas existem—a IA vai "corrigir" coisas que não deveriam ser corrigidas.

Dependências ocultas: Mude um arquivo, quebre três outros de maneiras não óbvias

Você atualiza a lógica de timeout de autenticação em auth/timeout-manager.ts. Mudança razoável. Testes passam. Envie.

Exceto que agora a sincronização offline do app mobile está quebrada. O gerenciador de timeout é chamado pelo middleware, que também é usado pelo endpoint de sincronização, que tem requisitos especiais de timing que não foram documentados. A conexão entre sua mudança e a sincronização mobile não está em nenhuma declaração de importação—é uma dependência de runtime que só existe sob condições específicas.

IA não consegue ver essas dependências ocultas sem exploração sistemática. Ela faz a mudança "óbvia" e introduz quebras sutis.

Padrões inconsistentes: O sistema de autenticação foi reescrito duas vezes, ambas versões ainda existem

Sua base de código tem três padrões diferentes para tratamento de erros. O jeito antigo de 2020 (lançando exceções), o jeito novo de 2023 (retornando tipos Result), e o híbrido "estávamos migrando mas paramos no meio do caminho" que existe em 60% do código.

Quando a IA gera código novo, qual padrão ela deveria seguir? Se ela escolher o padrão "moderno" Result mas integrar com um arquivo ainda usando exceções, você obtém um anti-padrão de mistura que torna o código ainda mais inconsistente.

Sem pesquisa para identificar quais padrões existem e quais seguir, a IA vai escolher o que parece melhor isoladamente—o que pode ser exatamente a escolha errada para sua base de código.

Escala massiva: 100.000+ linhas através de centenas de arquivos

Há 47 arquivos com "auth" no nome. Quais são relevantes para corrigir o bug de timeout? A resposta depende de entender a arquitetura, o que requer ler múltiplos arquivos para construir um modelo mental.

Se você deixar a IA buscar sequencialmente, ela pode ler 20 arquivos antes de encontrar o certo. São 10.000+ linhas no contexto antes de fazer qualquer trabalho útil. Quando ela encontra o código relevante, o contexto está 70% cheio e o modelo está operando no que um pesquisador chama de "zona burra".

O problema de escala não é apenas sobre tamanho—é sobre a explosão combinatória de onde procurar e o que importa.

Estouro de contexto: Apenas carregar arquivos relevantes excede a janela de contexto

Mesmo depois de identificar os arquivos certos, lê-los todos pode exceder seu orçamento de contexto. O gerenciador de sessão tem 1.200 linhas. A lógica de timeout tem 800 linhas. O middleware que o chama tem 950 linhas. Os testes são outras 1.500 linhas.

Você acabou de carregar 4.450 linhas, e ainda não começou a implementar nada. Se sua janela de contexto é 200k tokens (~150k na prática antes da degradação), você está com 30% de utilização antes de escrever uma única linha de código.

Sem estratégias de leitura cirúrgica—intervalos de linha, compactação, pesquisa paralela—o estouro de contexto impede você de até começar adequadamente.

Conhecimento tribal: "Ah sim, não mexa naquele módulo, é frágil"

Algumas partes da base de código têm uma reputação. O código de processamento de pagamento é "frágil". O handler de websocket é "estranho". A lógica de invalidação de cache é "não pergunte, apenas funciona".

Esse conhecimento tribal nunca é documentado. Ele existe em mensagens do slack, comentários de revisão de código, e na ansiedade coletiva da equipe. IA não tem acesso a esse contexto.

Então ela refatora confiantemente o código de pagamento "frágil" para ser "mais limpo", e introduz uma condição de corrida que foi corrigida três anos atrás. A mensagem de commit dessa correção diz "tratar caso extremo", o que não te diz nada sobre qual caso extremo ou por que importa.

É aqui que ferramentas de codificação com IA tipicamente falham. Elas não conseguem encontrar os arquivos certos entre centenas de opções. Elas perdem dependências críticas e quebram funcionalidade existente. Elas não entendem o contexto e histórico por trás das decisões de design. Elas produzem código que "funciona" isoladamente mas viola convenções da base de código. Elas desperdiçam a janela de contexto buscando aleatoriamente através de arquivos até atingirem o penhasco de desempenho.

Soa familiar? Se você tentou usar assistentes de codificação com IA em uma base de código real, provavelmente viveu essa frustração. A boa notícia é que é solucionável—e a solução não é esperar pelo GPT-5.

Os Quatro Desafios da Codificação Brownfield com IA

Desafio 1: O Problema da Descoberta

A situação: Você precisa corrigir um bug ou adicionar um recurso. A IA precisa encontrar os 5-10 arquivos relevantes entre 500+ arquivos na base de código.

O que falha:

Você: "Corrija o bug de timeout de autenticação"

IA: [Busca]
- Lê auth/handler.ts
- Lê auth/middleware.ts
- Lê auth/tokens.ts
- Lê auth/sessions.ts
- Lê auth/utils.ts
- Lê config/auth.ts
...
[30 arquivos depois, contexto está 70% cheio, não encontrou o bug real]

O que funciona: Fase de pesquisa estruturada com descoberta especializada.

Desafio 2: O Problema da Explosão de Contexto

A situação: Entender como um recurso funciona requer ler 20+ arquivos, cada um com 500+ linhas.

O que falha:

IA lê:
- Arquivo completo 1 (842 linhas)
- Arquivo completo 2 (1.243 linhas)
- Arquivo completo 3 (673 linhas)
- Arquivo completo 4 (891 linhas)

Contexto: 85% cheio
Qualidade: Na "zona burra"
Trabalho útil: Nenhum ainda

O que funciona: Leitura cirúrgica com intervalos de linha específicos e compactação.

Desafio 3: O Problema do Contexto Ausente

A situação: O código só faz sentido se você entender por que foi escrito daquela forma.

O que falha:

IA: "Esse tratamento de erro parece redundante, vou simplificá-lo"
[Remove tratamento de erro que foi adicionado para corrigir condição de corrida]
[Reintroduz bug que levou 3 dias para debugar da última vez]

O que funciona: Fluxo de trabalho com pesquisa primeiro que captura contexto histórico e restrições arquiteturais.

Desafio 4: O Problema da Integração

A situação: Código novo deve integrar com padrões, convenções e infraestrutura existentes.

O que falha:

IA: [Implementa recurso de forma limpa e moderna]
Engenheiro sênior: "Isso não segue nossos padrões, usa tratamento
de erro errado, e quebra nossas convenções de teste"

O que funciona: Descoberta de padrões e requisitos de integração explícitos no planejamento.

A Solução: Fluxos de Trabalho Brownfield Sistemáticos

O avanço não é esperar por modelos mais inteligentes. É aplicar fluxos de trabalho sistemáticos projetados especificamente para desenvolvimento brownfield.

A Abordagem de Três Fases

Em vez de jogar um agente de IA em uma base de código brownfield e torcer, estruture seu trabalho em três fases distintas:

1. Fase de Pesquisa: Entenda antes de tocar 2. Fase de Planejamento: Projete antes de implementar 3. Fase de Implementação: Execute com clareza

Cada fase tem objetivos específicos, orçamentos de contexto e pontos de revisão humana. Vamos mergulhar em cada uma.

Fase 1: Pesquisa - Entendendo Antes de Agir

A fase de pesquisa é sobre uma coisa: encontrar a verdade sobre como a base de código realmente funciona.

Objetivos da Pesquisa

Uma boa pesquisa brownfield responde:

Onde está o código relevante? (Referências específicas de arquivo:linha)
Como funciona atualmente? (Fluxo de dados, funções-chave, padrões)
Por que foi construído dessa forma? (Contexto arquitetural, restrições)
Quais são os pontos de integração? (Dependências, efeitos colaterais)
Como é testado? (Padrões de teste, cobertura, abordagem de verificação)

A Técnica de Pesquisa Paralela

Não deixe a IA buscar sequencialmente. Spawne múltiplos agentes de pesquisa especializados em paralelo:

[Lançar simultaneamente]

Agente 1: "Encontre todos os arquivos relacionados ao fluxo de autenticação"
→ Usa codebase-locator para identificar arquivos
→ Retorna: 12 arquivos com código relacionado a auth

Agente 2: "Analise a implementação de gerenciamento de sessão"
→ Usa codebase-analyzer para entender abordagem atual
→ Retorna: Explicação detalhada do tratamento de sessão

Agente 3: "Encontre padrões existentes para tratamento de timeout"
→ Usa pattern-finder para localizar recursos similares
→ Retorna: Exemplos de padrões de implementação de timeout

Agente 4: "Busque no diretório thoughts/ por decisões relacionadas a auth"
→ Usa thoughts-locator para encontrar contexto histórico
→ Retorna: Pesquisa anterior, decisões arquiteturais

[Cada agente trabalha isoladamente com seu próprio contexto]
[Agente principal recebe apenas descobertas compactas]
[Tempo total: 5-8 minutos, não 30+ minutos sequenciais]

Estrutura de Saída da Pesquisa

A fase de pesquisa deve produzir um documento estruturado, não um histórico de conversa:

# Pesquisa do Bug de Timeout de Autenticação

**Data**: 2025-01-15
**Base de Código**: UserService (250k LOC)
**Git Commit**: abc123def

## Entendimento do Problema
Sessões de usuário não expiram corretamente quando o período de graça
expira, permitindo acesso com tokens expirados.

## Implementação Atual

### Gerenciamento de Sessão
- Ponto de entrada: `src/auth/session-handler.ts:45`
- Validação de token: `src/auth/token-validator.ts:123`
- Lógica de timeout: `src/auth/timeout-manager.ts:67`
- Camada de banco de dados: `src/db/session-store.ts:89`

### Fluxo de Dados
1. Requisição chega ao handler de sessão (session-handler.ts:45)
2. Token extraído e validado (token-validator.ts:130)
3. Verificação de timeout contra armazenamento de sessão (timeout-manager.ts:72)
4. **LOCALIZAÇÃO DO BUG**: Verificação de período de graça falha em timeout-manager.ts:85

### Causa Raiz do Bug
A função `isSessionValid()` em `src/auth/timeout-manager.ts:85`
verifica expiração mas não trata adequadamente o caso onde o período
de graça também expirou. Retorna true quando deveria retornar false.

## Pontos de Integração
- Usado por: Middleware do API gateway (middleware/auth.ts:34)
- Depende de: Armazenamento de sessão, biblioteca JWT, cache Redis
- Efeitos colaterais: Registra no sistema de auditoria ao timeout

## Padrões de Teste
- Testes unitários: `tests/auth/timeout.test.ts`
- Testes de integração: `tests/integration/auth-flow.test.ts`
- Padrão: Abordagem test-first, todas mudanças em auth requerem testes

## Restrições Arquiteturais
- Deve manter compatibilidade com formato de token v1
- Não pode mudar schema do banco de dados (congelamento de migração até Q2)
- Cache Redis deve permanecer sincronizado com DB

## Contexto Histórico
De `thoughts/shared/research/2024-12-auth-refactor.md`:
- Período de graça foi adicionado para lidar com desvio de relógio entre serviços
- Bug anterior de timeout estava em local diferente (corrigido na PR #1234)
- Equipe debateu remover período de graça mas manteve para confiabilidade

## Abordagem Recomendada
Corrigir timeout-manager.ts:85 para verificar adequadamente tanto expiração
quanto período de graça. Adicionar casos de teste para caso extremo. Nenhuma
mudança de schema necessária.

Insight crítico: Este documento de pesquisa tem 100 linhas. Chegar a este ponto pode ter envolvido ler 50 arquivos e 10.000+ linhas de código através de múltiplos subagentes. Mas todo esse ruído fica nos contextos dos subagentes—o contexto principal vê apenas essas 100 linhas.

Pense nisso como enviar batedores à frente em vez de marchar todo seu exército através de cada caminho possível. Os batedores exploram, reportam de volta com um mapa, e então você avança com confiança.

O Checkpoint de Revisão Humana

Antes de prosseguir para o planejamento, um humano deve ler a pesquisa. Isso não é opcional.

Verifique:

✅ Os arquivos identificados estão realmente corretos?
✅ A análise de causa raiz faz sentido?
✅ Pontos de integração e dependências estão capturados?
✅ Existem restrições arquiteturais que devemos respeitar?
✅ A abordagem recomendada parece sólida?

Se algo estiver errado ou faltando, itere na pesquisa antes do planejamento. Uma linha ruim de pesquisa leva a milhares de linhas ruins de código.

Investimento de tempo: 5-10 minutos lendo pesquisa Tempo economizado: 2-3 horas de implementação indo na direção errada

Fase 2: Planejamento - Projete Antes de Construir

Com pesquisa sólida em mãos, o planejamento se torna direto. O objetivo é criar um guia de implementação detalhado, fase por fase.

Objetivos do Planejamento

Um bom plano brownfield especifica:

Exatamente o que mudar (Arquivos específicos e intervalos de linha)
A ordem das mudanças (Faseado para minimizar risco)
Como verificar cada etapa (Critérios de sucesso automatizados e manuais)
O que NÃO mudar (Limites de escopo explícitos)
Requisitos de integração (Seguindo padrões existentes)

A Estrutura de Implementação Faseada

Quebre o trabalho em fases pequenas e verificáveis. Aqui está como o plano de implementação se parece:

Estrutura do Plano:

# Correção de Timeout de Autenticação - Plano de Implementação

## Visão Geral
Corrigir o bug de timeout de período de graça na validação de sessão
atualizando o gerenciador de timeout para verificar adequadamente tanto
expiração quanto período de graça.

## Estado Atual (da pesquisa)
Bug em `src/auth/timeout-manager.ts:85` onde `isSessionValid()`
retorna true para sessões onde tanto timeout quanto período de graça expiraram.

## Estado Final Desejado
Sessões com períodos de graça expirados são corretamente rejeitadas.
Testes existentes passam. Novos testes de caso extremo adicionados e passando.

## O Que NÃO Estamos Fazendo
- NÃO mudando schema do banco de dados
- NÃO modificando formato de token
- NÃO mudando contratos de API
- NÃO tocando no handler de sessão ou validador de token

## Fase 1: Adicionar Teste com Falha

### Mudanças
Arquivo: `tests/auth/timeout.test.ts`
Adicionar caso de teste para sessão expirada com período de graça expirado

    test('rejeita sessão quando período de graça expirado', async () => {
      const session = createExpiredSessionWithExpiredGrace();
      const result = await isSessionValid(session);
      expect(result).toBe(false);
    });

### Critérios de Sucesso

**Automatizado:**
- [ ] Teste compila: `npm run build:test`
- [ ] Teste falha como esperado: `npm test timeout.test.ts`

**Manual:**
- [ ] Teste representa com precisão o cenário do bug
- [ ] Teste é claro e mantível

**Checkpoint**: Confirme falha do teste antes de prosseguir para Fase 2

---

## Fase 2: Corrigir Lógica de Timeout

### Mudanças
Arquivo: `src/auth/timeout-manager.ts:85-92`

Atualizar `isSessionValid()` para verificar ambas condições:

    function isSessionValid(session: Session): boolean {
      const now = Date.now();

      // Verificar expiração de sessão
      if (now > session.expiresAt) {
        // Sessão expirada, verificar período de graça
        if (now > session.expiresAt + GRACE_PERIOD_MS) {
          return false; // Período de graça também expirado
        }
      }

      return true;
    }

### Critérios de Sucesso

**Automatizado:**
- [ ] Todos testes unitários passam: `npm test auth/`
- [ ] Novo teste passa: `npm test timeout.test.ts`
- [ ] Verificação de tipo passa: `npm run type-check`
- [ ] Linting passa: `npm run lint`

**Manual:**
- [ ] Lógica trata casos extremos corretamente
- [ ] Nenhuma degradação de desempenho
- [ ] Mensagens de erro são claras

**Checkpoint**: Todas verificações automatizadas devem passar antes da Fase 3

---

## Fase 3: Adicionar Teste de Integração

### Mudanças
Arquivo: `tests/integration/auth-flow.test.ts`

Adicionar teste end-to-end para fluxo completo de auth com timeout:

    test('fluxo completo de auth com timeout de período de graça', async () => {
      // Criar sessão, esperar por timeout + período de graça
      // Verificar requisição API é rejeitada
      // Verificar log de auditoria é criado
    });

### Critérios de Sucesso

**Automatizado:**
- [ ] Testes de integração passam: `npm test integration/`
- [ ] Verificação de cobertura passa: `npm run coverage`

**Manual:**
- [ ] Testar em ambiente de staging
- [ ] Verificar logging de auditoria funciona corretamente
- [ ] Verificar invalidação de cache Redis

---

## Estratégia de Teste

### Testes Unitários
- Caso extremo: Exatamente no limite do período de graça
- Caso extremo: Pouco antes do período de graça expirar
- Caso extremo: Muito depois do período de graça

### Testes de Integração
- Fluxo completo de requisição com sessão expirada
- Verificar efeitos downstream (logging, cache)

### Testes Manuais
1. Deploy para staging
2. Criar sessão e esperar pelo timeout
3. Verificar acesso é negado
4. Verificar logs de auditoria
5. Testar com cenários de desvio de relógio

## Considerações de Desempenho
- Nenhuma consulta adicional ao banco de dados
- Comportamento de cache inalterado
- Características de desempenho existentes mantidas

## Plano de Rollback
Se problemas surgirem:
1. Reverter mudanças em timeout-manager.ts
2. Manter novos testes (marcados como ignorados)
3. Criar novo ticket de bug com descobertas

## Referências
- Pesquisa: `thoughts/shared/research/2025-01-15-auth-timeout-bug.md`
- PR relacionada: #1234 (correção de timeout anterior)
- Documento de arquitetura: `thoughts/shared/plans/auth-architecture.md`

O Checkpoint de Revisão Humana

Antes da implementação, um humano deve revisar o plano. Novamente, não opcional.

Verifique:

✅ As fases estão adequadamente delimitadas e testáveis?
✅ Os critérios de sucesso cobrem casos extremos?
✅ A abordagem é tecnicamente sólida?
✅ Os requisitos de integração estão claros?
✅ Está faltando algo?

Investimento de tempo: 10-15 minutos revisando plano Tempo economizado: 3-4 horas de implementação fazendo a coisa errada

Fase 3: Implementação - Execute com Clareza

Com pesquisa e plano completos, a implementação se torna quase mecânica. A IA tem tudo que precisa em um contexto limpo.

Abordagem de Implementação

Inicie uma sessão nova com:

O plano de implementação (compacto!)
Referência à pesquisa (leia apenas se necessário)
Instrução clara para trabalhar fase por fase

Você: "Implemente a correção de timeout de autenticação seguindo este plano:
thoughts/shared/plans/2025-01-15-auth-timeout-fix.md

Trabalhe através de cada fase sequencialmente. Após cada fase:
1. Execute toda verificação automatizada
2. Pare e aguarde minha confirmação antes de prosseguir

Leia a pesquisa referenciada apenas se precisar de esclarecimento.
Não se desvie do plano sem perguntar primeiro."

Por Que Isso Funciona

O agente de implementação começa com:

Contexto limpo: Sem ruído de pesquisa, sem vai e vem de planejamento
Instruções claras: Exatamente o que fazer, em qual ordem
Critérios de sucesso: Sabe quando cada fase está completa
Restrições: Sabe o que NÃO mudar
Padrões: Pesquisa identificou convenções a seguir

Lidando com Problemas de Implementação

Se o agente ficar preso ou produzir resultados errados:

Não deixe girar: Pare após 2-3 tentativas falhadas
Compacte o problema: Documente o que está falhando e por quê
Talvez pesquisa esteja errada: Volte para pesquisa, investigue
Talvez plano esteja errado: Atualize plano com novo entendimento
Comece do zero: Nova sessão com contexto atualizado

Exemplo do Mundo Real: 35.000 Linhas em 7 Horas

Vamos olhar um exemplo concreto: adicionar suporte a cancelamento ao BAML (uma base de código Rust de 300k linhas).

Fase de Pesquisa (2 horas)

Agentes de pesquisa paralela investigaram:

Como operações assíncronas funcionam atualmente
Onde cancelamento precisa ser suportado
Padrões de cancelamento Rust (tokio, futures)
Padrões de teste para código assíncrono
Implicações de desempenho

Saída: Documento de pesquisa de 300 linhas identificando:

47 arquivos que precisam mudanças
8 pontos-chave de integração
3 restrições arquiteturais
Padrões assíncronos existentes a seguir
Padrões de teste a replicar

Fase de Planejamento (1 hora)

Com pesquisa em mãos, planejamento identificou:

6 fases de implementação
Mudanças específicas para cada arquivo
Abordagem test-first para cada fase
Critérios de sucesso (automatizado + manual)
Estratégia de rollback

Saída: Plano de implementação de 400 linhas

Fase de Implementação (4 horas)

Seguindo o plano fase por fase:

Fase 1: Adicionar tipo de token de cancelamento (30 min)
Fase 2: Passar tokens através do executor assíncrono (45 min)
Fase 3: Atualizar runtime de função (1 hora)
Fase 4: Adicionar pontos de cancelamento (1 hora)
Fase 5: Atualizar testes (45 min)
Fase 6: Teste de integração (30 min)

Resultado: 35.000 linhas de código funcional, testes passando

O Insight-Chave

Sem pesquisa e planejamento:

Teria gastado 4+ horas apenas encontrando os arquivos certos
Contexto teria enchido com ruído
Teria perdido restrições arquiteturais
Teria violado padrões existentes
Engenheiros seniores estimaram: 3-5 dias de trabalho

Com fluxo de trabalho sistemático:

Tempo total: 7 horas (incluindo pesquisa e planejamento)
Qualidade do código: Passou revisão de engenheiro sênior
Taxa de sucesso na primeira vez: ~80% (vs. ~20% sem fluxo de trabalho)

Melhores Práticas Brownfield

Essas não são diretrizes teóricas—são lições testadas em batalha de equipes entregando código de produção em bases de código brownfield reais. Ignore-as por sua conta e risco.

1. Sempre Pesquise Primeiro

Aqui está o erro que todos cometem: "Isso parece simples, é só atualizar um valor de configuração. Deixa eu pular a pesquisa e ir direto para implementação."

Então 90 minutos depois, você está três implementações falhadas, a IA leu 40 arquivos, o contexto é uma bagunça, e você ainda não tem código funcionando. O valor de configuração "simples" acaba sendo referenciado em sete lugares, três deles dinamicamente, e mudá-lo quebra um script de migração que roda no deployment.

Os 10-15 minutos que você "economizou" pulando pesquisa acabaram de custar uma hora de frustração.

Mesmo para tarefas "simples", gaste 10-15 minutos em pesquisa. Onde está o código? Como realmente funciona? Que padrões existem? Quais são as restrições? O que depende disso?

Isso não é sobrecarga opcional—é a fundação que faz todo o resto funcionar. Pesquisa é o que transforma IA de um gerador de código aleatório em uma ferramenta de implementação direcionada.

Nunca pule isso. Os 10 minutos investidos economizam horas depois. Todas as vezes.

2. Leia Tudo Que a IA Produz

Seu tempo de maior alavancagem não é revisar o código final. É revisar a pesquisa e planos antes de qualquer código ser escrito.

Pense nos modos de falha:

Pesquisa ruim → plano ruim → implementação ruim → horas desperdiçadas
Pesquisa boa → plano ruim → implementação ruim → uma hora desperdiçada
Pesquisa boa → plano bom → implementação ruim → 15 minutos desperdiçados

Se você pega problemas na fase de pesquisa, você previne milhares de linhas de código de irem na direção errada. Se você pega problemas na fase de planejamento, você previne horas de churn de implementação. Se você espera até revisar código, você já pagou o custo total do erro.

Isso cria uma pirâmide de alavancagem:

Revisar código: valor 1x (você pega bugs antes de enviarem)
Revisar plano: valor 10x (você pega abordagem errada antes da implementação)
Revisar pesquisa: valor 100x (você pega entendimento errado antes do planejamento)

As equipes que entregam código brownfield de alta qualidade gastam 30-40% do seu tempo revisando pesquisa e planos. As equipes que lutam gastam 90% do seu tempo revisando código.

3. Torne Limites de Escopo Explícitos

IA não tem senso natural de escopo. Dado um bug para corrigir, ela pode decidir refatorar o módulo inteiro "já que está aqui". Dado um recurso para adicionar, ela pode redesenhar sua arquitetura para ser "mais limpa".

Você precisa de limites explícitos. Em cada plano, inclua uma seção "O Que NÃO Estamos Fazendo":

NÃO mudando schema do banco de dados
NÃO modificando contratos de API
NÃO tocando no módulo legado frágil
NÃO refatorando enquanto corrige bugs

Isso previne scope creep e mantém a IA focada na tarefa real. Também força você a pensar sobre o que está no escopo vs. o que é uma preocupação separada.

Quando a IA sair do script durante implementação, você tem um ponto de referência claro: "O plano diz que NÃO estamos refatorando tratamento de erro. Mantenha o foco na correção de timeout."

4. Use Implementação Orientada a Testes

Em código brownfield, testes são sua rede de segurança. É como você sabe que a mudança funcionou e você não quebrou nada mais.

O padrão test-first funciona excepcionalmente bem com IA:

Escreva teste com falha (captura comportamento desejado)
Implemente correção (faça teste passar)
Verifique sem regressões (todos outros testes ainda passam)

Por que isso funciona tão bem? Porque testes fornecem critérios de sucesso claros e executáveis. "Faça esse teste passar" é inequívoco de uma forma que "corrija o bug" não é.

Testes também pegam as quebras sorrateiras. Sua mudança pode corrigir o problema imediato mas quebrar um caso extremo que só aparece sob condições específicas. Sem testes, você descobriria em produção. Com testes, você descobre em 30 segundos.

Para trabalho brownfield, seu plano de implementação deveria começar com "Fase 1: Adicionar teste com falha." Não pule isso. Se você implementar primeiro e testar depois, você descobrirá que sua implementação estava errada depois de já ter pago o custo de contexto.

5. Abrace a Iteração

Pesquisa às vezes estará errada. Você identificará os arquivos errados ou perderá uma dependência-chave. Planos precisarão ajuste. Você descobrirá durante planejamento que pesquisa perdeu uma restrição. Implementação encontrará problemas inesperados. O código não compilará por causa de uma incompatibilidade de tipo que pesquisa não pegou.

Isso é normal. É assim que desenvolvimento brownfield funciona, mesmo com humanos. A diferença é que fluxos de trabalho sistemáticos lidam com iteração graciosamente:

Pesquisa ruim? Itere na pesquisa com melhor direcionamento. Spawne subagentes mais focados. Leia os arquivos específicos que você agora percebe que importam.
Plano ruim? Atualize o plano e comece implementação do zero com contexto limpo. Não tente "consertar" implementação com contexto contaminado.
Implementação presa? Compacte o progresso que fez, documente o que não está funcionando, reinicie a fase com entendimento atualizado.

O anti-padrão é "continuar empurrando para frente com entendimento errado." IA alegremente continuará tentando abordagens falhadas para sempre. Você precisa pegar quando iteração é necessária e reiniciar com melhor informação.

Observe sinais de que você precisa iterar: mesmo erro aparecendo múltiplas vezes, IA lendo os mesmos arquivos repetidamente, implementação levando 3x mais tempo que planejado. Esses são sinais para parar, compactar aprendizados, e reiniciar com contexto atualizado.

6. Mantenha Nomenclatura Consistente

Agentes de IA dependem fortemente de correspondência de padrões e busca semântica. Nomenclatura consistente amplifica sua habilidade de encontrar código relevante. Nomenclatura inconsistente a paralisa.

Se você chama autenticação de "auth" em alguns arquivos, "authentication" em outros, "authN" em alguns lugares, e "user_verification" no módulo legado, IA não consegue encontrar todo o código relevante. Ela buscará por "auth", encontrará metade dos arquivos, perderá o resto, e implementará baseada em entendimento incompleto.

O mesmo princípio se aplica a padrões de nomenclatura de arquivos e estruturas de diretórios. Se todos seus handlers de rota estão em routes/, lógica de serviço está em services/, e acesso a dados está em repositories/, IA pode aprender esses padrões e navegar eficientemente. Se eles estão espalhados aleatoriamente, cada tarefa começa com descoberta cara.

Você não precisa de consistência perfeita—isso é irrealista em código brownfield. Mas você precisa de consistência suficiente para que padrões sejam descobríveis. Quando você refatora ou adiciona código novo, empurre em direção à consistência em vez de para longe dela.

Isso paga exponencialmente. Cada melhoria em consistência de nomenclatura torna cada fase futura de pesquisa ligeiramente mais rápida e mais precisa.

7. Documente Decisões Arquiteturais

O melhor investimento que você pode fazer em produtividade brownfield com IA é documentação arquitetural leve.

Não especificações de 50 páginas. Não documentação exaustiva de API. Apenas documentos curtos que capturam:

Por que as coisas são estruturadas do jeito que são
Que restrições existem e por quê
Padrões a seguir para tarefas comuns
História de decisões-chave

Exemplo: Um documento de 200 linhas que explica por que sessões são divididas entre Redis e Postgres, quais são as características de desempenho, e quais são os modos de falha. Isso se torna um input crítico durante pesquisa para quaisquer mudanças relacionadas a auth.

Esses documentos não precisam ser perfeitos ou completos. Comece com as áreas de maior dor—as partes da base de código onde IA consistentemente fica confusa ou comete erros. Documente apenas contexto suficiente para evitar repetir esses erros.

Com o tempo, seus documentos de pesquisa se tornam documentação arquitetural. A pesquisa de corrigir o bug de timeout de auth se torna a referência para o próximo recurso relacionado a auth. Você está construindo conhecimento institucional como efeito colateral de fluxos de trabalho sistemáticos.

As equipes com melhor produtividade brownfield com IA acumularam 20-30 desses documentos leves. Cada um representa algumas horas de investimento inicial e economiza dezenas de horas através de tarefas futuras.

Modos de Falha Brownfield Comuns

Toda equipe aprendendo codificação brownfield com IA atinge esses modos de falha. As equipes inteligentes aprendem dos erros dos outros em vez de cometer todos eles mesmos.

Modo de Falha 1: Pular Pesquisa

Você está olhando para o que parece um bug direto. A mensagem de erro é clara. A correção é óbvia. Você pode praticamente ver a mudança de três linhas na sua cabeça.

Então você pula pesquisa e diz para a IA: "Corrija o bug de timeout no sistema de auth."

A IA começa buscando. Ela lê auth/handler.ts. Faz sentido—é onde requisições entram. Então ela lê auth/middleware.ts. Também razoável—é onde validação acontece. Então auth/tokens.ts, auth/sessions.ts, auth/utils.ts, config/auth.ts.

Vinte arquivos depois, contexto está 60% cheio, e a IA ainda não encontrou o bug real. Ela arrisca uma correção. A correção aborda um sintoma mas não a causa raiz. Testes passam—mal—porque os testes não cobrem o caso extremo. Você envia.

Três dias depois, o bug está de volta. Gatilho diferente, mesma causa raiz. Você gastou duas horas em uma correção que não corrigiu nada, e agora está recomeçando.

O que deu errado? O bug não estava no handler de auth ou middleware ou em qualquer dos lugares que pareciam óbvios. Estava em um utilitário gerenciador de timeout que é chamado indiretamente através de três camadas de abstração. Pesquisa teria encontrado isso em 10 minutos traçando sistematicamente o caminho de execução.

Sem pesquisa, IA busca aleatoriamente e queima contexto em becos sem saída. Com pesquisa, ela vai diretamente ao local certo com precisão cirúrgica.

Modo de Falha 2: Não Ler Pesquisa

Você aprendeu a lição do Modo de Falha 1. Você está fazendo pesquisa! Sua IA produz um documento de pesquisa detalhado—300 linhas explicando como o sistema de auth funciona, onde está o bug, o que precisa mudar.

Você folheia o resumo executivo. Parece bom. Você alimenta diretamente para planejamento. Planejamento produz um plano de implementação. Você alimenta isso diretamente para implementação.

Três horas de implementação depois, nada funciona. As mudanças não compilam. Quando você corrige os erros de compilação, testes falham de formas estranhas. Você está preso debugando mensagens de erro crípticas.

Finalmente, você realmente lê o documento de pesquisa. Acontece que a IA identificou mal a causa raiz. A pesquisa parecia detalhada, mas ela traçou o caminho de execução errado. Ela seguiu o caminho feliz e perdeu o caso extremo onde o bug realmente acontece.

Se você tivesse lido a pesquisa cuidadosamente antes do planejamento, teria pegado isso em cinco minutos. Agora você desperdiçou três horas de implementação, contaminou seu contexto com tentativas falhadas, e precisa recomeçar com melhor pesquisa.

Este é o modo de falha mais caro porque se acumula. Pesquisa ruim → plano ruim → implementação ruim → reinício completo. Você paga o custo completo de todo o fluxo de trabalho baseado em uma fundação errada.

A correção não é apenas "leia a pesquisa"—é lê-la ceticamente. O caminho de execução faz sentido? Os arquivos identificados são realmente relevantes? A análise de causa raiz explica todos os sintomas? Desafie a pesquisa. Verifique as afirmações-chave. Certifique-se de que a fundação é sólida.

Modo de Falha 3: Critérios de Sucesso Vagos

Seu plano de implementação diz:

Fase 1: Corrigir a lógica de timeout
Fase 2: Garantir que funciona
Fase 3: Limpar quaisquer problemas

Isso parece bem—é um plano! Mas observe o que acontece durante implementação.

A IA corrige a lógica de timeout. Ela terminou a Fase 1? Ela roda os testes. Alguns passam, alguns falham. As falhas são esperadas? O plano não diz. Ela tenta corrigir os testes que falham. Agora testes diferentes falham. Ela continua iterando, mudando tanto a correção quanto os testes, nunca certa se está fazendo progresso ou andando em círculos.

Quando você verifica, a IA fez 15 tentativas diferentes, contexto está completamente contaminado com experimentos falhados, e você não tem ideia qual versão estava mais próxima do correto.

O problema não foi a IA—foi o plano. "Garantir que funciona" não é acionável. A IA não sabe o que "funciona" significa. Significa todos testes existentes passam? Significa o bug específico está corrigido? Significa desempenho é mantido? Significa o código segue padrões existentes?

Compare com critérios de sucesso específicos:

Fase 1: Corrigir lógica de timeout
- TODOS testes unitários em auth/ passam
- Especificamente: timeout.test.ts linha 47 (o teste falhando) passa
- Verificação de tipo passa: npm run type-check
- Nenhuma mudança em quaisquer outros arquivos

Agora a IA sabe exatamente quando terminou. Passa todas essas verificações? Vá para Fase 2. Falha alguma verificação? Continue iterando, mas apenas no escopo da Fase 1.

Critérios vagos levam a scope creep, iteração sem fim, e contaminação de contexto. Critérios específicos levam a trabalho focado e completude clara.

Modo de Falha 4: Sem Limites de Escopo

O plano diz: "Corrija o bug de timeout de autenticação." A IA lê o código de timeout e nota que o tratamento de erro não é ótimo. Os padrões são inconsistentes. O logging poderia ser melhor. Já que está corrigindo o timeout, por que não limpar isso?

Então ela refatora o tratamento de erro. E atualiza o logging. E padroniza os padrões. E extrai algumas funções auxiliares. O diff agora é 400 linhas através de 8 arquivos em vez de 20 linhas em 1 arquivo.

Seu engenheiro sênior revisa a PR: "Não posso aprovar isso. A correção de timeout parece boa, mas toda essa refatoração introduz risco. Não refatoramos código de auth sem testes extensivos. Quebre isso em duas PRs—a correção e a refatoração—e vamos precisar de um plano de teste separado para a refatoração."

Você está bloqueado. O trabalho está feito mas não é enviável. Você precisa desembaraçar a correção de timeout da refatoração, o que é mais difícil do que parece porque agora estão entrelaçadas.

Isso acontece porque IA não tem senso inerente de escopo. Sem limites explícitos, ela segue otimização local: fazer cada pedaço de código tão bom quanto pode ser. Mas isso viola o princípio brownfield: minimizar área de superfície de mudança.

A correção é simples mas requer disciplina. Todo plano precisa de uma seção "O Que NÃO Estamos Fazendo":

NÃO refatorando tratamento de erro
NÃO atualizando padrões de logging
NÃO extraindo funções auxiliares
NÃO tocando qualquer código fora de timeout-manager.ts

Esses limites parecem restritivos—não é desperdício deixar código subótimo quando já estamos lá? Mas em desenvolvimento brownfield, disciplina de escopo é segurança. Cada mudança adicional é risco adicional. Corrija uma coisa de cada vez. Envie. Então considere melhorias separadamente.

Sem limites, IA otimiza para elegância de código. Com limites, ela otimiza para mudanças seguras e enviáveis. Em trabalho brownfield, o segundo é vastamente mais valioso.

Quando IA Brownfield Ainda Luta

Sejamos honestos: fluxos de trabalho sistemáticos não resolvem tudo. Alguns cenários brownfield permanecem genuinamente difíceis, mesmo com pesquisa e planejamento perfeitos. Saber quando você está atingindo os limites das capacidades atuais da IA é tão importante quanto conhecer as técnicas em si.

1. Dependências Profundamente Aninhadas

Quando mudar um arquivo afeta 20+ arquivos de formas não óbvias, mesmo boa pesquisa pode perder dependências ocultas.

Mitigação: Comece com testes de integração abrangentes antes de fazer mudanças.

2. Comportamento Legado Não Documentado

Quando o código faz algo por uma razão que se perdeu na história, IA pode "corrigir" comportamento que era realmente intencional.

Mitigação: Seja extra cuidadoso com código que parece "estranho". Pesquise por que antes de mudar.

3. Código Crítico de Desempenho

Quando desempenho depende de detalhes sutis de implementação, IA pode introduzir regressões enquanto mantém funcionalidade.

Mitigação: Inclua teste de desempenho em critérios de sucesso. Benchmark antes e depois.

4. Máquinas de Estado Complexas

Quando correção depende de transições de estado sutis, IA pode introduzir bugs que só aparecem em casos extremos.

Mitigação: Teste extensivo baseado em propriedades. Revisão manual de transições de estado.

Medindo Sucesso

Aqui está a coisa sobre medir efetividade de IA brownfield: as métricas tradicionais mentem para você.

Se você apenas rastreia "tempo para enviar código", você otimizará para a coisa errada. Você pulará pesquisa, apressará planejamento, e acabará com código que tecnicamente funciona mas introduz bugs sutis ou viola padrões arquiteturais. Sua PR é merged, métricas parecem boas, e três semanas depois você está debugando um incidente de produção.

O que realmente importa é entender onde seu fluxo de trabalho está quebrando e se você está construindo velocidade sustentável.

Pense nisso como medir produtividade de desenvolvimento de software—linhas de código é uma métrica terrível, mas tempo de ciclo combinado com indicadores de qualidade conta a história real.

Métricas de Processo: Encontrando Seus Gargalos

Tempo gasto em pesquisa vs. implementação

Esta proporção te diz se você está fazendo trabalho de descoberta suficiente. Equipes novas em IA brownfield frequentemente gastam 10% em pesquisa, 90% em implementação, então se perguntam por que a IA continua girando em círculos.

Equipes maduras invertem isso: 40% pesquisa, 30% planejamento, 30% implementação. Parece lento no início—você não está enviando código!—mas seu tempo real para PR funcionando cai dramaticamente porque você não está desperdiçando ciclos em implementações erradas.

Se você está gastando menos de 30% em pesquisa, provavelmente está enviando porcaria.

Número de iterações pesquisa → plano

Isso mede quantas vezes você tem que refazer pesquisa porque o plano revelou lacunas. Uma ou duas iterações é normal—você descobre o que não sabe quando tenta planejar. Cinco iterações significa que sua pesquisa não foi sistemática o suficiente.

Observe esse número ao longo do tempo. Ele deveria diminuir conforme você fica melhor em fazer as perguntas certas de pesquisa.

Taxa de aderência ao plano durante implementação

A implementação realmente segue o plano, ou a IA constantemente sai do script? Alta aderência (80%+) significa que seu plano foi específico o suficiente e sua pesquisa foi precisa. Baixa aderência significa que ou o plano foi vago, a pesquisa estava errada, ou seu contexto de implementação foi contaminado.

Quando aderência cai, não culpe a IA—sua pesquisa ou planejamento provavelmente perdeu algo crítico.

Métricas de Qualidade: Você Está Construindo Melhor?

Taxa de aprovação de PR na primeira vez

Esta é sua métrica estrela norte. Ela te diz se o fluxo de trabalho pesquisa → plano → implementar está realmente funcionando.

Antes de fluxos de trabalho sistemáticos, equipes podem ver 20-30% de aprovação na primeira vez. O resto precisa de retrabalho significativo. Com fluxos de trabalho maduros, você deveria atingir 70-80% de aprovação na primeira vez.

Se você está preso abaixo de 50%, sua fase de pesquisa não está capturando contexto suficiente sobre padrões e restrições.

Bugs de regressão introduzidos

Toda regressão é uma falha de pesquisa. Você mudou algo sem entender suas dependências, ou você "corrigiu" comportamento que era realmente intencional.

Rastreie esses implacavelmente. Quando uma regressão acontece, pergunte: o que a pesquisa perdeu? Atualize sua checklist de pesquisa para pegar essa categoria na próxima vez.

Volume de feedback de revisão de código

Quanto feedback o código gerado por IA recebe? Mais importante, que tipo?

"Isso não segue nossos padrões" → Pesquisa não capturou padrões "Isso quebra caso extremo X" → Planejamento não pensou através de casos extremos "Isso é muito complexo" → Implementação saiu do plano e sobre-engenheirizou

Use temas de feedback para melhorar seus templates de pesquisa e planejamento.

Métricas de Eficiência: Ficando Mais Rápido Sem Quebrar Coisas

Tempo de início da tarefa até PR mergeável

Este é seu tempo de ciclo. Inclui pesquisa, planejamento, implementação e iteração. Rastreie, mas não otimize diretamente—otimize as métricas de processo acima, e tempo de ciclo melhorará como efeito colateral.

No início, tarefas brownfield podem levar 2-3x mais tempo com fluxos de trabalho sistemáticos do que "apenas pular e codificar". Tudo bem. Você está aprendendo o processo. Após algumas semanas, você igualará sua velocidade antiga. Após alguns meses, você será 3-5x mais rápido.

Utilização de contexto durante implementação

Quão cheia está a janela de contexto da IA durante implementação? Se você está regularmente atingindo 70-80% de utilização, seu agente de implementação está fazendo demais—provavelmente porque pesquisa e planejamento não foram específicos o suficiente, forçando implementação a fazer trabalho de descoberta.

Implementação saudável roda a 40-50% de utilização de contexto. O resto é reservado para realmente pensar sobre o código.

Custo de token por recurso

Isso importa por duas razões: seu orçamento, e como proxy para trabalho desperdiçado.

Se custos de token disparam em uma tarefa, você provavelmente gastou muito contexto em tentativas falhadas, exploração aleatória, ou agentes de implementação fazendo pesquisa. Custos altos de token geralmente se correlacionam com baixas taxas de aprovação na primeira vez—você está girando, não enviando.

Métricas de Equipe: Construindo Capacidade Organizacional

Compartilhamento de conhecimento (via documentos de pesquisa)

Aqui está um benefício escondido de fluxos de trabalho brownfield sistemáticos: os documentos de pesquisa que você cria se tornam materiais de onboarding, documentação de arquitetura, e conhecimento institucional.

Conte quantas vezes documentos de pesquisa são referenciados por outros membros da equipe. Se ninguém nunca os lê exceto a pessoa que os criou, eles não são valiosos o suficiente—provavelmente muito verbosos ou não estruturados.

Bons documentos de pesquisa são referenciados 5-10 vezes nos próximos meses por colegas trabalhando em recursos relacionados.

Tempo de onboarding para novos engenheiros

Quanto tempo leva para um novo engenheiro fazer sua primeira contribuição significativa a uma base de código brownfield? Com abordagens tradicionais de "leia o código e descubra", isso pode levar semanas ou meses.

Com documentos de pesquisa acumulados de fluxos de trabalho sistemáticos com IA, novos engenheiros podem ser produtivos em dias. Os documentos de pesquisa respondem "onde está isso?", "como isso funciona?", e "por que isso foi construído dessa forma?"—exatamente o que novos engenheiros precisam.

Se tempo de onboarding não está diminuindo, seus documentos de pesquisa não estão capturando o contexto certo.

Confiança em código gerado por IA

Meça isso qualitativamente através de discussões de equipe. Engenheiros confiam na saída da IA, ou a tratam como suspeita por padrão?

Baixa confiança é geralmente um sintoma de pular pesquisa ou não revisar planos. Quando engenheiros veem IA produzir código de alta qualidade consistentemente—porque está seguindo pesquisa e planos sólidos—confiança se constrói rapidamente.

Alta confiança não significa confiança cega. Significa que a equipe sabe que o processo funciona e foca tempo de revisão em verificação ao invés de suspeita.

A Mudança Mental Necessária

Trabalhar efetivamente com IA em bases de código brownfield requer uma mudança mental significativa. Isso é frequentemente mais difícil do que aprender as técnicas reais, porque desafia hábitos profundamente enraizados sobre como desenvolvimento de software funciona.

De: Implementação Direta

Antigo: Mergulhe no código, comece mudando coisas, itere até funcionar

Novo: Pesquisa → Plano → Implementação, com revisão humana em cada fase

De: Código como Artefato Primário

Antigo: Código é o que importa, todo o resto é documentação

Novo: Pesquisa e planos são tão importantes quanto código, às vezes mais

De: Contexto Individual

Antigo: Todo o contexto está na minha cabeça enquanto trabalho

Novo: Contexto é explicitamente capturado em documentos para IA e equipe

De: Confiando em Seu Entendimento

Antigo: Eu entendo esse código, posso mudá-lo com segurança

Novo: IA pesquisa código, eu verifico seu entendimento antes de prosseguir

De: Foco em Implementação

Antigo: Gaste 90% do tempo escrevendo código, 10% planejando

Novo: Gaste 40% pesquisa, 30% planejamento, 30% implementação

A Verdade Desconfortável

Aqui está o que separa equipes enviando código brownfield de produção com IA de equipes lutando:

Elas gastam mais tempo NÃO codificando.

Eu sei, eu sei. Você se tornou engenheiro para escrever código, não documentos. Mas me ouça.

Mais tempo em:

Pesquisar como código realmente funciona
Planejar mudanças em detalhe
Revisar pesquisa e planos
Iterar em entendimento

Menos tempo em:

Diretamente escrever código
Debugar código gerado por IA
Reescrever porcaria de tentativas anteriores

O paradoxo: Ao gastar mais tempo em pesquisa e planejamento, elas enviam código mais rápido e com maior qualidade.

É como o velho ditado do lenhador: "Me dê seis horas para derrubar uma árvore e passarei as primeiras quatro afiando o machado." Exceto que neste caso, o machado é um agente de IA e você está afiando com documentos de pesquisa.

Conclusão: Brownfield é Solucionável

A diferença entre equipes usando IA com sucesso em bases de código brownfield e equipes desistindo não são as bases de código com que trabalham ou os modelos que usam.

É se elas:

Pesquisam sistematicamente antes de implementar
Planejam de forma abrangente com fases claras e critérios de sucesso
Revisam pesquisa e planos, não apenas código
Mantêm disciplina de contexto ao longo do processo
Tratam especificações como código-fonte, não artefatos descartáveis

Codificação brownfield com IA não é um problema de modelo. É um problema de fluxo de trabalho. E problemas de fluxo de trabalho têm soluções de fluxo de trabalho.

As equipes que descobriram isso já estão enviando 5-10x mais código que seus pares em bases de código complexas e legadas. Não porque têm modelos melhores, mas porque construíram processos sistemáticos que funcionam com os modelos de hoje.

O futuro do desenvolvimento brownfield não é esperar por IA mais inteligente. É construir fluxos de trabalho mais inteligentes ao redor da IA que temos.

Pronto para Implementar Codificação com IA na Sua Base de Código Brownfield?

Na FMKTech, ajudamos equipes de engenharia a implementar esses fluxos de trabalho sistemáticos para desbloquear produtividade de codificação com IA em bases de código legadas do mundo real. Seja você trabalhando com monólitos de 10 anos, spaghetti de microsserviços, ou código não documentado que "apenas funciona", podemos ajudar você a:

Projetar fluxos de trabalho de pesquisa e planejamento adaptados à arquitetura da sua base de código
Construir loops de feedback de qualidade que previnem IA de enviar porcaria
Criar documentação arquitetural que torna agentes de IA eficazes
Treinar sua equipe em técnicas brownfield de IA que realmente funcionam
Navegar de projetos piloto para desenvolvimento assistido por IA pronto para produção

Não apenas consultamos—trabalhamos ao lado de seus engenheiros para implementar esses fluxos de trabalho em tarefas reais na sua base de código real. Porque a única maneira de aprender codificação brownfield com IA é fazendo.

Interessado em explorar como agentes de codificação com IA podem funcionar nos seus sistemas legados? Entre em contato conosco para discutir seus desafios específicos de base de código e como fluxos de trabalho sistemáticos podem transformar IA de frustrante para produtiva.

Para mais insights sobre implementação de agentes de IA, confira nossos outros posts:

A Revolução Ralph Wiggum: Agentes de Codificação Autônomos - Aprenda como loops infinitos e prompts simples criam código de produção
O Que São Agentes de IA? - Um guia executivo para entender agentes de IA e suas aplicações empresariais
Entendendo Agentes de IA: Arquitetura e Segurança - Mergulho técnico profundo em arquitetura de agentes de IA, padrões e desafios de segurança

Leitura Adicional

Mergulho Profundo em Fluxos de Trabalho: Engenharia de Contexto Avançada para Agentes de Codificação
Comandos Pesquisa/Plano/Implementação: Comandos Claude do HumanLayer
Estudo de Stanford: Impacto da IA na Produtividade do Desenvolvedor
Contexto da Indústria: Especificações são o Novo Código - Sean Grove na AI Engineer 2025
Técnicas Relacionadas: 12-Factor Agents - Construindo sistemas de agentes de produção
Adoção de Equipe: Comunidade AI That Works

Este artigo é baseado em experiências do mundo real de equipes enviando código de produção com IA em bases de código brownfield complexas, incluindo fluxos de trabalho detalhados do HumanLayer, resultados do projeto BAML, e aprendizados da comunidade AI That Works. Todas as técnicas são testadas em batalha em sistemas de produção de 100k+ LOC.