Del chat infinito a una línea de producción
Casi todos los que han programado con un asistente de IA conocen el ciclo: escribes una petición, el modelo genera código, lo pegas, aparece un error, se lo devuelves y repites. Al principio funciona de maravilla. A las dos horas, la misma conversación está decidiendo la arquitectura, escribiendo migraciones, maquetando componentes, generando pruebas y revisando su propio trabajo, todo a la vez y con un contexto que se degrada a cada mensaje. Los errores pequeños de la primera hora se convierten en supuestos equivocados que contaminan todo lo que viene después.
El problema no es el modelo ni la calidad de las instrucciones. Es que una sola conversación está haciendo demasiados trabajos distintos. En un equipo humano nadie espera que la misma persona redacte las historias de usuario, diseñe la solución, programe el backend y el frontend, escriba las pruebas y apruebe su propio pull request. Sin embargo, eso es exactamente lo que le pedimos a un chat.
La alternativa es construir un sistema alrededor del modelo: una fábrica de software con Claude Code formada por un puñado de archivos en el repositorio que dividen el trabajo en roles especializados, fijan reglas que no dependen de la memoria del modelo y reservan para la persona las decisiones importantes. En esta guía construirás esa fábrica paso a paso con las funciones actuales de Claude Code: el archivo CLAUDE.md, las skills, los hooks, los subagentes y un orquestador que encadena todo con puntos de aprobación humana.
Las cinco capas de la fábrica
Antes de crear archivos conviene tener el mapa completo. La fábrica se organiza en cinco capas que se apoyan unas en otras:
- Capa de contexto: hábitos de trabajo que evitan que la conversación se degrade, como explorar antes de construir y reiniciar la sesión cuando el contexto se contamina.
- Capa de conocimiento: lo que el modelo debe saber siempre sobre tu proyecto, guardado en
CLAUDE.md, en skills reutilizables y en hooks que actúan como barreras automáticas. - Capa de agentes: subagentes especializados, cada uno con su propio contexto, sus propias herramientas y un modelo adecuado a su tarea.
- Capa de flujo: un orquestador que encadena a los agentes en orden y se detiene en los puntos donde una persona debe aprobar.
- Capa de entrega: cómo el resultado llega a producción, con pull requests por funcionalidad y revisores automáticos.
Al final, tu repositorio tendrá esta estructura adicional:
mi-proyecto/
├── CLAUDE.md
├── docs/
│ ├── arquitectura.md
│ ├── citas.md
│ └── adr/
└── .claude/
├── settings.json
├── hooks/
│ └── bloquear-secretos.sh
├── skills/
│ ├── construir-con-pruebas/
│ │ └── SKILL.md
│ └── fabrica-funcionalidad/
│ └── SKILL.md
└── agents/
├── investigador-codigo.md
├── redactor-historias.md
├── redactor-especificacion.md
├── constructor-backend.md
├── constructor-frontend.md
├── verificador-pruebas.md
├── validador-implementacion.md
└── revisor-pr.md
Todo vive en la carpeta del proyecto y se versiona con Git, de modo que el equipo completo comparte la misma fábrica y puede mejorarla mediante pull requests como cualquier otro código.
Usaremos un ejemplo concreto a lo largo del artículo: una aplicación SaaS de gestión de citas para clínicas, construida con Next.js 16, TypeScript, Prisma y PostgreSQL. Cada clínica es un inquilino independiente, y la funcionalidad que añadiremos será la exportación del historial de citas a CSV.
Instalar Claude Code y preparar el proyecto
Si todavía no tienes Claude Code, el método recomendado es el instalador nativo, que no requiere Node.js. En macOS, Linux y WSL:
curl -fsSL https://claude.ai/install.sh | bash
En Windows, desde PowerShell:
irm https://claude.ai/install.ps1 | iex
También puedes instalarlo con Homebrew mediante brew install --cask claude-code, o con npm usando npm install -g @anthropic-ai/claude-code, aunque en ese caso necesitas Node.js 22 o superior y las actualizaciones no son automáticas. Una vez instalado, entra en la carpeta de tu proyecto y arranca la herramienta:
cd mi-proyecto
claude
Crea las carpetas que usaremos durante la guía:
mkdir -p .claude/{hooks,skills,agents} docs/adr
Capa de contexto: tres hábitos antes de automatizar nada
La automatización amplifica tanto los buenos hábitos como los malos. Antes de crear agentes, vale la pena adoptar tres costumbres que se aplican tanto al trabajo manual como a la fábrica.
El primer hábito es explorar antes de construir. Cuando abordas algo que no conoces bien, empieza en modo de planificación, que en Claude Code se activa con Shift + Tab, o con peticiones explícitamente de solo lectura. Pide al modelo que inspeccione el código, compare alternativas y te explique los pros y contras. Con esa información eliges un enfoque, lo resumes en un documento breve y abres una sesión nueva para construir a partir de ese documento. La sesión de exploración, llena de caminos descartados, no contamina la de construcción.
Sin modificar ningún archivo, analiza cómo se generan hoy los informes
en services/ y propón dos formas de añadir exportación a CSV. Para cada
una indica qué archivos tocaría, riesgos y cómo se probaría.
El segundo hábito es vigilar la deriva del contexto. Hay errores que se corrigen en línea, como un nombre de variable equivocado, y errores que obligan a reiniciar, como un supuesto de arquitectura incorrecto. Si el modelo asumió que las citas pertenecen a los pacientes cuando en realidad pertenecen a las clínicas, corregirlo con un mensaje deja rastros del error en todo el historial. En ese caso es más barato cerrar la sesión con /clear y empezar de nuevo con el supuesto correcto escrito desde el principio.
El tercer hábito es anclar las versiones. Los modelos se entrenan con documentación de muchas versiones distintas de cada librería y tienden a mezclarlas. Indica en CLAUDE.md las versiones que tienes instaladas y, si es posible, conecta un servidor MCP de documentación que entregue al modelo la referencia correcta para esas versiones. Esto elimina una categoría entera de errores, como usar APIs deprecadas o sintaxis de versiones antiguas.
Capa de conocimiento: el archivo CLAUDE.md
CLAUDE.md es un archivo Markdown que Claude Code carga automáticamente al iniciar cada sesión. El de la raíz del repositorio aplica al proyecto y se comparte con el equipo; el de ~/.claude/CLAUDE.md aplica a todos tus proyectos y es personal. Es el lugar donde va todo aquello que no quieres repetir en cada conversación.
Este es un ejemplo para la aplicación de citas:
# Agenda Clínica — guía para Claude
## Stack
- Next.js 16 (App Router) + TypeScript estricto
- Prisma + PostgreSQL (esquema en prisma/schema.prisma)
- Auth.js para sesiones; cada usuario pertenece a una clínica (tenant)
- Cola de trabajos con BullMQ para tareas en segundo plano
## Comandos
- npm run dev → servidor de desarrollo
- npm test → pruebas con Vitest
- npm run typecheck → comprobación de tipos
- npm run lint → linter
- npx prisma migrate dev → crear y aplicar migraciones
## Reglas de arquitectura
- Las rutas de app/api son finas: validan entrada y llaman a un servicio.
- Toda la lógica de negocio vive en services/.
- El aislamiento por clínica se aplica en la capa de servicios con
requireSameClinic(); ninguna consulta a Prisma omite clinicId.
- Los trabajos programados se registran solo en workers/.
## Documentación
- docs/arquitectura.md → visión general y flujos
- docs/citas.md → reglas de negocio de citas y estados
- docs/adr/ → decisiones de arquitectura registradas
## Pruebas
- Cada servicio nuevo lleva pruebas unitarias en el mismo directorio.
- Toda ruta nueva lleva una prueba de acceso entre clínicas que espere 403.
## No hacer
- No editar migraciones ya aplicadas.
- No leer ni escribir archivos .env.
- No añadir dependencias sin indicarlo explícitamente en el resumen.
Fíjate en que el archivo no explica todo el proyecto. Apunta a documentos más detallados en docs/, que el modelo puede leer cuando los necesita. Un CLAUDE.md útil suele tener entre cien y trescientas líneas: si es demasiado corto le falta contexto, y si es demasiado largo ocupa espacio en cada sesión con información que casi nunca se usa. Puedes generar una primera versión con el comando /init, que analiza el repositorio, y después pulirla a mano.
Capa de conocimiento: skills para procedimientos repetibles
Una skill es una carpeta con un archivo SKILL.md que describe un procedimiento. Claude puede cargarla automáticamente cuando tu petición coincide con su descripción, o puedes invocarla tú con /nombre-de-la-skill. Las skills del proyecto viven en .claude/skills/<nombre>/SKILL.md y se comparten con el equipo.
Un detalle importante si vienes de versiones anteriores: los comandos personalizados se fusionaron con las skills. Un archivo .claude/commands/desplegar.md y uno .claude/skills/desplegar/SKILL.md crean el mismo comando /desplegar. Los comandos antiguos siguen funcionando, pero las skills añaden capacidades como archivos de apoyo, control sobre quién puede invocarlas y carga automática.
Esta skill define cómo construir cualquier cambio acompañado de pruebas:
---
name: construir-con-pruebas
description: Procedimiento para implementar un cambio de código con pruebas. Úsala cuando haya que añadir o modificar lógica en services/ o app/api/.
---
# Construir con pruebas
1. Lee CLAUDE.md y el documento de docs/ relacionado con el área afectada.
2. Escribe primero las pruebas que describen el comportamiento esperado.
3. Ejecuta `npm test` y confirma que las nuevas pruebas fallan.
4. Implementa el cambio mínimo para que pasen.
5. Ejecuta `npm run typecheck` y `npm run lint`.
6. Si tocaste una ruta, añade la prueba de acceso entre clínicas.
7. Resume: archivos modificados, pruebas añadidas y cualquier decisión tomada.
El campo description es lo más importante del archivo, porque es lo que Claude lee para decidir cuándo usar la skill. Escríbelo indicando tanto qué hace como cuándo aplicarla.
Un consejo que ahorra muchos problemas: evita las megaskills. Una skill que intenta cubrir análisis, diseño, implementación y despliegue se vuelve ambigua y difícil de mantener. Es preferible tener varias skills pequeñas, cada una con un procedimiento claro, y dejar que un orquestador las combine.
Capa de conocimiento: hooks como barreras deterministas
Las instrucciones de CLAUDE.md y de las skills son orientaciones. El modelo las sigue casi siempre, pero casi siempre no es suficiente para cosas como no subir secretos al repositorio. Para esas reglas existen los hooks de Claude Code, scripts que se ejecutan automáticamente en momentos concretos del ciclo de vida, sin depender de que el modelo los recuerde.
Los eventos más útiles para una fábrica son estos:
UserPromptSubmit: antes de que Claude procese tu mensaje.PreToolUse: antes de ejecutar una herramienta. Puede bloquearla.PostToolUse: después de que una herramienta termine con éxito.Stop: cuando Claude termina de responder.SubagentStartySubagentStop: cuando un subagente arranca o termina.
Vamos a crear un hook que impida hacer commit si hay archivos sensibles en el área de preparación. Guarda este script en .claude/hooks/bloquear-secretos.sh:
#!/bin/bash
# .claude/hooks/bloquear-secretos.sh
# Se ejecuta antes de cada comando Bash y bloquea commits con secretos.
COMANDO=$(jq -r '.tool_input.command')
# Solo nos interesan los commits.
if ! echo "$COMANDO" | grep -q 'git commit'; then
exit 0
fi
PROHIBIDOS=$(git diff --cached --name-only | grep -E '(\.env|\.pem|\.key|secrets\.json|credenciales\.md)$')
if [ -n "$PROHIBIDOS" ]; then
echo "Commit bloqueado: hay archivos sensibles preparados:" >&2
echo "$PROHIBIDOS" >&2
echo "Quítalos con 'git restore --staged <archivo>' antes de continuar." >&2
exit 2
fi
exit 0
Dale permisos de ejecución:
chmod +x .claude/hooks/bloquear-secretos.sh
El script funciona así. Claude Code le envía por la entrada estándar un JSON con los datos de la herramienta que está a punto de ejecutarse; para Bash, el comando está en tool_input.command, que extraemos con jq. Si el comando no es un commit, salimos con código 0 y la ejecución continúa con normalidad. Si es un commit y hay archivos prohibidos, escribimos el motivo en la salida de errores y salimos con código 2. Ese código es el que indica a Claude Code que debe bloquear la acción, y el texto de la salida de errores llega al modelo como explicación, de modo que puede corregir el problema. Ojo con un detalle: el código 1 no bloquea, solo muestra un aviso.
Ahora registra el hook en .claude/settings.json, el archivo de configuración del proyecto que se comparte con el equipo:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/bloquear-secretos.sh"
}
]
}
]
}
}
La estructura tiene tres niveles: el evento (PreToolUse), un grupo con un matcher que filtra por nombre de herramienta (Bash) y la lista de manejadores que se ejecutan. La variable ${CLAUDE_PROJECT_DIR} apunta a la raíz del proyecto, así que el hook funciona sin importar en qué subcarpeta esté trabajando Claude.
Con el mismo patrón puedes añadir otras barreras útiles: ejecutar el formateador en PostToolUse cada vez que se edita un archivo, lanzar el chequeo de tipos y las pruebas en Stop para que Claude no dé por terminado un trabajo que no compila, o enviar una notificación a tu canal de equipo en SubagentStop.
Capa de agentes: subagentes con un solo trabajo
Aquí empieza la fábrica propiamente dicha. Un subagente es un asistente especializado con su propia ventana de contexto, sus propias herramientas permitidas y su propio modelo. Cuando Claude delega una tarea en un subagente, este trabaja en un contexto limpio y devuelve solo el resultado, sin llenar la conversación principal con todos los archivos que leyó.
Los subagentes del proyecto se definen como archivos Markdown en .claude/agents/, con una cabecera YAML y un cuerpo que actúa como instrucciones de sistema. Los campos obligatorios son name y description; los más útiles además de esos son:
tools: herramientas permitidas, por ejemploRead, Grep, Glob. Si lo omites, el subagente hereda todas.model:haiku,sonnet,opus,fable, un identificador completo de modelo oinherit.color: color con el que aparece en la interfaz. Los valores admitidos sonred,blue,green,yellow,purple,orange,pinkycyan.permissionMode,skills,hooks,maxTurnsoisolationpara casos más avanzados, como ejecutar un agente en un worktree aislado.
En versiones antiguas, el comando /agents abría un asistente interactivo para crear subagentes. En las versiones actuales basta con editar los archivos directamente o pedirle a Claude que los cree por ti.
Esta es la plantilla que seguiremos para cada agente:
---
name: nombre-del-agente
description: Cuándo debe Claude delegar en este agente.
tools: Read, Grep, Glob
model: sonnet
color: blue
---
## Propósito
Una frase sobre el resultado que produce.
## Responsabilidades
Qué hace, paso a paso.
## Límites
Qué no hace nunca.
## Formato de salida
Estructura exacta de lo que devuelve.
La fábrica usa siete agentes. Cada uno tiene un único trabajo:
Agente Herramientas Modelo Color
------------------------ ------------------------ ------- ------
investigador-codigo Read, Grep, Glob haiku cyan
redactor-historias Read sonnet purple
redactor-especificacion Read, Grep, Glob sonnet pink
constructor-backend Read, Edit, Write, Bash sonnet green
constructor-frontend Read, Edit, Write, Bash sonnet blue
verificador-pruebas Read, Edit, Write, Bash sonnet yellow
validador-implementacion Read, Grep, Glob opus red
Las decisiones de esta tabla tienen una lógica. El investigador solo lee y busca, una tarea mecánica en la que un modelo rápido y económico como Haiku rinde de sobra. Los redactores y constructores necesitan buen razonamiento y velocidad, por eso usan Sonnet. El validador es el último filtro antes de que una persona revise el trabajo, así que merece el modelo más capaz. Y los agentes que no deben modificar código, como el investigador, los redactores y el validador, ni siquiera tienen acceso a Edit o Write.
Los siete agentes en detalle
Veamos tres de los agentes completos; los demás siguen la misma plantilla.
El investigador es el primer eslabón. Su trabajo es averiguar cómo está hecho el código actual antes de que nadie proponga cambios:
---
name: investigador-codigo
description: Investiga el código existente relacionado con una funcionalidad antes de diseñarla. Úsalo al inicio de cualquier tarea nueva.
tools: Read, Grep, Glob
model: haiku
color: cyan
---
## Propósito
Entregar un mapa del código relevante para la funcionalidad solicitada.
## Responsabilidades
1. Localiza servicios, rutas, modelos de Prisma y pruebas relacionados.
2. Identifica patrones existentes que la funcionalidad debería reutilizar.
3. Detecta riesgos: aislamiento por clínica, migraciones, trabajos en cola.
## Límites
- No propones soluciones ni escribes código.
- No inventas archivos: si algo no existe, dilo.
## Formato de salida
- Archivos relevantes (ruta y una línea sobre su papel)
- Patrones a reutilizar
- Riesgos detectados
- Preguntas abiertas
El constructor de backend es el primero que modifica código, y por eso sus límites son más estrictos:
---
name: constructor-backend
description: Implementa la parte de servidor (servicios, rutas, migraciones) a partir de una especificación aprobada.
tools: Read, Edit, Write, Bash
model: sonnet
color: green
skills:
- construir-con-pruebas
---
## Propósito
Implementar exactamente lo descrito en la especificación aprobada.
## Responsabilidades
1. Sigue la skill construir-con-pruebas.
2. Respeta las reglas de arquitectura de CLAUDE.md.
3. Crea migraciones nuevas; nunca edites las existentes.
## Límites
- No tocas archivos de app/(ui) ni components/.
- Si la especificación es ambigua, te detienes y preguntas.
- No haces commits ni abres pull requests.
## Formato de salida
- Archivos creados y modificados
- Migraciones generadas
- Resultado de npm test y npm run typecheck
- Desviaciones respecto a la especificación (si las hay)
Observa el campo skills: precarga en el contexto del agente la skill que definimos antes, de modo que no depende de que el modelo decida cargarla.
El validador cierra la cadena con una revisión crítica:
---
name: validador-implementacion
description: Compara la implementación con la especificación aprobada y busca fallos antes de la revisión humana.
tools: Read, Grep, Glob
model: opus
color: red
---
## Propósito
Detectar diferencias entre lo especificado y lo implementado.
## Responsabilidades
1. Verifica cada criterio de aceptación de la especificación.
2. Comprueba que toda consulta nueva filtra por clinicId y que
requireSameClinic() se llama, no solo se importa.
3. Revisa manejo de errores, validación de entrada y casos límite.
## Límites
- No modificas archivos. Solo informas.
## Formato de salida
Hallazgos agrupados por severidad: CRÍTICO, IMPORTANTE, MENOR.
Cada hallazgo con archivo, línea aproximada y explicación.
Los otros cuatro agentes completan la cadena. El redactor de historias convierte la petición en historias de usuario con criterios de aceptación comprobables. El redactor de especificación transforma las historias aprobadas en un documento técnico con los archivos a tocar, los cambios de datos y el plan de pruebas. El constructor de frontend implementa la interfaz a partir de esa especificación. Y el verificador de pruebas escribe pruebas de aceptación de extremo a extremo y las ejecuta.
Un recordatorio fundamental: las reglas escritas en el cuerpo de un agente son orientación, no garantía. Que el constructor de backend diga que no toca componentes no le impide hacerlo si tiene la herramienta Edit. La aplicación real de las reglas viene de tres sitios: la lista de herramientas de cada agente, los hooks y la integración continua.
Si siete agentes te parecen demasiados para empezar, una versión mínima con tres funciona sorprendentemente bien: un investigador de solo lectura, un constructor que implementa y prueba, y un validador que revisa.
Capa de flujo: el orquestador
Con los agentes definidos falta lo más importante: alguien que los ponga en orden y se detenga cuando debe intervenir una persona. Ese papel lo cumple un orquestador de agentes, que implementaremos como una skill invocable con /fabrica-funcionalidad.
La cadena completa es esta:
Petición
│
▼
investigador-codigo ──► redactor-historias ──► [APROBACIÓN HUMANA 1: historias]
│
▼
redactor-especificacion ──► [APROBACIÓN HUMANA 2: especificación]
│
▼
constructor-backend ──► constructor-frontend ──► verificador-pruebas
│
▼
validador-implementacion
│
¿hallazgos críticos? ── sí ──► vuelve al constructor
│ no
▼
[APROBACIÓN HUMANA 3: revisión final y PR]
Crea el archivo .claude/skills/fabrica-funcionalidad/SKILL.md:
---
name: fabrica-funcionalidad
description: Orquesta la cadena completa de agentes para construir una funcionalidad, con aprobaciones humanas.
disable-model-invocation: true
argument-hint: "[descripción de la funcionalidad]"
---
# Fábrica de funcionalidades
Funcionalidad solicitada: $ARGUMENTS
Ejecuta estas fases en orden. No saltes ninguna aprobación.
## Fase 1 — Investigación e historias
1. Delega en el subagente investigador-codigo con la funcionalidad solicitada.
2. Pasa su informe al subagente redactor-historias.
3. Muestra las historias al usuario y DETENTE.
- Si responde "aprobado", continúa.
- Si pide cambios, vuelve a redactor-historias con sus comentarios.
- Si rechaza, termina y resume por qué.
## Fase 2 — Especificación
4. Delega en redactor-especificacion con las historias aprobadas
y el informe del investigador.
5. Guarda la especificación en docs/specs/<nombre-funcionalidad>.md.
6. Muéstrala al usuario y DETENTE con las mismas tres opciones.
## Fase 3 — Construcción
7. Delega en constructor-backend con la especificación aprobada.
8. Después, delega en constructor-frontend.
9. Después, delega en verificador-pruebas.
Estas tres fases escriben código: ejecútalas en secuencia, nunca en paralelo.
## Fase 4 — Validación
10. Delega en validador-implementacion.
11. Si hay hallazgos CRÍTICOS, devuélvelos al constructor correspondiente
y repite la validación. Máximo dos iteraciones; si persisten, detente
y pide ayuda al usuario.
## Fase 5 — Revisión final
12. Presenta al usuario: resumen de cambios, resultado de pruebas,
hallazgos restantes y una propuesta de descripción para el PR.
13. No hagas commit ni abras el PR hasta que el usuario lo apruebe.
Hay varias decisiones de diseño en este archivo. disable-model-invocation: true impide que Claude lance la fábrica por su cuenta: es un proceso costoso y solo debe arrancar cuando tú lo pidas. $ARGUMENTS recoge todo lo que escribas después del nombre de la skill. Los puntos de parada son explícitos y cada uno contempla tres respuestas posibles. Y el bucle de corrección tiene un límite de iteraciones, porque un agente que corrige su propio trabajo indefinidamente consume tokens sin converger.
También puedes implementar el orquestador como un subagente en lugar de una skill. La ventaja es que su contexto queda aislado de tu conversación principal; la desventaja es que interactuar con él en los puntos de aprobación es menos directo. Para empezar, la versión como skill es más sencilla de entender y depurar.
La fábrica en acción: exportar citas a CSV
Veamos un recorrido real. Arranca Claude Code en el proyecto y lanza la fábrica:
/fabrica-funcionalidad Permitir que los administradores de una clínica
exporten el historial de citas de un rango de fechas a CSV desde el panel.
El investigador devuelve su mapa en pocos segundos:
Archivos relevantes
- services/citas/listar.ts → consulta de citas con filtros por clinicId
- app/api/admin/citas/route.ts → listado paginado para el panel
- lib/auth/require-same-clinic.ts → helper de aislamiento por clínica
- prisma/schema.prisma → modelos Cita, Paciente, Profesional
Patrones a reutilizar
- Validación de entrada con Zod en las rutas de admin
- Paginación por cursor en services/citas/listar.ts
Riesgos
- Exportaciones grandes pueden superar el tiempo máximo de la ruta
- Los datos de pacientes son sensibles: revisar qué columnas se exportan
El redactor de historias produce tres historias con criterios de aceptación, entre ellos que un administrador solo pueda exportar citas de su propia clínica. Tú las revisas y apruebas.
Llega la especificación, y aquí aparece el valor de la aprobación humana. El redactor propone generar el CSV en memoria dentro de la ruta. Tú sabes que algunas clínicas tienen años de historial, así que pides cambios: la exportación debe encolarse como trabajo en BullMQ, guardar el archivo en almacenamiento y notificar al administrador cuando esté listo. Además, decides que la columna con notas clínicas no se exporte. El redactor ajusta el documento y lo apruebas.
Los constructores trabajan en secuencia y tocan archivos como services/citas/exportar-csv.ts, app/api/admin/citas/exportar/route.ts, workers/exportaciones.worker.ts y un componente del panel. El verificador escribe pruebas de aceptación y las ejecuta.
Entonces el validador encuentra algo:
CRÍTICO
- app/api/admin/citas/exportar/route.ts (~línea 12)
requireSameClinic se importa pero nunca se llama. Un administrador
podría solicitar la exportación de otra clínica cambiando clinicId.
MENOR
- services/citas/exportar-csv.ts: falta escapar comillas en el nombre
del paciente al generar la fila CSV.
El orquestador devuelve el hallazgo crítico al constructor de backend, que añade la llamada y una prueba que espera un 403 cuando se intenta exportar otra clínica. La segunda validación sale limpia. Por último recibes un resumen con los cambios, las pruebas y una propuesta de descripción para el pull request, y decides si se publica.
Este ejemplo resume por qué la fábrica funciona. Las personas tomaron las decisiones de producto y arquitectura que el modelo no podía conocer, como el volumen de datos de algunas clínicas o la sensibilidad de las notas clínicas. Y un agente con contexto limpio detectó un fallo de seguridad que el agente que escribió el código no vio, precisamente porque no estaba revisando su propio trabajo.
Paralelo o en secuencia: la regla de las escrituras
Una pregunta natural es si se pueden ejecutar varios agentes a la vez para ganar velocidad. La respuesta depende de qué herramientas usan.
Los agentes de solo lectura, con Read, Grep y Glob, se pueden ejecutar en paralelo sin riesgo: ninguno modifica nada, así que no pueden pisarse. Por ejemplo, podrías lanzar cuatro investigadores a la vez, uno por cada servicio de un monorepo, y combinar sus informes.
Los agentes que escriben, con Edit, Write o Bash, deben ir en secuencia. Dos constructores editando los mismos archivos al mismo tiempo producen conflictos difíciles de resolver, y uno puede romper las pruebas que el otro acaba de arreglar.
Existe una excepción útil: el campo isolation: worktree en la cabecera de un subagente lo ejecuta en un worktree temporal de Git, con una copia aislada del repositorio. Esto permite paralelizar trabajos de escritura que no se solapan, como actualizar la documentación de cuatro paquetes independientes, porque cada agente trabaja en su propia copia.
Capa de entrega: pull requests por funcionalidad y revisión automática
Cuando producir código se vuelve barato, el cuello de botella se desplaza. Ya no está en escribir, sino en decidir qué funcionalidades construir, definir sus restricciones, validar su comportamiento y aprobar lo que llega a producción. La capa de entrega organiza esa última parte.
La primera regla es una funcionalidad, un pull request. La fábrica produce backend, frontend, pruebas y validación como un único corte vertical. Mantenerlo en un solo PR facilita la revisión y permite revertir la funcionalidad completa si algo falla.
La segunda técnica son los pull requests apilados. Mientras el PR de la funcionalidad A espera revisión, puedes crear la rama de la funcionalidad B a partir de la rama de A y seguir trabajando:
git switch -c exportar-citas-csv main
# ... la fábrica construye y abres el PR ...
git switch -c filtros-exportacion exportar-citas-csv
# ... la fábrica construye la siguiente funcionalidad ...
Cuando A se fusiona en main, rebasas B sobre main para eliminar los commits ya integrados:
git rebase --onto main exportar-citas-csv filtros-exportacion
Herramientas como Graphite o Sapling automatizan este flujo si trabajas con muchas ramas apiladas.
La tercera pieza es un agente revisor de pull requests. Crea .claude/agents/revisor-pr.md:
---
name: revisor-pr
description: Revisa un pull request completo antes de la revisión humana.
tools: Read, Grep, Glob, Bash
model: opus
color: orange
---
## Propósito
Dar una primera revisión estructurada del PR actual.
## Responsabilidades
Ejecuta `git diff main...HEAD` y revisa:
1. Alcance: ¿el PR hace solo lo que dice su descripción?
2. Pruebas: ¿hay pruebas para cada comportamiento nuevo?
3. Seguridad: aislamiento por clínica, validación de entrada, datos sensibles.
4. Arquitectura: ¿respeta las reglas de CLAUDE.md?
5. Documentación: ¿se actualizó docs/ cuando hacía falta?
## Límites
- Usa Bash solo para comandos de git de lectura.
- Nunca editas archivos, haces commit ni fusionas PRs.
## Formato de salida
Hallazgos por severidad (CRÍTICO, IMPORTANTE, MENOR) y un veredicto final.
Para garantizar que el límite de Bash se cumple, no basta con escribirlo en las instrucciones: añade un hook en la cabecera del agente o en settings.json que rechace cualquier comando que no empiece por git diff, git log o git show. Puedes invocarlo con una mención directa, escribiendo @ y eligiéndolo en la lista, o con lenguaje natural:
Usa el subagente revisor-pr para revisar esta rama antes de abrir el PR.
El mismo revisor puede ejecutarse en la integración continua en cada push, de modo que cada pull request llegue a la persona revisora con una primera pasada ya hecha.
Errores comunes al montar la fábrica
Al construir este sistema aparecen algunos tropiezos recurrentes. Conocerlos de antemano te ahorrará tiempo.
Confiar en las instrucciones para reglas críticas. Escribir en un agente que no debe tocar ciertos archivos no lo impide. Para todo lo que no puede fallar, como secretos, migraciones aplicadas o comandos destructivos, usa la lista de herramientas, hooks con código de salida 2 y comprobaciones en la integración continua.
Usar un hook con exit 1 para bloquear. El código 1 se interpreta como un error no bloqueante: Claude Code muestra un aviso y la acción continúa. Para bloquear, el código debe ser 2.
Escribir descripciones vagas. Claude decide cuándo usar una skill o delegar en un subagente a partir de su descripción. Una descripción como “ayuda con el backend” provoca delegaciones erráticas. Indica qué hace el agente y en qué situación debe usarse.
Usar campos de cabecera con nombres incorrectos. Claude Code ignora sin avisar los campos que no reconoce. Si escribes disallowed_tools en lugar de disallowedTools en un subagente, la restricción simplemente no existe. Revisa los nombres exactos en la documentación oficial.
Usar colores no admitidos. Los subagentes aceptan una lista cerrada de colores. Valores como teal, indigo o gray no forman parte de ella.
Saltarse las aprobaciones humanas para ir más rápido. Es tentador dejar que la fábrica corra de principio a fin, pero las aprobaciones son donde se corrigen los supuestos equivocados antes de que se conviertan en código. Una especificación revisada en dos minutos ahorra horas de reescritura.
Crecer demasiado pronto. Empieza con tres agentes, comprueba que la cadena funciona en funcionalidades reales y añade agentes solo cuando detectes una necesidad concreta.
Cómo hacer crecer la fábrica
Una vez que la versión básica funciona, puedes añadir especialistas según las necesidades de tu proyecto. Algunas ideas habituales son un revisor de accesibilidad para los cambios de interfaz, un revisor de seguridad con foco en autenticación y datos sensibles, un especialista en migraciones que compruebe que los cambios de esquema son reversibles, un guardián del sistema de diseño que verifique que se usan los componentes existentes, un redactor de documentación y notas de versión, o un revisor específico para cualquier código que toque pagos.
Cada uno sigue la misma plantilla y se integra en el orquestador como una fase adicional. La clave es que cada agente nuevo tenga un único trabajo y una salida con formato fijo, para que el orquestador sepa qué hacer con su resultado.
También conviene revisar la fábrica periódicamente. Si el validador encuentra una y otra vez el mismo tipo de fallo, probablemente falta una regla en CLAUDE.md, una instrucción en la skill de construcción o un hook que lo impida de raíz. La fábrica mejora igual que un equipo: aprendiendo de sus propios errores y convirtiendo cada lección en un proceso.
Conclusiones
Una fábrica de software con Claude Code no requiere herramientas externas ni infraestructura compleja. Son unos pocos archivos versionados en el repositorio: un CLAUDE.md con el conocimiento del proyecto, skills con procedimientos repetibles, hooks que hacen cumplir las reglas críticas, subagentes especializados con herramientas limitadas y un orquestador que los encadena con aprobaciones humanas en los momentos clave.
El cambio de fondo es de mentalidad. En lugar de pedirle a una sola conversación que lo haga todo, divides el trabajo en roles con un único propósito, das a cada uno un contexto limpio y reservas para ti las decisiones que el modelo no puede tomar: qué construir, con qué restricciones y qué llega a producción. Como demuestra el ejemplo de la exportación de citas, ese flujo de desarrollo agéntico con aprobaciones permite que una persona entregue funcionalidades completas con backend, frontend, pruebas y validación, mientras un agente revisor con contexto independiente atrapa los fallos que el autor del código no vio.
Empieza pequeño, con tres agentes y un orquestador sencillo, y deja que la fábrica crezca a partir de los problemas reales que encuentres. Cada hallazgo repetido es una oportunidad para convertir una corrección manual en una regla permanente.