La mayoría de la gente sigue usando Claude Code como si fuera un pasante muy caro.
Le dan una tarea, esperan una respuesta y luego deciden manualmente qué hacer a continuación.
Pero los equipos que obtienen el mayor provecho de la IA están construyendo algo más parecido a un pequeño sistema distribuido.
Un agente define el alcance del problema.
Cinco agentes más baratos buscan en paralelo.
Un script determinista elimina duplicados.
Tres agentes escépticos intentan refutar los hallazgos.
Un modelo de primer nivel toma la decisión final.
Eso es ingeniería de grafos.
Antes de que sigas leyendo:
Guarda esta guía como marcador para que puedas volver a los patrones de grafos cuando empieces a construir tus propios flujos de trabajo con Claude.
Y sigue a
@Gyome1_ -
Analizo Claude Code, agentes de IA y los sistemas que convierten un modelo en un flujo de trabajo de ingeniería confiable.
Pasé semanas diseccionando arquitecturas de agentes reales, diagramas de flujo de trabajo y patrones de producción para reconstruir la Ingeniería de Grafos en un manual práctico.
En lugar de escribir un prompt más largo, diseñas la ruta que la información recorre a través del sistema:
lineal → expansión → reducción → verificación → síntesis
Cada agente se convierte en un nodo con una tarea acotada. Cada arista transporta datos estructurados. Los enrutadores deciden qué rama se ejecuta. Los verificadores rechazan resultados débiles. Los bucles continúan hasta que el grafo deja de encontrar algo nuevo.
El cambio importante es que Claude Code ya no tiene que comportarse como una sola inteligencia que procesa una lista de verificación gigante.
Puede generar el código de orquestación, desplegar una flota de subagentes especializados, enrutar sus salidas a través de diferentes modelos y ensamblar el resultado final solo después de que la evidencia sobrevive a la verificación.
Los patrones básicos no son nuevos. Los ingenieros de software han usado DAGs, pipelines, barreras, MapReduce y workers distribuidos durante décadas.
Lo que cambió es lo que ahora reside dentro de cada nodo.
Un nodo puede buscar en un repositorio, auditar una migración, cuestionar una decisión arquitectónica, inspeccionar fallos de pruebas o sintetizar cincuenta hallazgos independientes en un informe con citas.
Esta guía desglosa todo el sistema, desde el agente lineal más simple hasta grafos diamante, nodos enrutadores, paneles de verificación adversarial, bucles convergentes, niveles de modelos y flujos de trabajo dinámicos generados directamente dentro de Claude Code.
Al final, podrás mirar una tarea grande y dejar de preguntarte:
"¿Qué prompt debería escribir?"
1. LA INGENIERÍA DE GRAFOS EMPIEZA CON LA FACTURA
La ingeniería de grafos a menudo se presenta como una forma de ejecutar más agentes.
Ese enfoque pasa por alto la parte costosa.
Puedes lanzar veinte agentes de Claude contra el mismo repositorio y recibir veinte informes superpuestos, contexto repetido, conclusiones contradictorias y una factura de API mucho más grande.
Un grafo útil controla dónde ocurre la computación, qué modelo maneja cada decisión y cómo los hallazgos inciertos avanzan a través del flujo de trabajo.
Imagina pedirle a Claude Code que prepare una migración de producción:
Inspecciona el repositorio, encuentra cada dependencia, propón la migración, identifica riesgos, verifica el plan y redacta el informe final.
Dentro de un solo prompt, esto se convierte en un proceso largo y opaco. Claude busca en el código, almacena hallazgos en contexto, diseña la migración, revisa su propio plan y produce el informe final.
Cuando el informe falla, la fuente del fallo es difícil de localizar. Claude puede haber pasado por alto un archivo, malinterpretado una dependencia, perdido un detalle anterior o aceptado una suposición débil durante la verificación.
Cada etapa también puede ejecutarse en el mismo modelo caro, incluso cuando partes de la tarea implican extracción simple u ordenamiento.
La ingeniería de grafos abre ese flujo de trabajo y le da a cada decisión un lugar visible.
Las ramas de inspección se ejecutan al mismo tiempo porque usan la misma tarea delimitada y no dependen de la salida de la otra.
Sus hallazgos se encuentran en una etapa de reducción, donde los duplicados desaparecen y la evidencia se comprime en un conjunto de datos más pequeño.
Luego, un enrutador lee la gravedad. Los cambios rutinarios pasan por una revisión ligera. Los hallazgos de alto riesgo reciben un análisis más profundo de varios revisores independientes antes de llegar al modelo final.
El resultado es un flujo de trabajo donde la latencia, el costo del modelo, el tamaño del contexto y la profundidad de la verificación se controlan a través de la estructura del grafo.
Un nodo debe tomar una sola decisión
Un nodo útil tiene una responsabilidad acotada.
Encuentra cada llamada a la API obsoleta. Clasifica cada riesgo de migración como bajo, medio o alto. Prueba el plan de reversión para casos de fallo.
Cada nodo necesita una entrada clara, una salida definida y una superficie de decisión limitada.
Un nodo que busca en el repositorio, estima el impacto comercial, diseña la corrección y escribe la recomendación sigue conteniendo varias etapas ocultas. La depuración sigue siendo difícil porque el razonamiento intermedio está enterrado dentro de una sola llamada al modelo.
Los límites más pequeños revelan dónde entró la evidencia al sistema y dónde cambió su significado.
Una arista debe transportar evidencia
Una arista representa los datos requeridos por el siguiente nodo.
El escáner puede devolver un objeto predecible:
1{2 "file": "src/auth/session.ts",3 "lines": [84, 119],4 "dependency": "legacySessionClient",5 "confidence": 0.94,6 "evidence": "Ambos sitios de llamada dependen del método refresh obsoleto."7}
El clasificador de riesgos ahora recibe los mismos campos para cada hallazgo. Puede rechazar resultados incompletos, agrupar archivos relacionados y enrutar evidencia incierta a otra revisión.
Los esquemas reducen la deriva de interpretación entre nodos. Los párrafos de formato libre obligan a cada agente posterior a reconstruir el significado del agente anterior. En varias etapas, pequeñas ambigüedades pueden alterar la conclusión final.
La salida estructurada mantiene la evidencia estable mientras se mueve a través del grafo.
Algunos nodos son código ordinario
Supongamos que ocho agentes de búsqueda devuelven ochenta hallazgos.
El flujo de trabajo necesita combinar arreglos, descartar respuestas vacías, eliminar duplicados y ordenar los elementos restantes.
Estas operaciones tienen respuestas deterministas:
1const uniqueFindings = [2 ...new Map(3 results4 .flatMap(batch => batch ?? [])5 .map(item => [`${item.file}:${item.lines.join("-")}`, item])6 ).values()7];
Una transformación en JavaScript maneja esto instantáneamente y produce la misma salida en cada ejecución. Enviar la misma tarea a otro modelo agrega costo de tokens y crea otro lugar donde la evidencia puede desaparecer.
Los nodos de modelo pertenecen alrededor de la búsqueda, clasificación, comparación, revisión y síntesis. El código puede manejar validación, deduplicación, ordenamiento, reglas de enrutamiento explícitas y otras transformaciones predecibles.
Esta división se convierte en la base del grafo.
Cada llamada al modelo debe corresponder a una decisión que realmente requiere juicio.
2. EL DIAMANTE: CÓMO LOS GRAFOS DE AGENTES REALES MUEVEN EL TRABAJO
La mayoría de los grafos de agentes serios eventualmente adoptan la misma forma.
Una tarea comienza con un alcance compartido, se divide en varios trabajadores independientes, espera sus salidas, comprime la evidencia y pasa el resultado a una decisión final.
Esa forma es el diamante.
El lado izquierdo es la expansión.
El punto medio donde todas las ramas se encuentran es la barrera.
El lado derecho es la reducción.
Este patrón aparece en todas partes una vez que una tarea se vuelve demasiado grande para una sola ventana de contexto.
Una auditoría de repositorio puede dividirse por subsistema. Un informe de mercado puede dividirse por fuente. Una tarea de investigación puede dividirse por hipótesis. Una revisión de migración puede dividirse en uso de API, cambios en la base de datos, riesgo de despliegue y cobertura de pruebas.
Cada trabajador recibe el mismo alcance con una asignación más estrecha.
El grafo luego espera hasta que haya regresado suficiente evidencia útil.
La expansión debe crear trabajo independiente
Una rama pertenece a la expansión cuando puede comenzar desde la entrada compartida y producir un resultado útil sin leer la salida de otra rama.
Para una auditoría de seguridad, la división podría verse así:
Claude Code puede lanzar estas llamadas concurrentemente con una primitiva de barrera como parallel()
1const findings = await parallel(2 checks.map(check => async () => {3 return agent({4 task: check.task,5 context: auditScope,6 schema: FINDING_SCHEMA7 });8 })9);
La orquestación permanece en JavaScript ordinario. Cada rama recibe una tarea acotada y devuelve un objeto validado.
El resultado llega como una colección de salidas que pueden filtrarse, inspeccionarse y pasarse a la siguiente etapa.
Una expansión grande aún necesita una razón detrás de cada rama.
Dividir una asignación vaga en doce agentes casi idénticos a menudo produce hallazgos repetidos con redacción ligeramente diferente. El paralelismo útil proviene de fuentes, perspectivas, regiones de código o hipótesis distintas.
La barrera crea un punto de decisión
Una barrera pausa la siguiente etapa hasta que las ramas requeridas se hayan completado.
Esa pausa importa porque algunas decisiones dependen del conjunto completo.
Un nodo de clasificación no puede identificar la vulnerabilidad más importante mientras la mitad del repositorio aún está siendo inspeccionada. Un modelo de síntesis no puede escribir un plan de migración completo mientras la revisión de despliegue aún se está ejecutando.
En la barrera, el grafo tiene la oportunidad de inspeccionar el estado de la ejecución:
1const completed = findings.filter(Boolean);23if (completed.length < MIN_REQUIRED_RESULTS) {4 throw new Error("Cobertura de auditoría insuficiente");5}
Aquí es donde los fallos parciales se vuelven visibles.
Un trabajador puede agotar el tiempo, devolver datos mal formados o no producir hallazgos. Filtrar valores nulos mantiene la ejecución en marcha, pero los flujos de trabajo de producción generalmente necesitan una política más clara:
- cuántas ramas exitosas se requieren;
- qué ramas son obligatorias;
- si un nodo fallido debe reintentar;
- si el resultado final debe marcarse como incompleto.
La barrera es, por lo tanto, parte del modelo de confiabilidad, no solo un mecanismo de sincronización.
Reduce antes de sintetizar
Después de la expansión, el grafo puede contener docenas de hallazgos superpuestos.
Enviarlos todos directamente a un modelo de primer nivel crea un contexto grande, repite la misma evidencia y hace que los detalles importantes sean más difíciles de distinguir.
La etapa de reducción prepara la evidencia.
Parte de la reducción puede ocurrir en código:
1const unique = deduplicateByKey(2 completed.flatMap(result => result.findings),3 finding => `${finding.file}:${finding.line}:${finding.type}`4);
La siguiente capa puede requerir juicio:
1const curated = await agent({2 task: `3 Agrupa los hallazgos relacionados.4 Conserva todas las referencias de archivo y línea.5 Clasifica cada grupo por impacto operativo.6 Devuelve la evidencia más sólida para cada conclusión.7 `,8 input: unique,9 schema: CURATED_FINDINGS_SCHEMA10});
La reducción controla lo que llega al modelo final.
Un buen reductor elimina la repetición mientras preserva la evidencia. Un reductor agresivo puede comprimir varios riesgos distintos en un resumen vago y borrar los detalles necesarios para la verificación.
El patrón más seguro mantiene un vínculo entre cada afirmación reducida y sus elementos de origen.
1{2 "risk": "La renovación de la sesión puede fallar después de la migración",3 "severity": "alta",4 "sourceFindingIds": ["AUTH-04", "API-11", "TEST-07"],5 "evidence": [6 "Tres servicios llaman al método refresh obsoleto",7 "No existe una ruta de respaldo",8 "Falta cobertura de integración"9 ]10}
Ahora el nodo de síntesis recibe un conjunto de datos más pequeño sin perder la trazabilidad.
3. LA CONFIABILIDAD ES PARTE DEL GRAFO
Un grafo puede terminar rápidamente y aún así producir una mala respuesta.
Una vez que varios agentes comienzan a buscar, clasificar y revisar la misma tarea, el problema principal se vuelve el control.
El sistema necesita reglas para decidir qué hallazgos merecen un trabajo más profundo, qué salidas deben rechazarse y cuándo el flujo de trabajo ha buscado lo suficiente.
Enruta por riesgo
Un nodo enrutador lee la salida estructurada y elige la siguiente rama.
La clasificación puede provenir de un modelo, mientras que la rama en sí misma permanece explícita en el código.
1const route =2 finding.severity === "high"3 ? runFullAudit(finding)4 : runQuickReview(finding);
Esto concentra la revisión costosa alrededor de los hallazgos con impacto significativo.
Un enrutador útil se basa en campos que el grafo puede inspeccionar: gravedad, confianza, sistemas afectados, exposición financiera o la presencia de evidencia faltante.
Agrega verificación independiente
Un agente que revisa su propia conclusión lleva las mismas suposiciones a ambas etapas.
Un grafo más sólido envía hallazgos importantes a varios revisores con diferentes asignaciones.
Los revisores no deben recibir instrucciones de mejorar la respuesta original. Su tarea es buscar razones por las que podría ser incompleta o incorrecta.
El grafo puede requerir acuerdo antes de que un hallazgo avance:
1const accepted = votes.filter(vote => vote.approve).length >= 2;
Aísla a los agentes que modifican código
Los agentes de codificación en paralelo pueden interferir entre sí cuando editan el mismo directorio de trabajo.
Un agente puede sobrescribir un archivo mientras otro aún lo está leyendo. Las pruebas pueden ejecutarse contra una mezcla de cambios no relacionados.
Los worktrees de Git le dan a cada rama su propia copia del repositorio.
1repositorio principal2 │3 ├→ worktree/auth-fix4 ├→ worktree/db-migration5 └→ worktree/test-repair
Cada agente puede modificar archivos y ejecutar pruebas dentro de su propio entorno. Un nodo posterior compara los parches, verifica conflictos y selecciona lo que debe fusionarse.
Esto convierte el aislamiento en parte del grafo, en lugar de un paso de limpieza manual.
Deja que el descubrimiento converja
Algunas tareas no pueden completarse en una sola pasada.
Una auditoría de repositorio puede descubrir una dependencia que apunta hacia otro paquete. Ese paquete puede revelar otro sitio de llamada. El grafo necesita una forma controlada de continuar buscando sin repetir todo lo que ya ha visto.
1const seen = new Set();2let dryRounds = 0;34while (dryRounds < 2) {5 const findings = await discoverNext([...seen]);6 const fresh = findings.filter(item => !seen.has(item.id));78 fresh.forEach(item => seen.add(item.id));9 dryRounds = fresh.length === 0 ? dryRounds + 1 : 0;10}
El detalle importante es deduplicar contra cada elemento visto previamente.
Deduplicar solo contra los hallazgos confirmados permite que los elementos rechazados o inciertos regresen en la siguiente pasada y consuman el mismo trabajo nuevamente.
El bucle se detiene después de varias rondas secas, un presupuesto fijo o un número máximo de iteraciones. Los grafos de producción generalmente necesitan los tres.
Empareja el modelo con el nodo
No todos los nodos necesitan el modelo más fuerte disponible.
La extracción, la clasificación básica y las búsquedas estrechas a menudo pueden ejecutarse en un nivel más rápido. La revisión de arquitectura, la verificación adversarial y la síntesis final pueden justificar un modelo más fuerte.
La estratificación de modelos se convierte en otra propiedad del grafo.
El presupuesto está determinado por cuántos nodos se ejecutan, con qué frecuencia se repiten los bucles, cuánto contexto cruza cada arista y qué modelo maneja cada etapa.
Un grafo con veinte llamadas de búsqueda baratas aún puede costar más que una llamada fuerte. La arquitectura necesita un presupuesto de tokens antes de necesitar otra rama.
Sabe cuándo dejar de dibujar
Las tareas pequeñas rara vez necesitan enrutadores, paneles de votación, worktrees y bucles de convergencia.
La sobrecarga del grafo incluye código de orquestación, esquemas, reintentos, registro, almacenamiento intermedio y más estados de fallo que depurar.
Un flujo de trabajo lineal suele ser suficiente cuando un modelo puede contener el contexto relevante, la tarea tiene pocas ramas independientes y el costo de una respuesta incorrecta es bajo.
La ingeniería de grafos se vuelve útil a medida que la tarea gana trabajo paralelo, decisiones costosas, grandes conjuntos de evidencia o requisitos de verificación significativos.
El flujo de trabajo completo puede verse así eventualmente:
El valor proviene de hacer visible el movimiento del trabajo.
Cada nodo tiene una responsabilidad limitada. Cada arista transporta evidencia estructurada. Cada rama tiene una razón para existir. Cada bucle tiene una condición de parada.
En ese punto, Claude Code ya no está procesando una instrucción larga.
Está ejecutando un sistema diseñado.
