Codemaps - Entiende el código antes del vibe coding

• Windsurf Codemaps es una nueva herramienta de exploración de código en la que la IA crea mapas de código estructurados con anotaciones, para ayudar a los desarrolladores a comprender una base de código de forma rápida y precisa
• Mientras que las herramientas de coding con IA existentes se han enfocado en automatizar la escritura de código, Codemaps apunta a una ingeniería centrada en la comprensión y funciona sobre los modelos SWE‑1.5 y Claude Sonnet 4.5
• Muestra visualmente el flujo de funcionalidades dentro de la base de código y permite ir de inmediato a la ubicación exacta del código o revisar explicaciones de grupos de código relacionados mediante “trace guide”
• Tiene mejor conexión de contexto y eficiencia de exploración que los agentes conversacionales existentes como Cascade, y mejora el rendimiento del agente con la función de referencia @{codemap}
• La IA se posiciona no como un simple reemplazo, sino como una herramienta colaborativa que refuerza la comprensión y la responsabilidad del ingeniero

---

La importancia de entender el código y la aparición de Codemaps

• El desarrollo de software no comienza con solo programar, sino con la comprensión del problema
  • Las herramientas de IA que escriben código en lugar del desarrollador aumentan la productividad, pero también provocan una desconexión de entendimiento entre el desarrollador y el código
  • En trabajos de alta dificultad y alto valor, esta separación deriva en una ineficiencia crítica
• Cognition enfatiza que no se necesita una “IA que apaga el cerebro”, sino una IA que enciende el cerebro
• Codemaps es un mapa de código con anotaciones de IA basado en SWE‑1.5 y Claude Sonnet 4.5, una expansión de la tecnología de DeepWiki y Ask Devin

Por qué Codemaps

• Todo trabajo de ingeniería comienza con la comprensión del código, y las bases de código grandes consumen mucho tiempo en exploración y memoria
  • Los nuevos ingenieros tardan entre 3 y 9 meses en alcanzar dominio completo, y los senior dedican más de 5 horas por semana al onboarding
  • Según una encuesta de Stripe, el mantenimiento de legacy es una de las principales causas de caída de productividad
• Las herramientas existentes de coding con IA se centran en preguntas y respuestas generales, y no pueden apoyar el onboarding intensivo ni la exploración de precisión
• Codemaps fue diseñado como una herramienta de mapeo precisa basada en código para resolver estas limitaciones

Función de mapeo centrada en problemas en tiempo real

• Se ejecuta dentro de Windsurf con Cmd + Shift + C, donde se puede ingresar el objetivo de trabajo o elegir una sugerencia automática
  • Se puede elegir entre modo Fast (SWE‑1.5) o Smart (Sonnet 4.5)
  • Cada Codemap se basa en un snapshot del código y cumple con el principio ZDR
• Permite explorar la estructura del código mediante un mapa visual de nodos y, al hacer clic, ir a la ubicación exacta del código
• Con la opción “See more”, se puede abrir la trace guide para revisar en detalle la explicación de grupos de código
• Si se invoca @{codemap} dentro de Cascade para referenciar una sección específica, mejora la comprensión de contexto y el rendimiento del agente

Un enfoque contra el ‘Vibeslop’

• El “vibe coding” se ha ido deformando hacia una generación indiscriminada de código con IA, y se señala como problema el mantenimiento de código sin comprensión
• Codemaps cierra esa brecha de entendimiento al hacer que humanos e IA compartan la estructura del sistema, el flujo de datos y las dependencias
• El rol del ingeniero se mueve de autor a responsable (accountability), garantizando la calidad a través de la comprensión
• El objetivo no es solo velocidad, sino ayudar a que el ingeniero mantenga el flujo y resuelva problemas complejos con confianza
• La IA se presenta no como un simple reemplazo, sino como un medio de colaboración que potencia el trabajo de alto valor y alivia el de bajo valor

Planes a futuro

