Proyecto integrador: de principio a fin, conectando los conocimientos

📚 Navegación de la serie: El artículo anterior 47 Modo de voz (Voice) te enseñó cómo hablar tus instrucciones en lugar de escribirlas, liberando tus manos. Este artículo representa el proyecto integrador de esta guía de aprendizaje; no introduce nuevas herramientas, sino que toma un proyecto real de mayor escala y que requiere múltiples sesiones para poner en práctica las piezas que has aprendido: CLAUDE.md, permisos, MCP, subagentes, checkpoints y git, unificándolas en un flujo de ingeniería completo desde el inicio hasta la entrega.

Al analizar los proyectos desarrollados con Claude Code, se llega a una conclusión: las soluciones que realmente demuestran el valor de la herramienta no son las modificaciones rápidas de una sola línea, sino los proyectos medianos que abarcan múltiples sesiones y movilizan varias características.

Para ser específicos: desarrollar una pequeña utilidad interna desde cero puede requerir abrir unas 4 sesiones y tomar alrededor de dos horas y media. En el proceso se conecta un servidor MCP para consultar documentación, se asigna un subagente para realizar auditoría de seguridad y se emplean los checkpoints para revertir código que falló. Al final, el historial de commits de git se mantiene ordenado, explicando con claridad qué tarea resolvió cada commit. En ese punto experimentas cómo las piezas aprendidas funcionan de manera coordinada.

Esta es la transición entre "entender las funciones individuales" y "diseñar una solución real". El artículo 39 nos llevó por un ejercicio básico: una sola sesión, un solo script y ejecución local. Este artículo amplía el alcance: el proyecto es más complejo, requiere transferir el estado entre sesiones, conectar servicios externos, delegar subtareas y contar con mecanismos de reversión ante fallos. Los artículos previos explicaron el uso de cada instrumento; en este artículo asumirás la dirección para coordinarlos en una sola melodía.

Analogía: dirigir una orquesta. Has practicado el violín, los metales y la percusión; conoces el funcionamiento de cada instrumento de forma aislada. Pero saber tocarlos no es lo mismo que coordinarlos para interpretar una pieza: debes saber cuándo entra cada sección, quién tiene el papel principal y cómo mantener el ritmo. En este artículo tú eres el director: CLAUDE.md, permisos, MCP, subagentes, checkpoints y git representan tus secciones instrumentales, y te guiaremos para introducirlos en el momento adecuado del flujo de trabajo.

Al terminar este artículo, obtendrás:

• Un mapa completo del desarrollo de un proyecto mediano desde el inicio hasta la entrega, identificando dónde entra cada característica y qué problema resuelve.
• Un método para la transferencia de estado entre sesiones: cómo usar --resume, documentos SPEC y checkpoints para desarrollar una tarea compleja en varios días o sesiones de forma segura.
• Qué comandos ejecutar, qué elementos observar y qué puntos validar en cada fase crítica.
• Un proyecto real completo de referencia (una utilidad de lista de tareas por línea de comandos con almacenamiento local, pruebas y documentación) coordinando CLAUDE.md → permisos → MCP → subagentes → checkpoints → git.
• Una tabla comparativa de diferencias entre proyectos de práctica y proyectos reales para identificar y evitar fallos comunes.

---

01 Vista general: el flujo de un proyecto mediano

Antes de comenzar, analicemos el esquema del flujo de trabajo. El desarrollo de un proyecto mediano sigue la misma estructura básica, pero cada paso tiene un peso mayor y requiere coordinar diferentes características.

Este diagrama representa el desarrollo de un proyecto mediano como una línea de trabajo con ciclo de retorno: los seis pasos se ejecutan de forma sucesiva, con un punto clave indicado por la línea discontinua: un proyecto real no se resuelve en una sola sesión; tras validar una iteración, se retorna al paso de planificación para abrir una nueva sesión y continuar abordando las características de forma progresiva. El camino lineal del artículo 39 se transforma aquí en un ciclo iterativo.

Las dos diferencias principales respecto al artículo 39 que debes recordar son:

• Requiere transferir sesiones: cuando el contexto de una conversación se satura (vimos en el artículo 19 que un contexto saturado reduce la precisión del agente), conviene dar cierre a la sesión y abrir una conversación limpia para continuar. La transferencia de estado entre conversaciones es una habilidad de ingeniería necesaria.
• Requiere coordinar características avanzadas: las tareas sencillas no requieren MCP o subagentes, pero en proyectos medianos estos componentes son indispensables para consultar documentación externa, auditar el código de forma aislada o evaluar cambios con modelos específicos.

