Codemaps - Entenda o código antes do vibe coding

(cognition.ai)

22 pontos por GN⁺ 2025-11-06 | 3 comentários | Compartilhar no WhatsApp

Windsurf Codemaps é uma nova ferramenta de exploração de código em que a IA cria mapas estruturais do código com anotações, ajudando desenvolvedores a entender uma base de código com rapidez e precisão
Enquanto as ferramentas de IA para programação existentes se concentram em automatizar a escrita de código, o Codemaps tem como objetivo uma engenharia centrada na compreensão e funciona com base nos modelos SWE‑1.5 e Claude Sonnet 4.5
Ele mostra visualmente o fluxo de funcionalidades dentro da base de código e permite ir instantaneamente para a posição exata do código ou verificar explicações de grupos de código relacionados por meio do “trace guide”
Em comparação com agentes conversacionais existentes, como o Cascade, oferece maior conexão de contexto e eficiência de navegação, além de melhorar o desempenho do agente com o recurso de referência @{codemap}
A IA passa a se posicionar não como simples substituta, mas como uma ferramenta colaborativa que fortalece a compreensão e a responsabilidade do engenheiro

A importância de entender o código e o surgimento do Codemaps

O desenvolvimento de software não começa com simplesmente programar, mas com a compreensão do problema
- Ferramentas de IA que escrevem código no lugar do desenvolvedor aumentam a produtividade, mas causam uma ruptura de entendimento entre o desenvolvedor e o código
- Em trabalhos de alta dificuldade e alto valor, essa separação leva a uma ineficiência crítica
A Cognition enfatiza que precisamos não de uma “IA que desliga o cérebro”, mas de uma IA que liga o cérebro
O Codemaps é um mapa de código com anotações de IA baseado em SWE‑1.5 e Claude Sonnet 4.5, expandindo tecnologias do DeepWiki e do Ask Devin

Por que Codemaps

Todo trabalho de engenharia começa pela compreensão do código, e bases de código grandes consomem muito tempo com navegação e memorização
- Novos engenheiros levam de 3 a 9 meses para atingir plena proficiência, e profissionais seniores gastam mais de 5 horas por semana com onboarding
- Segundo uma pesquisa da Stripe, a manutenção de legados é uma das principais causas de queda de produtividade
Ferramentas atuais de IA para programação são focadas em perguntas e respostas gerais e não conseguem dar suporte a onboarding intensivo e navegação precisa
O Codemaps foi projetado como uma ferramenta de mapeamento baseada no código exato para resolver essas limitações

Recurso de mapeamento em tempo real orientado por problemas

No Windsurf, ele é executado com Cmd + Shift + C, e é possível inserir o objetivo da tarefa ou selecionar uma sugestão automática
- É possível escolher entre os modos Fast (SWE‑1.5) ou Smart (Sonnet 4.5)
- Cada Codemap se baseia em um snapshot do código e segue os princípios ZDR
Você pode explorar a estrutura do código por meio de um mapa visual de nós e, ao clicar, ir para a posição exata do código
Pela opção “See more”, é possível abrir o trace guide para ver explicações detalhadas dos grupos de código
Ao chamar @{codemap} dentro do Cascade para referenciar uma seção específica, a compreensão de contexto e o desempenho do agente melhoram

Uma abordagem contra o ‘Vibeslop’

O “vibe coding” vem se deturpando em geração desenfreada de código por IA, e a manutenção de código sem compreensão passou a ser apontada como problema
O Codemaps reduz essa lacuna de entendimento ao fazer humanos e IA compartilharem a estrutura do sistema, o fluxo de dados e as dependências
O papel do engenheiro deixa de ser o de autor para se tornar o de responsável (accountability), garantindo a qualidade por meio da compreensão
O objetivo não é só velocidade, mas também ajudar engenheiros a manter o fluxo e resolver problemas complexos com confiança
A IA é apresentada não como mera substituta, mas como um meio de colaboração que fortalece tarefas de alto valor e reduz o peso das tarefas de baixo valor

