La primera tarea real empieza con lo que dejas preparado antes de ella

Módulo 9 · Capstone · Lección 1 de 4

Al terminar esta lección podrás preparar un proyecto de cliente para un refactor multiarchivo, escribir un CLAUDE.md que siga siendo válido durante todo el proyecto y tomar la decisión de orquestación en paralelo con una justificación clara.

Dónde estás

El piloto está activo y el entorno está limpio. Ahora llega el primer ejercicio real.

El Día 3 de una activación de 30 días parece engañosamente simple desde fuera.

La cohorte ya está en marcha. La instalación salió bien, lo que significa que la checklist previa al kickoff hizo su trabajo. Lo que el equipo aprende con el primer ejercicio depende menos de la tarea en sí y más de lo que dejas preparado antes de que ejecuten un solo comando. Un CLAUDE.md al que le falta contexto clave, un alcance de configuración mal definido o un modelo de permisos demasiado abierto: cualquiera de estos factores moldeará la primera sesión de formas que luego cuestan más de deshacer, una vez que el equipo ha formado hábitos alrededor de ellos.

Preparación

Cuatro cosas que conviene dejar bien antes de que alguien ejecute un comando

1. Confirma qué alcance de configuración está activo. Claude lee la configuración desde cuatro lugares, y cada uno tiene un peso distinto: la configuración gestionada (managed settings) está en la parte superior y nada de lo que está por debajo puede sobrescribirla. Para un piloto, conviene que el alcance de proyecto haga el trabajo: la configuración del equipo se aplica, pero cada desarrollador puede ajustar lo que le corresponde. Si managed-settings.json ya está desplegado, vale la pena comprobar que no esté sobrescribiendo silenciosamente nada de lo que vas a configurar a nivel de proyecto.

2. Escribe el CLAUDE.md del proyecto. Es el contexto que Claude lee al inicio de cada sesión. El principio que se sostiene en todos los proyectos es simple: escribe lo que, de otro modo, volverías a explicar cada vez. Restricciones de arquitectura, el framework de testing, qué archivos Claude no debe tocar. Lo específico gana a lo general aquí: “no modifiques archivos en /billing/legacy/” es útil; “ten cuidado con el código legado” no lo es.

3. Define el modelo de permisos. Deny se evalúa primero, luego ask y después allow. Para un refactor del Día 3, poner las escrituras de archivos en modo ask merece la pena, no porque no confíes en la herramienta, sino porque la confirmación visible genera confianza en el equipo sobre lo que está ocurriendo. Bloquea cualquier directorio que quede fuera del alcance de este ejercicio.

4. Elige el estilo de salida. El estilo Default funciona bien para la iteración del Día 3: eficiente, preciso y sin comentarios adicionales. Si el equipo va a revisar los cambios en conjunto y quiere entender qué decidió Claude y por qué, Explanatory añade por cada salida una sección de insights que explica las decisiones de implementación. Configúralo explícitamente: el estilo adecuado para la sesión es un detalle pequeño que marca una diferencia notable.

Orden de evaluación de los permisos:

flowchart LR
    A["1 · Deny (se evalúa primero)"] --> B["2 · Ask (pide confirmación)"] --> C["3 · Allow"]

Ejecución

Un refactor multiarchivo es el primer buen argumento a favor de la orquestación en paralelo

Cuando el refactor abarca módulos independientes, ejecutarlos en secuencia es desperdiciar tiempo, y el equipo del cliente lo notará.

El patrón que funciona aquí es el mismo de la auditoría de seguridad con tres agentes del módulo de Extensibilidad: un orquestador lanza subagentes, cada uno trabaja un módulo aislado y los resultados vuelven al orquestador. La propiedad que lo hace fiable es el aislamiento de contexto. Cada subagente ve solo lo que necesita para su tarea específica, así que un fallo en un módulo no se propaga a los demás y el orquestador se mantiene limpio durante todo el proceso. Conviene nombrarlo explícitamente con el equipo del cliente el Día 3: es una de las cosas que cambia su forma de pensar sobre la escala.