Las mejores prácticas de la documentación oficial guían este flujo:

Una vez que logre que Claude trabaje de manera efectiva en un entorno, incremente su rendimiento mediante el uso de sesiones paralelas, modo no interactivo y patrones de distribución (fan-out).

Es decir: una vez establecida una metodología de trabajo, amplía el rendimiento ejecutando sesiones en paralelo, usando procesamiento por lotes desatendido y delegando tareas a subagentes en lugar de repetir procesos de forma manual. Este artículo demuestra cómo aplicar estas técnicas de forma integrada.

En cada sección indicaremos a qué artículos previos corresponde el conocimiento aplicado para que relaciones los conceptos.

💡 Resumen rápido: El desarrollo de proyectos medianos se compone de "definición → planificación → integración → delegación → control de fallos → entrega", requiriendo además gestionar la transferencia de estado entre sesiones e integrar herramientas como MCP y subagentes a lo largo del flujo iterativo.

---

02 Definición del proyecto: estructura, guías en CLAUDE.md y permisos

Paso 1: Definición del proyecto. Relacionado con los artículos 12 y 18 (CLAUDE.md) y el artículo 20 (permisos). En tareas simples, este paso consiste en escribir unas líneas en CLAUDE.md; en proyectos medianos, es necesario establecer la guía del proyecto y las reglas de permisos básicas, ya que servirán como el cimiento para las múltiples sesiones de trabajo.

El proyecto que desarrollaremos es: una utilidad de lista de tareas por línea de comandos (todo-cli). Permitirá añadir tareas, listarlas y marcarlas como completadas, guardando la información localmente en un archivo JSON, con pruebas integradas y un archivo README de documentación. Estructuralmente es de mayor escala que un script simple: involucra múltiples archivos, persistencia de datos, suites de pruebas y requiere ser desarrollado en fases sucesivas, utilizando únicamente la biblioteca estándar de Python.

Paso 1: Inicializar la carpeta del proyecto e integrarlo a git

mkdir todo-cli && cd todo-cli && git init

¿Por qué es git la primera acción a realizar? Porque representa tu red de seguridad más sólida. Los checkpoints del agente (artículo 37) permiten revertir modificaciones en el código, pero operan a nivel local de la sesión. Contar con un commit inicial limpio en git te garantiza un punto de restauración seguro e independiente de las herramientas del agente, una regla indispensable en proyectos de gran escala.

Paso 2: Iniciar la sesión y crear el archivo CLAUDE.md

claude

En la conversación, pídele que redacte las directrices del proyecto en CLAUDE.md (es preferible definir las reglas principales de forma manual en lugar de usar /init cuando el repositorio está vacío, asegurando mayor precisión en las directrices iniciales):

Crea un archivo CLAUDE.md en la raíz del proyecto que contenga las siguientes reglas:
1. El proyecto es una utilidad de consola en Python que solo usa la biblioteca estándar, sin dependencias de terceros.
2. Los datos se guardan en el archivo todos.json en la raíz del proyecto; todas las operaciones de lectura y escritura deben centralizarse en este archivo.
3. Cada nueva función debe incluir pruebas unitarias con unittest, y las pruebas se validan ejecutando python3 -m unittest.
4. Los mensajes de commit de git deben ser en español con prefijos como feat: / fix: / docs:.

Resultado esperado: Claude propondrá la estructura, solicitará tu autorización (regulado por el control de permisos) y escribirá el archivo CLAUDE.md con las directrices. Mantén el archivo conciso; recuerda la directriz oficial:

Sea conciso. Para cada línea, pregúntese: "¿Si elimino esto, se incrementará la probabilidad de que Claude cometa un error?". Si la respuesta es no, elimínela.

Estas directrices definen decisiones de diseño del proyecto que Claude no puede asumir por su cuenta. En las sesiones de trabajo futuras, el agente leerá este archivo al iniciar, evitándote tener que repetir las instrucciones de no usar dependencias o ejecutar las pruebas en cada conversación.

Paso 3: Configurar las reglas de permisos básicas

En proyectos medianos que modifican múltiples archivos a lo largo de varias sesiones, solicitar confirmaciones recurrentes resulta molesto: "Tras diez confirmaciones repetitivas, el usuario deja de evaluar el comando y procede a autorizar sin leer." Para evitar esto, define una configuración de permisos inicial según tu escenario:

