Research-first en Claude Code: explora repos sin romper

TL;DR

Research-first es un patrón de trabajo con agentes de código donde, antes de tocar nada, Claude Code investiga la estructura del repo, las convenciones y los tests relacionados. Después planificas el cambio y solo entonces ejecutas. En repos grandes esto reduce ediciones a ciegas, archivos huérfanos y regresiones silenciosas. La regla simple: explorar, planificar, ejecutar, en ese orden y como fases separadas.

El problema: agentes que editan antes de entender

En un repo de cinco archivos da igual el orden. Pides un cambio, el agente lo hace y revisas. En un repo con cientos de módulos, ese mismo flujo falla de formas concretas: el agente duplica utilidades que ya existen, ignora un decorador estándar del proyecto, toca un archivo marcado como deprecated o introduce dependencias que el equipo ya descartó.

La causa raíz casi nunca es el modelo. Es que le pediste ejecutar sin darle tiempo a entender. Y como Claude Code obedece, ejecuta. Por eso los repos más serios que se están publicando últimamente alrededor de harnesses de agentes empujan la misma idea: research-first. Primero investiga, luego cambia.

¿Qué es research-first?

Research-first es un workflow donde el agente realiza una fase explícita de exploración del repositorio antes de proponer o aplicar cambios. No es leer un archivo y editar otro. Es una fase separada con su propio objetivo: producir un mapa mental verificable de la zona del código que vas a tocar.

La diferencia clave frente al flujo improvisado:

Sin research-first: el agente abre el archivo que mencionaste, deduce el resto y empieza a escribir.
Con research-first: el agente devuelve primero qué módulos están implicados, qué convenciones aplican, qué tests cubren la zona y qué efectos colaterales esperar. Tú decides si esa lectura es correcta antes de seguir.

Las tres fases del flujo

El patrón se descompone en tres etapas con criterios de salida claros. Si una fase no produce su entregable, no pasas a la siguiente.

Fase	Objetivo	Entregable
Exploración	Mapear la zona del repo afectada	Lista de archivos relevantes + convenciones detectadas
Planificación	Decidir qué cambiar y en qué orden	Plan numerado con pasos atómicos y riesgos
Ejecución	Aplicar el cambio y verificar	Diff aplicado + tests pasando

Fase 1: Exploración

El objetivo aquí no es resolver el problema, es entenderlo. Un prompt útil para arrancar:

Antes de cambiar nada, investiga:
1. ¿Qué módulos tocan el flujo de autenticación?
2. ¿Qué convenciones de testing usa el repo (pytest, fixtures, mocks)?
3. ¿Qué archivos están marcados como deprecated o legacy?
Devuelve solo la respuesta. No edites código todavía.

Lo importante es la última línea. Sin ella, Claude Code tiende a saltar directo a la edición. Con ella, devuelve un informe que puedes leer en treinta segundos y validar.

Fase 2: Planificación

Con el mapa en la mano, pides un plan. No código, plan. Pasos numerados, atómicos y reversibles:

Basándote en la investigación anterior, dame un plan paso a paso
para migrar la validación de tokens al nuevo middleware.
Cada paso debe ser aplicable y testeable por separado.

Aquí descubres pronto si el agente entendió mal algo. Es mucho más barato corregir un plan que un diff de 400 líneas.

Fase 3: Ejecución

Solo cuando el plan está validado, autorizas la ejecución. Y preferiblemente paso a paso, no "haz los siete pasos". Después de cada paso, ejecutas tests y revisas.

Cómo configurar research-first en tu día a día

Tres ajustes concretos que reducen la fricción del patrón:

CLAUDE.md con convenciones del repo: si el agente sabe que usas pytest, FastAPI y arquitectura por capas, no necesita descubrirlo cada vez. Esto encaja con la idea de separar responsabilidades en arquitectura: el CLAUDE.md documenta las fronteras, el agente las respeta.
Subagente de exploración: define uno cuyo único trabajo sea investigar sin permisos de escritura. Así no hay forma de que se cuele en la fase 3 antes de tiempo.
Plan mode antes de cada cambio grande: usar el modo de planificación de Claude Code como puerta entre la fase 2 y la 3 obliga al check humano.

Aplicación práctica: migrar un módulo en un repo monolítico

Caso típico: tu repo tiene un módulo de notificaciones que se llama desde quince sitios, y quieres migrarlo a una nueva interfaz. Sin research-first, pides a Claude Code que migre el módulo y el agente empieza a tocar imports. A los diez minutos tienes tests rotos en sitios que no esperabas.