Planos futuros

O Codemaps é o primeiro passo para visualizar para humanos os resultados de indexação e análise dos agentes internos
- Atualmente, já pode ser usado para compartilhamento entre equipes e aprendizado
- No futuro, está previsto fazer benchmarks do efeito na melhoria da capacidade de resolução de problemas de agentes como Devin e Cascade
Estão sendo estudados recursos de conexão e anotação entre Codemaps, além da definição de um protocolo aberto .codemap
O objetivo é evoluir, em conjunto com o recurso Fast Context, para uma forma de engenharia automática de contexto legível por humanos
O Codemaps está disponível nas versões mais recentes do Windsurf e do DeepWiki

3 comentários

galadbran 2025-11-07

Sempre fico impressionado quando uso o DeepWiki, então também estou ansioso por esse recurso!

tested 2025-11-06

Queria que também saísse no VS Code

GN⁺ 2025-11-06

Comentários no Hacker News

Pensando melhor depois de ler este post, há alguns pontos a destacar
Isso parece mais um produto de IA para empresas Fortune 500. Talvez não se encaixe tão bem em equipes menores
Na prática, esse tipo de ferramenta de diagrama baseada em análise estática existe há muito tempo, e a novidade não parece tão grande além do fato de um LLM gerar o desenho
Onboarding não é só mostrar um fluxograma; o principal é compartilhar o contexto dos problemas que a equipe tem. Mais importante do que boilerplate como CRUD ou MVC é explicar os padrões e restrições peculiares da nossa equipe
- Se a visualização for feita só com análise estática, falta flexibilidade para decidir o que mostrar
  A vantagem das visualizações feitas por LLM é justamente trazer esse julgamento e bom senso, deixando tudo mais intuitivo
- Hoje eu também me senti como uma das pessoas do xkcd “Lucky 10,000”
  Alguém pode recomendar ferramentas desse tipo de análise estática? Se possível, seria ótimo que fossem open source e suportassem Python, Java e JavaScript, especialmente Angular
Abri o Windsurf depois de muito tempo e cliquei em “Upgrade Available”, aí fui parar nesta página
O comando indicado, sudo apt-get upgrade windsurf, na prática é um comando arriscado que atualiza os pacotes do sistema inteiro
Felizmente resolvi manualmente com sudo apt-get install --only-upgrade windsurf
De qualquer forma, o novo recurso de Codemaps parece bem legal e vale a pena testar
- A sintaxe pouco intuitiva de apt-get upgrade $PACKAGE é realmente estranha. A forma correta nem aparece no manual
- Disseram que a equipe viu esse feedback e corrigiu imediatamente
```
- sudo apt-get upgrade windsurf
+ sudo apt-get install windsurf
```
- Ainda não entendo qual é a vantagem dessa sintaxe. É realmente confusa
Queria que mais gente experimentasse o Windsurf
Como engenheiro sênior, alterno entre codificação com agentes e programação normal, e o Windsurf é uma ferramenta subestimada
Fiquei realmente feliz quando o recurso Codemaps apareceu pela primeira vez
- Estou numa linha parecida. Uso Windsurf na empresa e o UX é realmente um ponto forte
  Uso Codemaps há algumas semanas e ele é excelente. Se as mudanças no código aumentarem muito, a manutenção pode ficar trabalhosa, mas parece algo resolvível
- Eu prefiro IDEs como o Zed, sem login obrigatório nem dependência do ecossistema
- Depois de ler isto, também estou pensando em testar. Já usei várias ferramentas, como abacus.ai IDE e claude CLI, mas ainda não encontrei um workflow perfeito
- Fico me perguntando por que ainda não falaram do Copilot embutido no VSCode
  Eu criei rapidamente um protótipo de SaaS com a combinação de Sonnet 4, Sequential Thinking e servidor MCP do Tavily. O preço também é razoável