Método	Aplicación	Escenario de uso
Autorización automática	Registra comandos de confianza en /permissions (como la suite de pruebas o git status)	Para comandos recurrentes y seguros, evitando interrupciones en el flujo
Plan Mode (Modo de planificación)	Cambia de modo con Shift+Tab o inicia con claude --permission-mode plan	Para cambios de código complejos donde desees validar el diseño antes de su aplicación
Auto Mode (Modo automático)	Inicia con claude --permission-mode auto para que el filtro actúe solo ante comandos de riesgo	Para avanzar rápido en el desarrollo confiando en el alcance general del agente

Configuración de permisos recomendada para este proyecto: añade comandos recurrentes como python3 -m unittest, git diff y git status a la lista de autorización automática con /permissions; para modificaciones de código complejas, cambia a Plan Mode para validar las propuestas antes de autorizar las ediciones. Esto reduce el ruido de confirmaciones recurrentes durante la sesión.

⚠️ Advertencia sobre seguridad: Desactivar confirmaciones en modo automático agiliza el trabajo, pero delega la validación de seguridad a los checkpoints del sistema. Consulta los artículos 20 y 21 para balancear control y agilidad.

💡 Resumen rápido: La definición de un proyecto mediano requiere inicializar git, redactar un archivo CLAUDE.md conciso con las reglas de diseño y establecer la base de permisos con /permissions o Plan Mode para optimizar el flujo de confirmaciones en las conversaciones.

---

03 Planificación: redactar un documento SPEC y gestionar la transferencia de sesiones

Definido el entorno, pasamos al Paso 2: Planificación. Relacionado con el artículo 16 (exploración), el artículo 20 (Plan Mode) y el artículo 19 (gestión de contexto). En este paso se marca la diferencia respecto a proyectos sencillos: en lugar de programar a partir de una instrucción general, se redacta un documento de especificaciones técnicas (SPEC) que guía el desarrollo en las siguientes sesiones.

¿Por qué es necesario contar con un documento SPEC? Conforme aumentan las características del proyecto, las ideas generales no son suficientes; omitir la definición de flujos o formatos de datos causará problemas de integración y retrabajo durante la programación. La metodología recomendada es permitir que Claude te entreviste para detallar los requerimientos.

Paso 1: Entrevista de requerimientos y creación del documento SPEC

Cambia a Plan Mode (Shift+Tab) e introduce la siguiente instrucción:

Quiero desarrollar la utilidad de consola todo-cli para gestionar tareas guardando los datos en un JSON local.
Utiliza la herramienta AskUserQuestion para entrevistarme sobre los detalles: especificación técnica, interfaz de consola (comandos), control de excepciones (JSON dañado, campos vacíos) y decisiones de diseño.
Realiza preguntas específicas sobre aspectos de diseño que requieran definición y resume las respuestas en un archivo SPEC.md en el proyecto.

Resultado esperado: Claude te hará preguntas sobre el diseño: "¿las tareas deben tener prioridad?", "¿qué ocurre si el archivo JSON no existe?", "¿las tareas completadas se eliminan o se marcan con un estado?". Estas preguntas ayudan a estructurar el diseño del código. Una vez aclarados los puntos, generará el archivo SPEC.md con los comandos, el formato de datos y los criterios de validación.

La documentación define las características de una buena especificación:

Las especificaciones técnicas más útiles son auto-contenidas: nombran los archivos e interfaces involucrados, declaran qué aspectos están fuera de alcance y definen los pasos de validación de principio a fin.

Definir aspectos como si se permiten tareas duplicadas antes de escribir código evita tener que modificar estructuras de datos o reescribir funciones más adelante, optimizando el tiempo de desarrollo.

Paso 2: Dividir el desarrollo del proyecto en sesiones

Divide las tareas de desarrollo en bloques definidos para ser abordados en conversaciones limpias e independientes:

Sesión 1: Estructura base: organización de archivos, lectura/escritura del archivo JSON y comando "add" con pruebas.
Sesión 2: Implementación de comandos "list" y "done" con sus pruebas correspondientes.
Sesión 3: Control de excepciones (JSON dañado, entradas vacías) y ampliación de pruebas.
Sesión 4: Documentación en README, revisión general de calidad y preparación de la entrega.

Paso 3: Transferencia de estado entre conversaciones

Esta es una técnica clave en proyectos medianos. Al finalizar una fase de desarrollo, realiza las siguientes acciones para preparar la siguiente conversación:

• Limpia el contexto con /clear y reanuda con --resume: usa /clear para dar cierre a una conversación y limpiar la memoria de trabajo antes de iniciar una tarea diferente; usa claude --resume si necesitas recuperar la conversación de una fase específica.
• Usa SPEC.md como el registro de transferencia: al iniciar una nueva conversación, indícale que lea SPEC.md y el historial de git log para que el agente asimile el estado actual del proyecto de forma inmediata. Las conversaciones se limpian, pero los archivos del repositorio se mantienen en el disco.

Inicia cada nueva sesión con la siguiente instrucción de transferencia:

Lee los archivos SPEC.md y git log para entender en qué punto del desarrollo nos encontramos. No realices modificaciones de código todavía; explícame qué tareas corresponden a esta fase y si hay pendientes de la fase anterior.

No omitas esta instrucción: si inicias la segunda sesión pidiéndole que programe el comando "list" sin indicarle que lea las especificaciones, podría estructurar el formato del JSON de forma diferente a la definida en la primera sesión, causando inconsistencias de datos. Usar el archivo SPEC como punto de transferencia garantiza la consistencia del diseño.

La documentación destaca esta capacidad de persistencia:

Claude Code almacena las conversaciones localmente, por lo que no es necesario volver a ingresar el contexto de trabajo al reanudar tareas entre sesiones.

Las conversaciones históricas se guardan, pero cargarlas de forma completa consume memoria de contexto. El archivo SPEC actúa como una síntesis compacta y estructurada del estado del proyecto, permitiendo al agente asimilar el contexto en pocos segundos sin saturar el espacio de trabajo.

💡 Resumen rápido: La planificación de un proyecto mediano requiere diseñar un documento SPEC.md mediante una entrevista de requerimientos, dividir el desarrollo en sesiones independientes y usar SPEC.md junto con git log como el mecanismo de transferencia de contexto al iniciar cada nueva conversación.

---

04 Integración externa: conectando servicios de apoyo mediante MCP

Con la estructura de archivos definida y en desarrollo, entramos al Paso 3: Integración externa. Relacionado con el artículo 22 (MCP). Esta característica no es necesaria en scripts simples, pero es de gran ayuda en proyectos de mayor escala para que el agente consulte documentación de API, interactúe con bases de datos o valide cambios en GitHub de forma directa.

¿Cuándo es útil conectar un servidor MCP? La documentación oficial ofrece una regla práctica:

Conecte un servidor cuando note que copia y pega información de otra herramienta a la conversación de forma recurrente.

Por ejemplo, si al escribir pruebas en Python el agente duda sobre el uso de un método de aserción en unittest y procedes a buscarlo en el navegador para pegarle la documentación, esa es la señal para conectar un servidor MCP de documentación y permitirle realizar la consulta por sí mismo.

Analogía: conectar un cable de red a una computadora aislada. Una máquina sin conexión solo accede a sus archivos locales, requiriendo usar memorias USB para transferir información externa. Al conectar el cable de red, la máquina consulta la información que necesita de forma directa. Claude actúa inicialmente como esa máquina aislada: solo ve tus archivos locales y comandos de consola; MCP es el cable de red que le permite consultar e interactuar con servicios externos de forma directa. Puedes conectar servicios de consulta web, bases de datos o herramientas de control de código como GitHub.

Usaremos para esta práctica el servidor oficial de documentación de Claude Code (claude-code-docs). Es un servicio HTTP público que no requiere credenciales ni configuraciones complejas, ideal para familiarizarse con la herramienta.

Paso 1: Registrar el servidor MCP en el entorno

Ejecuta el comando en tu terminal de sistema (no dentro de la sesión de claude):

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Nota: Este es un servicio en la nube y requiere conexión a internet estable.

Resultado esperado: La consola confirmará el registro: Added HTTP MCP server claude-code-docs ...

Paso 2: Validar el estado de la conexión

claude mcp list

Resultado esperado: El servidor claude-code-docs debe mostrar el estado ✓ Connected en verde. Si muestra error de conexión, verifica tu acceso a internet.

Paso 3: Indicar a Claude que realice la consulta en el servidor

Inicia una sesión de claude y escribe:

Utiliza el servidor claude-code-docs para consultar la definición y la estructura de configuración de los subagentes en Claude Code.