Con research-first, el flujo cambia:

Exploración: pides la lista de los quince sitios, qué firma usan y qué tests los cubren. Validas que la lista esté completa.
Planificación: pides un plan donde cada paso migre una llamada y deje el resto funcionando. Revisas el orden.
Ejecución: aplicas paso a paso. Si el paso tres rompe algo, lo revierte y replanteas, sin haber tocado los pasos cuatro al quince.

Este patrón también ayuda cuando trabajas en otras arquitecturas modulares. Si vienes de armar microservicios con Node.js y Express o de aplicar arquitectura hexagonal en Java y Spring, la fase de exploración es donde el agente confirma qué capa toca y cuál no.

En Producción

Algunas consideraciones que aparecen cuando llevas research-first más allá del proyecto personal:

Coste por sesión: la fase de exploración consume tokens. En un repo grande puedes gastar entre 10.000 y 40.000 tokens solo investigando. Compensa cuando el cambio es no trivial, no para arreglar un typo.
Caducidad del informe: el mapa que produjo el agente refleja el repo en ese momento. Si pasas tres días sin tocar la tarea y mientras tanto alguien hizo merge, vuelve a explorar antes de planificar.
Permisos por fase: en producción real, el subagente explorador no debería tener permisos de escritura. Eso fuerza la separación y evita que ejecute por accidente.
Verificación humana: el plan debe pasar por una revisión rápida tuya antes de ejecutar. No es burocracia, es el único punto donde tu juicio entra en el flujo.

Errores comunes

Error: el agente empieza a editar en la fase 1 → Causa: el prompt no prohíbe explícitamente la escritura → Solución: añade "no edites código todavía" al cierre del prompt y, si puedes, retira permisos de escritura al subagente.
Error: el plan tiene pasos no atómicos ("refactorizar el módulo X") → Causa: pediste un plan sin restricciones de granularidad → Solución: exige que cada paso sea aplicable y testeable por separado.
Error: la exploración devuelve solo lo obvio → Causa: el agente buscó por nombre de archivo en vez de por símbolo o por uso → Solución: pide explícitamente que use búsqueda de referencias y grep por función, no solo por nombre de fichero.
Error: tras ejecutar, los tests pasan pero algo se rompió en runtime → Causa: la fase 1 no incluyó tests de integración → Solución: añade explícitamente al prompt de exploración "qué tests de integración cubren esta zona".

Preguntas frecuentes

¿Research-first no es lento para tareas pequeñas?

Sí, y por eso no lo apliques siempre. Para cambios de menos de 20 líneas o tareas que tocan un solo archivo, el flujo directo gana. Research-first paga cuando el cambio cruza módulos, toca interfaces compartidas o el repo tiene más de unos cuantos miles de líneas.

¿Cómo se relaciona research-first con los subagentes?

Encajan bien. El subagente de exploración es el ejecutor natural de la fase 1: contexto aislado, sin permisos de escritura y con un objetivo único. Esto reduce el ruido en tu sesión principal y mantiene separadas la investigación y la edición.

¿Sirve research-first si trabajo con bases de datos o frontend?

Sí. En frontend, la fase de exploración mapea componentes, props compartidas y stores. En backend con DB, identifica modelos relacionados y migraciones recientes. Si estás trabajando con un ORM, la fase de exploración debería incluir el esquema actual; por ejemplo, cuando usas Prisma para gestionar bases de datos en Node.js, conviene que el agente revise el schema antes de tocar queries.

Cierre

Research-first no es una técnica avanzada, es disciplina de orden. La diferencia entre un agente de código que mete bugs y uno que aporta valor real en repos serios suele estar en si exploró antes de ejecutar. Las tres fases (explorar, planificar, ejecutar) son baratas de adoptar y caras de saltarse cuando el repo crece.

Si estás empezando con Claude Code, prueba aplicar el patrón en tu próxima tarea no trivial: bloquea la edición en la primera fase, revisa el plan antes de autorizar y ejecuta paso a paso. La sensación de control al final del cambio es notable.

¿Cómo aplicas tú la fase de investigación con agentes de código? Cuéntamelo en los comentarios o escríbeme por Twitter en @sergiomarquezp_. En el próximo post entraré en cómo encajar este patrón con worktrees aislados para probar varias rutas sin ensuciar tu rama principal.