- Sou fã do Windsurf, mas ultimamente migrei totalmente para o Codex. O ambiente em nuvem é conveniente demais
  O Windsurf também é bom, mas desistimos de adotar na empresa inteira por causa da política de preços
A ideia é interessante, mas se o diagrama gerado não for preciso, ele pode acabar gerando mais confusão
Se no fim uma pessoa ainda tiver que validar tudo de novo, o propósito da ferramenta fica esvaziado
- Na verdade, se não for alguém que esteja realmente “tentando entender o código”, o diagrama pode acabar sendo só um artefato formal para mostrar ao chefe
Esse tipo de recurso mostra apenas um mapa das conexões do código sem contexto de negócio, então sua utilidade é limitada
A IA não entende o “porquê” da arquitetura. No fim, acho melhor ler a documentação de design e o próprio código
- Além disso, muito do contexto de negócio está na cabeça das pessoas. Para chegar a um nível realmente de engenheiro, a IA teria que fazer perguntas diretamente às pessoas
- Mas, se o contexto for fornecido explicitamente, a qualidade da saída do LLM melhora claramente
- No futuro, se o prompt incluir o contexto de negócio, a IA também vai entender esse “porquê”
- Na verdade, bastante contexto de domínio também está embutido no código
  Dá para ver isso só pelos exemplos do deepwiki e pelo link do Codemap
  Para depuração, esse nível de informação na prática já costuma ser suficiente
- Não sei desde quando programar virou algo tão centrado em “contexto de negócio”. Entendimento técnico por si só já tem bastante valor
Acho que essa abordagem aponta para a direção certa na resolução do problema
Em vez de criar produtos de IA que funcionam só pela metade, o mais importante é tornar a base de código fácil de entender para humanos e LLMs
Esse tipo de sistema autodocumentado pode reduzir o desgaste do desenvolvimento em grandes empresas
- Eu também combino as duas abordagens. Quando estou entendendo uma base de código nova, a visualização ajuda, mas depois a produtividade volta a ser o principal
(Coautor) Perguntas são bem-vindas!
Dá para conferir este vídeo de demonstração de 1 minuto
Esta foi uma ideia do CTO da Cognition, Steven. Ele não gosta dos holofotes, mas desta vez mandou muito bem
Veja também o tweet dele
- Fico curioso se há exemplos de funcionamento bom em bases de código realmente grandes. Projetos pequenos até vão bem com LLM, mas o verdadeiro teste é código complexo
- Tenho uma sugestão — seria ótimo se desse para ver o Codemaps no painel principal, e não só na sidebar. Do jeito que está, fica estreito demais
Há 3 anos fiz um side project com uma ideia parecida
Como isso foi antes da explosão dos LLMs, eu mesmo criei um parser de AST para extrair relações de código Go e Java e visualizar tudo com Graphviz
Também adicionei filtros baseados em regex, e isso foi realmente útil para entender bases de código desconhecidas
Hoje ainda está em packagemap.co, mas já ficou bem ultrapassado
- Eu também fiz algo parecido, mas era uma visualização 3D para a linguagem Go
  A ideia era que o desenvolvedor entendesse a estrutura do código espacialmente e trabalhasse vendo o contexto em um ambiente de VR
  Tem um texto sobre isso aqui
Sugestão de recurso: seria legal gerar automaticamente o Codemap do repositório com uma Github Action, incluir isso no README e atualizar automaticamente nos PRs principais
A ideia de visualização de código é legal, mas às vezes há o risco de “cair em ideias ruins”
A maioria dos diagramas não transmite muito bem o significado pretendido e, em vez disso, acaba exigindo tempo para interpretação
Na prática, as pessoas leem código ou matemática e constroem seu próprio modelo de visualização na cabeça
Por exemplo, se eu visualizar um app Flutter e a estrutura em árvore de widgets não aparecer, isso entra em conflito com o meu modelo mental
No fim, esse tipo de visualização é parecido com formar cenas na cabeça ao ler um romance.
Ainda não tenho certeza se LLMs são a tecnologia para criar esse “filme do código que você quer ver”