Resultado esperado: Claude solicitará tu confirmación la primera vez que intente comunicarse con el servidor MCP (un control de permisos del artículo 22). Autoriza la comunicación. Claude realizará la consulta y mostrará la definición en la conversación, indicando la llamada al servidor claude-code-docs al lado del resultado, lo que confirma que la información proviene del recurso externo en lugar de su memoria general.

Considera otras integraciones de servidores MCP útiles en proyectos reales:

Recurso externo	Servidor MCP	Capacidad del agente
Repositorio de GitHub	GitHub MCP	Leer issues, comentar en PRs o crear reportes del estado de los commits
Base de datos del proyecto	PostgreSQL / MySQL MCP	Consultar esquemas de datos o verificar registros (se recomienda usar credenciales de solo lectura en desarrollo)
Herramientas de diseño	Figma MCP	Leer variables de diseño o adaptar los estilos de la interfaz de consola

Ten presente la advertencia de seguridad de la documentación al integrar servidores de terceros (artículos 21 y 22):

Valide que el servidor MCP sea de confianza antes de conectarlo. Los servidores que leen contenido externo podrían exponer al agente a riesgos de inyección de instrucciones.

Los servidores MCP ejecutan código de terceros que Anthropic no audita. Utiliza servidores oficiales de proveedores de confianza y restringe el acceso de bases de datos a perfiles de solo lectura para minimizar riesgos. Además, recuerda que cada servidor conectado consume recursos de tu contexto de conversación; al terminar el proyecto, remueve las conexiones que no utilices con claude mcp remove claude-code-docs.

💡 Resumen rápido: MCP conecta a Claude con recursos externos. Utilízalo si te encuentras copiando información externa a la conversación. Configura el servidor con claude mcp add, valida con mcp list y autoriza sus llamadas en la conversación. Usa conexiones seguras y remueve los servidores inactivos al finalizar.

---

05 Delegación: usar subagentes para analizar código y realizar auditorías de calidad

Con el código base del proyecto desarrollado y expandiéndose a múltiples archivos, entramos al Paso 4: Delegación. Relacionado con el artículo 23 (subagentes) y el artículo 29 (equipos de agentes). Esta característica permite mantener la conversación principal limpia de logs y archivos extensos, y realizar revisiones de calidad objetivas.

Evitar saturar el contexto principal usando subagentes

En la tercera sesión de desarrollo del proyecto todo-cli, la cantidad de funciones y archivos de prueba se incrementa. Si deseas analizar en qué secciones del código se realizan operaciones de lectura o escritura en el archivo todos.json, evita pedirle al agente principal que abra y lea todos los archivos en la conversación, ya que saturará la memoria del contexto con el código fuente del proyecto, reduciendo la precisión para las tareas siguientes. Delega esta tarea de análisis a un subagente:

Asigna un subagente para identificar en qué archivos y funciones de todo-cli se realizan operaciones de lectura o escritura en todos.json. Indícale que reporte solo el resumen de los archivos y funciones identificados, sin incluir el código fuente de los archivos.

Resultado esperado: El subagente se ejecutará en una conversación de contexto independiente para analizar el repositorio, y devolverá únicamente el resumen estructurado a la conversación principal. La documentación oficial destaca este beneficio:

Dado que el contexto de conversación es una restricción física, los subagentes representan una herramienta muy potente. Se ejecutan en contextos independientes y devuelven resúmenes compactos.

Analogía: encargar a un ayudante que busque un dato en el archivo general. En lugar de traer archivadores y carpetas a tu mesa de trabajo (saturando tu contexto), el ayudante busca el dato en el archivo (contexto independiente) y regresa a tu mesa con una nota que contiene la respuesta exacta, manteniendo tu mesa limpia y ordenada. El subagente actúa como ese ayudante.

Evaluar el código con una revisión independiente

Al finalizar la programación, evita pedirle al mismo agente que escribió el código que realice la revisión de calidad, ya que tenderá a pasar por alto sus propios fallos de lógica. Es preferible iniciar una conversación de subagente limpia para que evalúe el código de forma objetiva. La documentación oficial explica el beneficio de esta práctica:

Un revisor que se ejecuta en un contexto de subagente limpio solo tiene acceso a los cambios del diff y a los criterios que le asignes, evaluando el código de forma objetiva sin verse influenciado por el proceso de razonamiento que generó el código.

Puedes ejecutar el comando nativo /code-review para iniciar una revisión automatizada de los cambios actuales en un subagente independiente:

/code-review

También puedes estructurar una instrucción personalizada para guiar al revisor indicando los puntos de control específicos:

