Un flujo de trabajo práctico que convirtió mi caótico proceso de desarrollo en un enfoque sistemático.
Solía empezar a programar funciones en cuanto se me ocurrían. Sin planificación. Sin documentación. Solo por intuición. ¿El resultado? Funciones a medio terminar, contexto olvidado y código que solo tenía sentido para la versión de mí mismo de ayer.
Entonces descubrí algo que lo cambió todo: un flujo de trabajo que combina el comando /init de Claude Code con las herramientas Speckit de GitHub. No se trata de una sofisticada magia de IA. Se trata de tener un sistema que realmente funciona.
Déjame mostrarte el flujo de trabajo exacto que me ayudó a lanzar funciones tres veces más rápido mientras escribía un código mejor.
El problema al que se enfrentan todos los desarrolladores
Estás mirando fijamente tu terminal. Tienes que crear una función. ¿Por dónde empiezas?
La mayoría de los desarrolladores se enfrentan a esta parálisis decisoria todos los días. ¿Empiezas a programar sin más? ¿Escribes primero las especificaciones? ¿Actualizas la documentación? La falta de un árbol de decisiones claro significa que pierdes 30 minutos solo para averiguar por dónde empezar.
Yo perdía tardes enteras dando vueltas entre diferentes enfoques. Empezaba a programar, me daba cuenta de que tenía que aclarar los requisitos, escribía algunos documentos, me confundía con la arquitectura y volvía a empezar. Y así una y otra vez, hasta que me entraba el pánico por la fecha límite.
La solución de dos capas
Esto es lo que cambió mi enfoque: comprender que la configuración del proyecto y el desarrollo de funciones operan en niveles completamente diferentes.
Piensa en CLAUDE.md como la constitución de tu proyecto. Responde a la gran pregunta: «¿En qué consiste fundamentalmente este proyecto?». Aquí se encuentran tu pila tecnológica, tus patrones de arquitectura, tus estándares de calidad y tus principales decisiones de diseño.
Speckit se encarga de la capa táctica. Responde a la pregunta: «¿Cómo construimos esta característica específica?». Cada característica tiene sus propias especificaciones, plan y desglose de tareas en una carpeta dedicada.
Esta separación resolvió mi mayor problema. Dejé de mezclar las decisiones estratégicas con los detalles de implementación. Ya no tenía que actualizar los documentos de arquitectura del proyecto cada vez que añadía un botón.
Fase uno: Inicialización del proyecto (hazlo una vez)
¿Estás empezando un nuevo proyecto? Ejecuta estos comandos una vez y nunca más:
git init my-project
cd my-project
/init
git add CLAUDE.md
git commit -m "docs: Initialize project with CLAUDE.md"El comando /init crea tu archivo CLAUDE.md. Cada sesión posterior de Claude Code lee automáticamente este archivo, lo que te proporciona un contexto coherente. Ya no tendrás que explicar la configuración de tu proyecto en cada conversación.
Tu CLAUDE.md se convierte en la única fuente de verdad. Cuando me uní a un proyecto en equipo tres meses después de la configuración, comprendí toda la arquitectura en 10 minutos con solo leer este archivo. Ese es el poder de tener el contexto del proyecto documentado correctamente.
Fase dos: Desarrollo de funciones (el trabajo real)
Aquí es donde la mayoría de los desarrolladores tienen dificultades. Saben qué función deben crear, pero no cómo desglosarla de forma sistemática. Speckit resuelve este problema con un proceso claro de cinco pasos.
Paso 1: Especificar los requisitos
/speckit.specify "Users need to login with email and password"Esto crea specs/001-email-login/spec.md con requisitos estructurados. La especificación incluye historias de usuario, requisitos funcionales y criterios de aceptación. Se acabaron las descripciones de características vagas que significan cosas diferentes para cada persona.
Paso 2: Aclarar ambigüedades
/speckit.clarify
Claude lee tus especificaciones y te hace las preguntas que no se te ocurrieron responder. «¿Debemos validar el formato del correo electrónico del lado del cliente o del lado del servidor?». «¿Qué sucede si los correos electrónicos de restablecimiento de contraseña rebotan?». Estas aclaraciones evitan horas de trabajo adicional más adelante.
Paso 3: Crear un plan de implementación
/speckit.planAquí es donde CLAUDE.md cobra importancia. Claude lee tanto el contexto de tu proyecto como las especificaciones de las características para generar un plan que siga los patrones establecidos. Si tu proyecto utiliza FastAPI y SQLAlchemy, el plan lo reflejará. Si necesitas una cobertura de pruebas del 90 %, eso aparecerá en el plan.
El plan incluye fases de implementación, decisiones técnicas y puntos de control de calidad. Cada plan se guarda como specs/001-email-login/plan.md para futuras consultas.
Paso 4: Desglosar en tareas
/speckit.implementClaude lee tu archivo de tareas y las ejecuta en orden. Hace referencia a CLAUDE.md durante toda la implementación para mantener la coherencia con los estándares de tu proyecto.
El poder de la preservación del contexto
La semana pasada creé tres funciones independientes: autenticación de usuarios, gestión de perfiles y restablecimiento de contraseñas. Sin CLAUDE.md, habría tenido que explicar mis decisiones de arquitectura tres veces. En cambio, todas las funciones siguieron automáticamente los mismos patrones porque Claude siguió leyendo el mismo contexto del proyecto.
Así es como se consigue la coherencia a gran escala. Tu décima función tiene una arquitectura tan buena como la primera, porque se aplican las mismas directrices a todo.
Cuándo actualizar CLAUDE.md
Actualiza CLAUDE.md con moderación. Solo cuando haya cambios importantes:
Cambios importantes en la arquitectura, como pasar de monolítico a microservicios. Nuevas incorporaciones tecnológicas, como añadir Redis para el almacenamiento en caché. Convenciones establecidas que afectan a todo el desarrollo futuro. Decisiones de diseño importantes que afectan a múltiples funciones. Requisitos de calidad actualizados, como elevar los estándares de cobertura de pruebas.
Yo actualizo el mío aproximadamente una vez al mes. A veces menos. La estabilidad es lo importante. CLAUDE.md es tu base, no tu diario.
Patrón: POC antes de la planificación
He aquí un patrón que ahorra muchísimo tiempo. Cuando te enfrentes a la incertidumbre sobre los enfoques técnicos, crea una prueba de concepto rápida antes de la planificación formal.
Recientemente creé un rastreador de pruebas de correo electrónico. ¿Debería utilizar la detección basada en reglas o los LLM? Dediqué dos horas a crear ambos enfoques como pruebas de concepto. El basado en reglas obtuvo una precisión del 50 %. El basado en LLM obtuvo una precisión del 85-90 %. El ganador estaba claro.
A continuación, documenté esa decisión en CLAUDE.md y ejecuté `/speckit.plan`. El plan incorporó automáticamente mi enfoque basado en LLM porque Claude leyó primero el contexto del proyecto.
Esto evita el bloqueo por exceso de análisis. Cree pequeños experimentos, tome decisiones informadas, documéntelas y, a continuación, planifique formalmente.
Patrón: desarrollo paralelo de funciones
La estructura de carpetas de especificaciones permite trabajar en paralelo. Tres desarrolladores pueden trabajar en tres funciones simultáneamente sin conflictos:
specs/
├── 001-email-login/
├── 002-password-reset/
└── 003-user-profile/
Cada función tiene archivos de especificaciones, planes y tareas aislados. La única referencia compartida es CLAUDE.md, que rara vez cambia. Esto también hace que las revisiones de código sean más claras. Todo lo relacionado con una función se encuentra en un solo lugar.
Solución de problemas comunes
Cuando las cosas salen mal, la solución suele ser obvia:
¿Claude solicita /init? Aún no ha creado CLAUDE.md. Ejecute el comando init.
¿El plan no coincide con las expectativas? CLAUDE.md está desactualizado. Actualice el contexto de su proyecto y vuelva a generar el plan.
¿Las tareas son demasiado vagas? El plan carece de detalles suficientes. Edita plan.md manualmente y vuelve a generar las tareas.
¿El comando «clarify» no funciona? Edita directamente spec.md para eliminar los requisitos poco claros marcados con [NEEDS CLARIFICATION].
¿Las pruebas fallan? Los requisitos de calidad han cambiado. Corrige el código o actualiza los estándares de calidad de CLAUDE.md.
¿Conflictos de funciones? Estás trabajando en funciones que se solapan. Impleméntalas secuencialmente o utiliza ramas separadas.
Los resultados en el mundo real
Hice un seguimiento de mi velocidad de desarrollo durante tres meses utilizando este flujo de trabajo. Las funciones que antes me llevaban cinco días, ahora me llevan dos. No porque programe más rápido, sino porque pierdo menos tiempo en falsos comienzos y debates sobre arquitectura.
La secuencia especificación-plan-tarea-implementación elimina la fatiga de la toma de decisiones. Sé exactamente qué hacer a continuación. Se acabó mirar fijamente a los editores en blanco preguntándome por dónde empezar.
Las revisiones de código se han acelerado un 40 % porque los revisores pueden leer el archivo de especificaciones para comprender el contexto. Se acabaron los largos hilos de Slack explicando lo que hace una función.
Lo que no es
Este flujo de trabajo no consiste en que la IA haga tu trabajo. Claude no escribe código perfecto a la primera. Sigues revisando todo, tomando decisiones y gestionando los casos extremos.
No se trata de un proceso rígido. Omite los pasos que no tengan sentido. Las pequeñas correcciones de errores no necesitan especificaciones completas. Usa tu criterio.
No se trata de documentar por documentar. Cada archivo tiene un propósito práctico. Las especificaciones aclaran los requisitos. Los planes guían la implementación. Las tareas permiten realizar un seguimiento del progreso. CLAUDE.md conserva el contexto.
Empieza por lo sencillo
Empieza con una función. Recorre todo el flujo de trabajo una vez. Especifica, aclara si es necesario, planifica, divide en tareas, implementa. Comprueba cómo te sientes.
El flujo de trabajo puede parecer pesado al principio. No lo es. Después de tres funciones, se convierte en algo natural. La estructura inicial da sus frutos en forma de reducción del trabajo repetido y mayor claridad de pensamiento.
Tu yo futuro te agradecerá tener una documentación clara cuando vuelvas al código seis meses después. Los miembros del equipo te agradecerán tener puntos de partida obvios al unirse a los proyectos.
Conclusión
CLAUDE.md proporciona la estrategia. Speckit proporciona las tácticas. Juntos crean un flujo de trabajo que hace que el desarrollo de software se sienta sistemático en lugar de caótico.
¿Lo mejor? Es escalable. Tanto si estás creando un proyecto paralelo de fin de semana como un sistema de producción que da servicio a millones de personas, el proceso es el mismo. Lo único que cambia es la minuciosidad con la que documentas las decisiones en CLAUDE.md.
Deja de luchar contra la pérdida de contexto. Deja de reconstruir modelos mentales en cada sesión de desarrollo. Empieza a utilizar un flujo de trabajo que conserve lo que aprendes y aumente tu eficacia con el tiempo.
¡Con esto llegamos al final de este blog! Si te ha gustado leerlo, aquí tienes otros blogs míos que te gustarán.
Gracias por leer Código en Casa.