flowchart TD
    A["Orquestador: coordina, no refactoriza"] --> B["Subagente 1: módulo A"]
    A --> C["Subagente 2: módulo B"]
    A --> D["Subagente N: módulo N"]
    B --> E["Resultados vuelven al orquestador"]
    C --> E
    D --> E

Conviene tener presente

El orquestador no refactoriza: coordina. Cada subagente ve solo su módulo.

Contexto del proyecto

Cuatro campos que evitan volver a explicar lo mismo en cada sesión

Un CLAUDE.md bien configurado se vuelve invisible: simplemente funciona. Uno demasiado vago o escueto se convierte en un costo en cada sesión.

Campo	Qué incluir
01 · Restricciones de arquitectura	Lo que Claude no debe cambiar: patrones de importación, estructura de archivos, propiedad de carpetas. Si hay módulos que solo ciertos equipos deben tocar, indícalo explícitamente. La orientación vaga se ignora.
02 · Framework de testing	Cómo se escriben los tests, cómo se ejecutan y qué aspecto tiene una suite que pasa. Si hay tests inestables conocidos, nómbralos aquí. Si no, Claude perseguirá fallos que ya existían antes de que tocara nada.
03 · Convenciones de código	Patrones de nombres, estándares de formato, reglas de linting. Cuanto más específico, más útil: “usamos camelCase para variables y PascalCase para componentes” es mejor que “sigue las convenciones estándar”.
04 · Rutas fuera de límites (off-limits)	Archivos y directorios que Claude no debe tocar durante este ejercicio. Explica el motivo cuando puedas: ayuda al equipo a entender el límite, no solo a respetarlo.

Comprueba tu comprensión

El CLAUDE.md ya está listo. Ahora hay que delimitar el refactor.

Escenario · Día 3

El repositorio del cliente tiene tres módulos: autenticación, capa de API y un módulo legado de facturación (billing) con una suite de tests inestable conocida. El equipo quiere ejecutar el refactor en los tres en paralelo para ahorrar tiempo. ¿Cuál es la decisión correcta?

• A · Ejecutar los tres módulos en paralelo. Un subagente por módulo. Máximo rendimiento y el equipo puede revisar los tres resultados juntos.
• B · Ejecutar autenticación y API en paralelo, y retener billing. Dos subagentes para los módulos estables. Billing se ejecuta de forma secuencial después de que el equipo revise la suite de tests.
• C · Ejecutar los tres en secuencia. La orquestación en paralelo es una capacidad del Día 2, no del Día 3. Mantenlo simple para el primer ejercicio.
• D · Empezar por billing. Corregir primero los tests inestables y, una vez que la línea base esté limpia, ejecutar el refactor completo en paralelo.

Ver respuesta

B es la respuesta correcta, y el motivo importa. El aislamiento de contexto hace que cada subagente falle de forma independiente, lo que suena ideal hasta que la línea base no es fiable. Con una suite de tests inestable en billing, no puedes saber si los cambios del subagente rompieron algo o si los tests ya estaban rotos antes de que los tocara. Autenticación y API pueden ejecutarse en paralelo sin riesgo. Billing necesita una pasada secuencial después de que hayas revisado la suite de tests con el equipo. La opción D no es errónea como instinto, pero corregir los tests de billing antes de que ocurra cualquier refactor es un compromiso mayor del que el Día 3 puede asumir.

Ideas clave

El entorno estaba bien. Ahora sí puede empezar el trabajo.

• Configuraste el CLAUDE.md, confirmaste el alcance de configuración y tomaste la decisión de orquestación en paralelo.
• El CLAUDE.md debe contener lo que volverías a explicar en cada sesión, con restricciones concretas en lugar de advertencias vagas.
• Los permisos se evalúan en este orden: deny, después ask y por último allow.
• Un refactor multiarchivo es el primer caso natural para la orquestación en paralelo, siempre que la línea base sea fiable.
• El primer ejercicio funcionó porque la base estaba bien preparada, no porque el comando fuera ingenioso.

Para el Día 8 llegan datos de uso y la curva de adopción del equipo empieza a verse. La lección 9.2 cubre la generación de tests, la lectura de las primeras señales y cuándo intervenir.

Siguiente: Ejercicio de generación de tests y depuración