Asigna un subagente para revisar los cambios actuales en comparación con SPEC.md: valida si se cubren los casos límite definidos, si las pruebas unitarias cubren las funciones añadidas y si se modificaron archivos fuera de alcance. Reporta solo fallos lógicos o de requerimientos, omitiendo observaciones de estilo.

Al desarrollar todo-cli, este flujo suele identificar detalles omitidos, como haber controlado la ausencia del archivo JSON pero no el caso de que el archivo contenga datos JSON corruptos o no válidos. La revisión en un contexto independiente ayuda a detectar estas excepciones. La documentación sugiere definir el alcance de la revisión:

Indique al revisor que reporte fallos de lógica o desvíos en los requerimientos del proyecto, tratando las sugerencias estéticas como observaciones opcionales.

Nota sobre equipos de agentes: La característica experimental de Teams (artículo 29, sujeta a cambios) permite automatizar este proceso estructurando una mesa de trabajo donde un agente programa y otro audita de forma continua. Para proyectos medianos, iniciar subagentes de forma manual para análisis específicos es suficiente.

💡 Resumen rápido: Delegar tareas complejas a subagentes previene la saturación del contexto principal (ya que analizan en entornos aislados y devuelven resúmenes) y permite realizar revisiones de código objetivas usando /code-review en contextos independientes.

---

06 Gestión de fallos: restaurar estados mediante checkpoints y git

A medida que el proyecto crece en complejidad, es común encontrarse con modificaciones de código que rompen la lógica o generan errores en las pruebas. El Paso 5 es la Gestión de fallos. Relacionado con el artículo 37 (checkpoints). En proyectos de gran escala, este control es clave para evitar perder el progreso.

Evita este error común: intentar corregir un código dañado pidiéndole al agente que aplique parches sobre el desorden actual.

Si el diseño o la refactorización han salido mal, intentar corregirlos aplicando más modificaciones en la misma sesión suele complicar la lógica, ya que el agente intentará solucionar el problema arrastrando el contexto y los errores previos. La mejor práctica es restaurar el código a un punto estable conocido y replantear la instrucción con mayor claridad. Dispones de dos niveles de restauración:

Nivel de restauración	Herramienta	Punto de restauración	Escenario recomendado
Nivel local	Checkpoints (/rewind o doble Esc)	El estado del código previo a la última interacción de Claude	Para deshacer cambios menores recientes dentro de la sesión actual
Nivel de repositorio	Git (git restore . o git reset --hard)	El último commit registrado en el historial de git	Para deshacer refactorizaciones extensas o cambios que abarcan múltiples sesiones

El comando /rewind te permite abrir la interfaz de checkpoints de la sesión para deshacer modificaciones en el código, el historial de conversación o ambos. Ten en cuenta la advertencia oficial sobre los checkpoints:

Los checkpoints solo registran las ediciones de archivos realizadas por Claude en la sesión activa; no rastrean cambios realizados por comandos de consola (Bash) ni reemplazan el control de versiones de git.

Por ello es indispensable registrar commits en git de forma frecuente. Dado que los checkpoints solo actúan en la sesión activa, si el desarrollo abarca varias conversaciones o ejecuta comandos del sistema, git representa el único punto de restauración confiable para el proyecto. En el desarrollo de todo-cli, si una refactorización compleja del formato del JSON afecta a múltiples archivos y altera la base de datos de pruebas, ejecutar git reset --hard te permite regresar al commit estable previo en pocos segundos, eliminando el desorden de forma segura.

Tras restaurar el código, analiza qué causó la desviación en la propuesta del agente; comúnmente se debe a instrucciones ambiguas o falta de restricciones en la solicitud (visto en el artículo 15). Añade las reglas necesarias (por ejemplo, "refactoriza la función de guardado sin alterar la estructura de los campos de fecha en el JSON") antes de volver a solicitar la modificación.

💡 Resumen rápido: Ante modificaciones de código fallidas, restaura el entorno a un punto estable conocido en lugar de aplicar parches sobre el error. Usa /rewind para cambios recientes de la sesión y git para restauraciones estructurales. Registra commits frecuentes para asegurar puntos de restauración válidos.

---

07 Proyecto de referencia: desarrollo de todo-cli paso a paso

Pondremos en práctica el flujo de desarrollo creando la utilidad todo-cli en tu máquina local. Sigue las instrucciones paso a paso para experimentar la integración de las herramientas.

Requisitos: Python 3 instalado en tu sistema local y una sesión activa de Claude Code autenticada con cuenta de Claude.ai.