• Codemaps es el primer paso para visualizar para humanos los resultados de indexación y análisis de los agentes internos
  • Actualmente puede usarse para compartir entre equipos y para aprendizaje
  • Más adelante se planea medir con benchmarks cuánto mejora la capacidad de resolución de problemas de agentes como Devin y Cascade
• Se está evaluando la conexión entre Codemaps, funciones de anotación y la definición de un protocolo abierto .codemap
• La meta es combinarlo con la función Fast Context para evolucionar hacia una ingeniería automática de contexto en una forma legible para humanos
• Codemaps está disponible en las versiones más recientes de Windsurf y DeepWiki

[galadbran]

Cada vez que uso DeepWiki me sorprende, así que también tengo muchas expectativas con esta función.

[tested]

Ojalá también saliera en VS Code

[GN⁺]

Comentarios en Hacker News

• Después de leer esto, creo que hay varios puntos a considerar
  Esto parece ser otro producto de IA para empresas Fortune 500. Puede que no encaje tan bien con equipos pequeños o medianos
  En realidad, este tipo de herramientas de diagramas basadas en análisis estático existen desde hace mucho, y fuera de que un LLM los dibuje, no hay tanta novedad
  El onboarding no se trata simplemente de mostrar un diagrama de flujo, sino de compartir el contexto del problema que tiene el equipo. Más que el boilerplate como CRUD o MVC, es más importante explicar los patrones y restricciones particulares de nuestro equipo

  • Si se visualiza solo con análisis estático, falta flexibilidad para decidir qué mostrar
    La ventaja de las visualizaciones hechas por un LLM es que incorporan ese criterio y sentido común, por lo que resultan más intuitivas
  • Siento que hoy fui una de las personas del xkcd “Lucky 10,000”
    ¿Alguien puede recomendar herramientas de análisis estático como esta? Si es posible, mejor si son open source, y si soportan Python, Java y JavaScript (especialmente Angular), aún mejor

• Abrí Windsurf después de mucho tiempo e hice clic en “Upgrade Available”, y me llevó a esta página
  El comando indicado, sudo apt-get upgrade windsurf, en la práctica es un comando riesgoso que actualiza todos los paquetes del sistema
  Por suerte, lo resolví directamente con sudo apt-get install --only-upgrade windsurf
  De todos modos, la nueva función de Codemaps está bastante buena y vale la pena probarla

  • La sintaxis poco intuitiva de apt-get upgrade $PACKAGE es realmente extraña. Ni siquiera aparece el formato correcto en el manual
  • Dicen que el equipo vio este feedback y lo corrigió de inmediato

    - sudo apt-get upgrade windsurf
    + sudo apt-get install windsurf
    

  • Sigo sin entender cuál sería la ventaja de esa sintaxis. Es realmente confusa

• Ojalá más gente hubiera probado Windsurf
  Como ingeniero senior, alterno entre programación con agentes y programación normal, y Windsurf es una herramienta subestimada
  Cuando apareció por primera vez la función Codemaps, de verdad me dio gusto verla

  • Estoy más o menos en la misma. En mi empresa usamos Windsurf y su UX realmente es su punto fuerte
    Llevo semanas usando Codemaps y es excelente. Si aumentan mucho los cambios en el código, mantenerlo podría volverse engorroso, pero parece solucionable
  • Yo prefiero IDEs como Zed, sin inicio de sesión obligatorio ni dependencia del ecosistema
  • Después de leer esto, yo también pienso probarlo. He usado varias herramientas como el IDE de abacus.ai y claude CLI, pero todavía no encuentro un flujo de trabajo perfecto
  • Me pregunto por qué todavía nadie menciona el Copilot integrado en VSCode
    Yo armé rápidamente un prototipo SaaS con Sonnet 4, Sequential Thinking y un servidor MCP de Tavily. El precio también es razonable
  • Soy fan de Windsurf, pero últimamente me cambié por completo a Codex. El entorno en la nube es demasiado cómodo
    Windsurf también está bien, pero por su política de precios dejamos pasar una adopción a nivel de toda la empresa

