He estado usando Claude Code para construir un agente de IA full-stack. En el camino, noté algo: cada vez que planificaba una nueva funcionalidad, hacía lo mismo manualmente. Preparar el contexto del código, investigar la documentación, dirigir la dirección, generar un plan.
Funcionaba. Pero era repetitivo. Así que convertí todo el flujo de trabajo en comandos reutilizables (slash commands).
Aquí está cómo lo hice y lo que aprendí.
El Flujo de Trabajo Manual Que Funcionaba
Antes de automatizar cualquier cosa, planificaba funcionalidades a través de una conversación de varios pasos con Claude. Se veía así:
- Preparar el código - cargar todo el contexto del proyecto
- Explorar opciones - "¿cuáles crees que deberían ser nuestros próximos pasos?"
- Dirigir la dirección - "no estoy de acuerdo, hagamos X en su lugar"
- Investigación profunda - "lee la documentación de PydanticAI, mira el código fuente"
- Generar un plan - llenar una plantilla estructurada con todo ese contexto
- Revisar y refinar - "¿tienes esos riesgos en el plan?"
Los planes que salían de esto eran excelentes. Lo suficientemente detallados para que otro agente de IA pudiera ejecutarlos sin hacer preguntas. Rutas de archivos específicas, números de línea, patrones de código, trampas, comandos de validación.
Pero cada funcionalidad requería los mismos 6 pasos. El mismo baile, diferente canción.
Lo Que Ya Tenía
Tenía una plantilla de plan - un archivo markdown estructurado que definía cómo se ve un buen plan. Secciones para descripción de la funcionalidad, historias de usuario, referencias de contexto, tareas paso a paso, estrategia de pruebas, comandos de validación. Era sólida.
El problema: la plantilla era solo un formulario en blanco. No hacía ninguna investigación. Asumía que yo ya había descifrado todo y solo necesitaba un lugar donde escribirlo.
La Idea Clave
La fase de investigación es lo que hace buenos los planes, no la plantilla.
Cuando miré mis mejores planes, la calidad no venía de la estructura de la plantilla. Venía de lo que pasaba antes de llenarla:
- Buscar en el código implementaciones similares
- Leer documentación de librerías externas para entender APIs específicas
- Extraer patrones reales de código con números de línea
- Identificar trampas que morderían durante la implementación
La plantilla era solo el contenedor. La investigación era el contenido.
Construyendo el Comando
Construí un comando /plan-feature que automatiza la investigación y llena la plantilla. Esta es la estructura:
Fase 1: Entender la Funcionalidad y Enfocar la Investigación
El comando analiza lo que le des - puede ser un prompt detallado con URLs y restricciones, o puede ser una línea. Luego determina qué investigar revisando tres fuentes:
- Tu entrada - cualquier URL, nombre de librería o restricción que hayas mencionado
- El manifiesto del proyecto - ¿qué dependencias toca esta funcionalidad?
- CLAUDE.md - ¿qué tecnologías y documentación referencia el proyecto?
Este es el paso que hace que incluso un prompt vago como "agregar búsqueda semántica" produzca buena investigación. El comando ya sabe que el proyecto usa PydanticAI, PostgreSQL y SQLAlchemy porque leyó la configuración.
Fase 2: Investigación en Paralelo
Dos agentes corren simultáneamente:
El agente de código busca implementaciones similares, mapea puntos de integración y extrae patrones - convenciones de nombres, manejo de errores, logging, pruebas, todo. Con rutas de archivos y números de línea.
El agente de investigación externa trabaja con la lista de objetivos de la Fase 1. Obtiene las URLs que proporcionaste, encuentra documentación de librerías para las funcionalidades específicas que necesitas, e identifica trampas y problemas de versión.
Fase 3: Llenar la Plantilla
Toda esa investigación alimenta la plantilla estructurada. Cada sección se llena con datos específicos, no con marcadores genéricos. El resultado va a un archivo de plan que otro agente puede ejecutar de arriba a abajo.
Lo Que Aprendí
Tu dirección va en los argumentos. El flujo manual era poderoso porque yo tomaba decisiones a mitad de la conversación - "usa esta API, no esa", "lee esta página específica de la documentación." En la versión automatizada, todo eso se carga de antemano en los argumentos del comando:
/plan-feature Agregar Google Gemini como proveedor de LLM.
Leer ai.pydantic.dev/models/ para patrones de proveedores.
Extender _build_model() en agent.py. Seguir el patrón
existente de switch Ollama/Anthropic.
Más contexto de entrada, mejor plan de salida. Pero incluso una descripción básica de la funcionalidad funciona porque el comando sabe cómo encontrar contexto que no proporcionaste.
No re-preparar. También tengo un comando /prime que carga todo el contexto del código. El comando de plan asume que eso ya pasó y no pierde tiempo re-explorando. Sabe lo que tus herramientas ya hicieron.
La plantilla es el mecanismo de control. Cada fase de investigación se mapea a secciones específicas de la plantilla. Esto evita que el agente divague - sabe exactamente qué está tratando de llenar.
La portabilidad importa. Construí estos comandos para funcionar en diferentes proyectos, no solo en el que estaba construyendo. El comando prime descubre el toolchain desde archivos de manifiesto en vez de codificar rutas. El comando de plan lee cualquier CLAUDE.md y configuración de proyecto que exista.
Los Comandos
Estoy corriendo dos versiones en paralelo para ver cuál produce mejores planes:
v1 sigue el enfoque del instructor - 6 fases explícitas, preguntas de clarificación, esqueleto de plantilla desde el inicio.
v2 es la mía - 3 fases, sin preguntas (inferir del contexto), enfoque de investigación desde el manifiesto del proyecto, subagentes en paralelo, y una sección de riesgos/mitigaciones que la versión del instructor no tiene.
Ambas usan la misma plantilla de salida. La diferencia es cómo recopilan la información para llenarla.
Pruébalo Tú Mismo
Si estás usando Claude Code, el flujo de trabajo es:
- Crea un
CLAUDE.mden tu proyecto con tus convenciones y stack - Construye un comando
/primeque cargue el contexto de tu código - Construye un comando
/plan-featureque investigue y llene una plantilla de plan - Carga tu criterio de antemano en los argumentos
El objetivo no es eliminar tu pensamiento del proceso. Es dejar de repetir las partes mecánicas para que puedas enfocarte en las decisiones que realmente importan.
Este es el mismo tipo de pensamiento sistemático que aplico al construir sitios web para contratistas. Si tienes curiosidad sobre quién está detrás de esto, conoce mi historia.