Paso 1: Inicializar el entorno de desarrollo (Definición del proyecto)

Ejecuta en tu terminal de sistema:

mkdir todo-cli && cd todo-cli && git init && claude

En la conversación con Claude, escribe la instrucción para definir las reglas de CLAUDE.md:

Crea un archivo CLAUDE.md en la raíz del proyecto. Debe establecer que este es un proyecto de Python sin dependencias de terceros, que guarda los datos en todos.json en la raíz, que cada función requiere pruebas unitarias en unittest que se validan con "python3 -m unittest", y que los commits de git deben ser en español con prefijos como feat: / fix: / docs:.

Resultado esperado: Claude escribirá el archivo CLAUDE.md con las reglas y te lo reportará en la conversación. Sal de la sesión (/exit o Ctrl+C dos veces) para agregar la suite de pruebas a la lista de autorización automática:

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

(Nota: añadimos el mcp de docs para consultas durante el ejercicio). Iniciamos claude de nuevo para proceder.

Paso 2: Crear las especificaciones técnicas (Planificación)

Cambia a Plan Mode (Shift+Tab) en la sesión y escribe:

Diseña el documento SPEC.md para la utilidad todo-cli. Debe detallar la estructura del JSON todos.json (id, task, completed), y el comportamiento de los comandos de consola: todo.py add "<tarea>" y todo.py list. Describe los casos límite y define los pasos de validación. No programes el código todavía, solo genera la especificación.

Resultado esperado: Claude creará el archivo SPEC.md detallando la estructura del JSON, los comandos a soportar y los criterios de aceptación para las pruebas. Valida que el documento esté en la raíz del proyecto.

Paso 3: Implementar la base y el comando "add" (Programación y confirmaciones)

Regresa a la sesión interactiva y pídele que inicie la programación:

De acuerdo con SPEC.md, implementa la estructura base de lectura/escritura de todos.json en todo.py, el comando "add" para añadir tareas, y la suite de pruebas unitarias correspondiente en test_todo.py. Ejecuta las pruebas al finalizar para confirmar la validez del código.

Resultado esperado: Claude creará los archivos todo.py y test_todo.py mostrando los diffs de edición en la pantalla. Solicitará tu aprobación para crear y modificar los archivos. Tras escribir el código, ejecutará la suite de pruebas unitarias y te mostrará el resultado en la consola.

Paso 4: Validar la suite de pruebas y el funcionamiento manual (Verificación)

Verifica que las pruebas unitarias muestren un estado correcto:

python3 -m unittest

Resultado esperado: La consola debe reportar la ejecución de las pruebas con estado OK al final.

Prueba el funcionamiento del script agregando tareas de forma manual:

python3 todo.py add "Configurar reglas de permisos"
python3 todo.py add "Realizar el proyecto integrador"

Abre el archivo todos.json creado en la raíz del proyecto para validar que las tareas se hayan guardado en el JSON local con la estructura definida (campos id, task y completed).

Paso 5: Implementar el comando "list" (Iteración)

Pídele en la sesión que desarrolle el comando para listar tareas:

Implementa el comando todo.py list para mostrar en consola las tareas registradas en todos.json indicando su ID, descripción y estado (si está completada o pendiente). Añade las pruebas unitarias correspondientes en test_todo.py y ejecútalas.

Resultado esperado: Modificará todo.py y test_todo.py para añadir el comando. Ejecutará las pruebas mostrando el estado OK.

Valida el funcionamiento en la consola:

python3 todo.py list

Resultado esperado: Se mostrarán las tareas agregadas en el paso anterior con sus respectivos IDs y estado pendiente.

Paso 6: Auditar la calidad del código (Revisión)

/code-review

Resultado esperado: Se iniciará un subagente para evaluar los cambios del diff en comparación con SPEC.md, reportando hallazgos o confirmando la consistencia del código.

Paso 7: Registrar el commit en git (Entrega)

Muestra el estado de los archivos modificados con git status y realiza el commit de los cambios utilizando una descripción clara en español con el prefijo "feat:".

Resultado esperado: Claude ejecutará git status y git commit tras tu aprobación de los permisos correspondientes.

Nota de seguridad: Recuerda que git push no debe ser ejecutado por Claude; realiza la sincronización con tu repositorio remoto de forma manual en tu terminal de sistema al concluir.

Completar este ejercicio de referencia te da el flujo de desarrollo mediano: estableciendo las reglas, estructurando la especificación, iterando en fases sucesivas, validando con pruebas y registrando la entrega de forma ordenada.

