Este es el flujo de trabajo que utilizo cuando quiero código útil rápidamente sin crear un desastre del que luego me arrepienta. Es subjetivo, repetible y se basa en los puntos fuertes de Claude Code (agentes, bucles de retroalimentación cortos, diferencias claras).

0) Configuración única

Mantén CONTEXT.md breve (≤ 200 líneas). Describe los módulos, las formas de los datos, las API y los elementos no negociables. Actualízalo después de cada hito.

/docs/01-scope.md         # single source of truth for goals & constraints
/docs/02-decisions.md     # architecture decisions log (ADR-style, <10 bullets)
/docs/03-tasks.md         # running task list with checkboxes
/PLAYBOOK.md              # “how this project works” for future-me / team
/CONTEXT.md               # compressed summary Claude reads first
/src/                     # code
/tests/                   # tests (even if thin)
/scripts/                 # one-off utilities (seed, migrate, import)

1) Crea cinco agentes específicos

En Claude Code: claude update → /agents.

Créalos una vez y reutilízalos en todas partes:

mvp-planner

Role: Turn a vague goal into a MVP with a crisp scope.
Always output: 
- "We will NOT build" list
- Risks with mitigations
- JSON backlog [{id, title, acceptance}]

Mantén CONTEXT.md breve (≤ 200 líneas). Describe los módulos, las formas de los datos, las API y los elementos no negociables. Actualízalo después de cada hito.

1) Crea cinco agentes específicos

En Claude Code: claude update → /agents.

Créalos una vez y reutilízalos en todas partes:

mvp-planner

Role: Turn a vague goal into a MVP with a crisp scope.
Always output: 
- "We will NOT build" list
- Risks with mitigations
- JSON backlog [{id, title, acceptance}]

Diseñador de interfaz de usuario

Role: Restyle components to a design token set (typography, spacing, colour).
Constraints: no library swaps without approval; return a patch diff only.

Corregidor de errores

Role: Reproduce, write a failing test, fix, and return a minimal patch.
Always include root cause in 1–2 sentences.

Arquitecto modular

Role: Propose directory structure, boundaries, and interfaces.
Output an ASCII module map + reasons for each boundary.

Revisor-solo lectura

Role: Code review with NO edits. 
Return: inline comments, risk ranking (High/Med/Low), and a “merge/no-merge” call.

Claude se dirigirá automáticamente a ellos cuando coincida tu solicitud. Si no es así, llama al agente explícitamente.

El bucle de compilación de 35 minutos

Ejecuta este bucle hasta que envíes. No lo alargues. La restricción mantiene la calidad alta.

Minutos 0-5: marco

  • Edita /docs/01-scope.md (lo que haremos a continuación, aceptación).
  • Actualiza /CONTEXT.md si la estructura ha cambiado.

Minutos 5-20: compilación

  • Solicite a Claude una tarea atómica (consulte las plantillas a continuación).
  • Solicite patch diff, no prosa.
  • Si obtiene ruido, solicite el mismo parche, pero más pequeño («tocar un máximo de 3 archivos»).

Minutos 20-30: prueba

  • Solicite primero una prueba fallida y, a continuación, una corrección.
  • Ejecute localmente, mantenga los registros y reduzca el alcance si es necesario.

Minutos 30-35: Confirmar y comprimir

  • Confirmar: feat: añadir exportación de facturas (csv)
  • Añadir una línea a /docs/02-decisions.md si se ha tomado una decisión.
  • Reescribir /CONTEXT.md deltas (mantenerlo por debajo de 200 líneas).

Repetir.

3) Plantillas de prompt que realmente funcionan

A. Nueva función (atómica)

Goal: [one sentence]Constraints: [stack, libraries, patterns that must remain]Touch budget: max 3 filesReturn: unified PATCH DIFF only + brief rationale (≤3 bullets)Use CONTEXT.md topreserve architecture.

B. Pase de estilo (sin cambios lógicos)