• Es una idea interesante, pero si el diagrama generado no es preciso, puede terminar generando malentendidos
  Si al final una persona tiene que volver a validarlo, se desdibuja el propósito de la herramienta

  • En realidad, si no es alguien que “de verdad quiera entender el código”, el diagrama podría ser solo un entregable formal para mostrarle al jefe

• Este tipo de función es poco práctica porque solo muestra un mapa de conexiones del código sin contexto de negocio
  La IA no entiende el “por qué” de la arquitectura. Al final, creo que sigue siendo mejor leer la documentación de diseño y el código

  • Además, mucho contexto de negocio está en la cabeza de las personas. Para llegar a un nivel realmente ingenieril, la IA tendría que hacerles preguntas directamente a las personas
  • Pero si se proporciona el contexto de forma explícita, la calidad de salida del LLM sí mejora claramente
  • En el futuro, si el prompt incluye el contexto de negocio, la IA también llegará a entender ese “por qué”
  • La verdad es que en el propio código también hay bastante contexto del trabajo incorporado
    Se puede ver solo con este ejemplo de deepwiki o este enlace de Codemap
    Para depurar, de hecho ese nivel de información suele ser suficiente
  • No sé desde cuándo programar se volvió algo tan centrado en el contexto de negocio. El entendimiento técnico por sí solo también tiene suficiente valor

• Creo que este enfoque va en la dirección correcta para resolver el problema
  En lugar de crear productos de IA que funcionan a medias, es más importante hacer que la base de código sea más fácil de entender para personas y LLMs
  Este tipo de sistemas auto documentados puede reducir el desgaste del desarrollo en grandes empresas

  • Yo también combino ambos enfoques. Cuando intento entender una base de código nueva, la visualización ayuda, pero después al final lo importante es la productividad

• (Coautor) ¡Preguntas bienvenidas!
  Pueden ver este video demo de 1 minuto
  Esta fue idea de Steven, CTO de Cognition. No le gusta estar bajo los reflectores, pero esta vez de verdad lo hizo muy bien
  También pueden revisar su tuit

  • Me pregunto si hay ejemplos de que funcione bien también con bases de código grandes. En proyectos pequeños un LLM puede arreglárselas, pero el verdadero examen está en el código complejo
  • Tengo una sugerencia: estaría bien que Codemaps pudiera verse en el panel principal y no solo en la barra lateral. Ahora mismo queda demasiado angosto

• Hace 3 años hice un side project con una idea parecida
  Como fue antes del boom de los LLM, hice yo mismo un parser de AST para extraer relaciones en código Go y Java, y lo visualicé con Graphviz
  También agregué filtros basados en expresiones regulares, y fue realmente útil para entender bases de código desconocidas
  Todavía existe en packagemap.co, pero ya está bastante viejo

  • Yo hice algo parecido, pero era una visualización 3D para el lenguaje Go
    La idea era que los desarrolladores captaran la estructura del código de forma espacial y trabajaran viendo el contexto en un entorno de VR
    Hay un texto relacionado aquí

• Propuesta de función: estaría bueno que como Github Action se generara automáticamente el Codemap del repositorio, se incluyera en el README y se actualizara automáticamente en PRs importantes

• La idea de visualizar código suena genial, pero a veces existe el riesgo de “quedarse atrapado en una mala idea”
  La mayoría de los diagramas no transmiten bien el significado que pretenden y, al contrario, terminan exigiendo tiempo para interpretarlos
  En la práctica, las personas leen código o matemáticas y construyen en su cabeza su propio modelo de visualización
  Por ejemplo, si visualizo una app de Flutter y no se revela la estructura del árbol de widgets, choca con mi modelo mental
  Al final, este tipo de visualización se parece a cuando lees una novela y las escenas se forman en tu cabeza.
  Todavía no estoy seguro de si los LLM son una tecnología capaz de crear esa “película del código que quieres ver”