💡 Resumen rápido: El proyecto de referencia abarca: definir CLAUDE.md y permisos → generar SPEC.md en Plan Mode → implementar código y pruebas de forma incremental → validar con pruebas unitarias y pruebas manuales → auditar con /code-review → confirmar el commit local de git.

---

08 Comparativa de metodologías de trabajo

El desarrollo de proyectos reales se diferencia de los ejercicios de práctica en la rigurosidad aplicada a cada fase del flujo. Comparamos los comportamientos en ambos escenarios:

Fase del desarrollo	Práctica o ejercicios de juguete	Proyectos reales de ingeniería
Cimientos	CLAUDE.md omitido o con reglas genéricas de plantillas	CLAUDE.md y reglas de permisos definidas antes de escribir código para estructurar el desarrollo
Diseño	Programar directamente a partir de la idea del momento	Entrevista de requerimientos para plasmar un documento SPEC.md con los casos límite y flujos
Conversaciones	Mantener una sola conversación extensa sin limpiar contexto	Uso de conversaciones independientes por tarea, limpiando memoria con /clear y usando el SPEC para transferencia
Servicios	Pegar información de páginas externas manualmente	Conexión de servidores MCP oficiales para consultar APIs o bases de datos de forma directa
Calidad	Confiar en el reporte del mismo agente de desarrollo	Uso de subagentes y /code-review independientes para auditorías de lógica
Respaldo	Modificar código dañado aplicando más cambios en la sesión	Restauración de código con /rewind o git, controlando el progreso con commits frecuentes
Entrega	Finalizar sin documentar o automatizando el push remoto	Validación exhaustiva del diff local y confirmación de commits estructurados, gestionando el push manualmente

Adoptar la metodología de proyectos reales reduce las fallas de coherencia del agente, evita la saturación del contexto de conversación y proporciona un historial de cambios ordenado y mantenible a largo plazo.

💡 Resumen rápido: Los proyectos reales requieren definir reglas previas, diseñar especificaciones claras, segmentar conversaciones, usar MCP para datos externos, auditar de forma independiente y controlar el historial con commits frecuentes, a diferencia de la flexibilidad de los proyectos de práctica.

---

09 Resumen

En este artículo hemos integrado los conocimientos de Claude Code en un flujo de desarrollo de proyecto mediano, coordinando el diseño, la automatización y el control de calidad.

Repasemos las directrices del proyecto integrador:

Fase del flujo	Herramienta clave	Objetivo de ingeniería
Definición	CLAUDE.md y reglas de permisos	Establecer las normas de diseño y autorizaciones para las sesiones de desarrollo
Planificación	Documento SPEC.md	Detallar la especificación técnica de la solución para transferir contexto entre conversaciones
Integración	Servidores MCP	Conectar recursos externos necesarios de forma directa, cuidando las reglas de seguridad
Delegación	Subagentes y /code-review	Optimizar el contexto principal delegando análisis extensos y revisiones de código a agentes independientes
Gestión de fallos	Checkpoints (/rewind) y git	Mantener una política de restauración de código estable apoyada en commits frecuentes
Entrega	Commits de git y push manual	Consolidar la entrega con commits explicativos, manteniendo el control de envío a producción de forma manual

Ahora puedes:

• Coordinar el desarrollo de proyectos de software medianos controlando las fases del flujo técnico.
• Estructurar documentos de especificación técnica interactuando con el agente.
• Transferir el contexto del estado del proyecto de forma limpia entre diferentes conversaciones de trabajo.
• Conectar y operar servidores MCP para enriquecer la capacidad de información del agente.
• Delegar auditorías de calidad a subagentes independientes para asegurar la lógica del código.
• Aplicar políticas de restauración de código estables ante fallos de refactorización.

Coordinar estas herramientas de forma integrada te permite usar Claude Code como un asistente de ingeniería confiable para estructurar tus soluciones de desarrollo.

---

El siguiente artículo es el 49 "Mejores prácticas". Hemos consolidado el flujo técnico de un proyecto; en el próximo artículo resumiremos las directrices de uso, recomendaciones de prompts, estrategias de ahorro de API y consejos de seguridad de la guía en una lista de mejores prácticas de referencia rápida.

---

Lecturas recomendadas

• Metodologías de trabajo cotidianas: exploración, bugs y refactorización
• Referencia de comandos de la CLI
• Integración de plugins en el entorno