Apply design tokens (font scale, spacing, radius). No JS behaviour edits. Return patch diff for *.tsx/*.css only. If tokens missing, create tokens.ts and refactor to use it.

C. Corrección de errores con barandillas de seguridad.

Reproduce bug: [steps] 
Write failing test first in /tests/[name].spec.ts. 
Then propose smallest fix. 
Return: test diff + code diff. 
Explain root cause in 2 sentences.

D. Recuperación de la respuesta «demasiado grande»

Your patch is too large. Split into sequential patches of ≤50 lines each.
Return only PATCH 1 now. I will apply and ask for PATCH 2.

4) Cuando te quedes atascado, utiliza la escalera de atascos (en orden)

  1. Reduce la petición (un archivo, una función).
  2. Añade un ejemplo concreto (entrada/salida JSON).
  3. Duplica la página y reformula la indicación (un contexto nuevo suele dirigir al agente adecuado).
  4. Cambia la persona (llama a modular-architect para remodelar antes de codificar).
  5. Reduzca el área de superficie (indicador de función, envíe una porción más pequeña).

Si sigue atascado después de 20 minutos, está resolviendo el problema equivocado. Vuelva a /docs/01-scope.md.

5) Escalado a bases de código grandes

  • Comprima primero. Mantenga /CONTEXT.md actualizado; pida a Claude que lo regenere cuando cambien los módulos:
  • Resuma el repositorio por módulos, interfaces públicas y contratos de datos. ≤ 180 líneas. Resalte los puntos críticos de acoplamiento. Envíe el resultado a CONTEXT.md (sobrescriba).
  • Trabaje por partes. «Toque solo /src/billing/*». Claude respeta las barreras cuando las declara.
  • Refactorizaciones por lotes. Bloquea la lógica, ejecuta el ui-stylist o los cambios de linting como parches separados para evitar diferencias ruidosas.
  • Índice de puntos críticos. Mantén una lista breve en la parte superior de /CONTEXT.md: «Aquí hay dragones» con rutas de archivo.

6) Ritual de envío

  1. El agente solo lectura debe decir «fusionar» (sin ediciones).
  2. Las pruebas se ejecutan localmente (aunque sean mínimas).
  3. Documentación actualizada (una línea en las decisiones + cualquier cambio en la forma de la API).
  4. Nota de lanzamiento (3 puntos: qué ha cambiado, riesgo, reversión).

7) Ejemplo: función desde cero

Resumen: «Exportar facturas a CSV con filtros».

Inicio

  • Alcance: añadir el botón «Exportar CSV», filtrar por fecha/estado, finalización del trabajo.
  • Arquitecto modular: añade el módulo /src/export con interfaz.
  • Solicitud de función (atómica): devuelve un parche para el servicio + controlador + stub del botón.
  • Corrector de errores: escribe una prueba fallida para el caso extremo de la zona horaria y, a continuación, un parche.
  • Confirmar, línea de decisiones: «CSV utiliza UTC; la visualización se convierte a la hora local».

8) Preguntas frecuentes en una sola línea

  • ¿Por qué parches diffs? Anclan a Claude para que cambie menos, por lo que se obtienen ediciones más seguras. Aquí hay un ejemplo. Esta es también la razón por la que una herramienta como v0 o ChatGPT es más lenta para codificar con IA, ya que siempre regeneran todo el archivo.

¿Por qué CONTEXT.md? Es la barrera de seguridad. Claude lo lee; tú lo mantienes.

  • ¿Por qué 35 minutos? Lo suficiente para terminar una parte, lo corto suficiente para evitar desviaciones. Si no puedes enviar funciones a un ritmo regular, tu alcance es demasiado grande.
  • ¿Por qué cinco agentes? Más agentes no equivale a más velocidad. Estos cinco cubren el 95 % del trabajo. Descubrí que si tienes demasiados, no se enrutan al correcto.

9) Paquete inicial para copiar y pegar

Añade esto al principio de cada sesión de Claude:

House Rules:
- Return patch diffs, not prose.
- Respect /CONTEXT.md constraints.
- If unsure, propose 2 options with trade-offs (≤80 words).
- Keep changes surgical: max 3 files unless I expand scope. 
- If more than 3 files tell me why and what


Primer mensaje en un nuevo proyecto:

Read CONTEXT.md and 01-scope.md. 
Propose a clear MVP plan with a JSON backlog. 
List what we will NOT build. 
Then wait.

Me gusta decir lo que no vamos a construir.

Esto es todo. Mantén los documentos breves, las tareas atómicas, exige diferencias de parches y deja que los agentes hagan el trabajo para el que los contrataste.

Gracias por leer Codigo en Casa.