Guías

¿Qué es la ingeniería de grafos? Un CLAUDE.md de 8 líneas

La ingeniería de grafos consiste en diseñar un sistema de agentes de IA como un grafo: los nodos hacen el trabajo, las aristas deciden qué se ejecuta después y el estado viaja entre ellos. Nuestra visión: el grafo sustituye al archivo de instrucciones, así que un CLAUDE.md puede reducirse a 8 líneas mientras el proceso y las reglas viven en flujos de trabajo y estándares.

David Marsa

David Marsa

Founder & CEO

Intermedio8 min de lecturaActualizada el 10 oct 2026

Última verificación: 7 oct 2026

Herramientas y modelos tratados:Claude Code
Qué es la ingeniería de grafos: un CLAUDE.md de 8 líneas alimenta una decisión de triaje que envía el trabajo por el camino de funcionalidad o de bug hasta Build + tests, y una revisión de código cuyo no lleva a una corrección y de vuelta a los tests.

Lo que serás capaz de hacer

  • Explicar la ingeniería de grafos en una frase y en qué se diferencia de LangGraph.
  • Reducir el CLAUDE.md o AGENTS.md de un agente a un archivo de identidad corto.
  • Convertir un proceso que tu equipo repite en un flujo de trabajo con decisiones, puntos de control y estándares.
  • Demostrar los caminos del «no» de un flujo de trabajo plantando un fallo en una tarea desechable.

Ideas clave

  • La ingeniería de grafos consiste en diseñar un sistema de agentes como un grafo: los nodos hacen el trabajo, las aristas deciden qué se ejecuta después y el estado viaja entre ellos.
  • Nuestra visión: el grafo sustituye al archivo de instrucciones, que se reduce a un archivo de identidad de 8 líneas.
  • El proceso pasa a flujos de trabajo de pasos, decisiones y puntos de control, y las reglas pasan a estándares que se leen en cada paso.
  • La tarea guarda el estado, así que un archivo corto lleva el trabajo de una sesión a otra.
  • El conocimiento crece, el prompt no.

El problema: un CLAUDE.md que no para de crecer

Todos los equipos que usan un agente de programación con IA como Claude Code mantienen un archivo de instrucciones, y ese archivo solo crece. CLAUDE.md, AGENTS.md, .cursorrules. Empieza con veinte líneas: quién es el agente, cómo está organizado el repositorio y unas pocas reglas.

Luego llegan las lecciones. Un bug que causó el agente se convierte en una regla. Algunas reglas van en un hook, no en un archivo: mira cómo impedir que Claude Code borre tus archivos. Un proceso que acordó el equipo se convierte en un párrafo. Aparece una tabla de enrutamiento: «para los bugs, haz esto; para las funcionalidades, aquello». Meses después, el CLAUDE.md es demasiado largo: cientos de líneas, y el agente solo sigue una parte.

No es una impresión. La documentación de buenas prácticas de Claude Code de Anthropic lo dice sin rodeos: los archivos CLAUDE.md sobrecargados hacen que Claude ignore tus instrucciones reales (Anthropic, Best practices for Claude Code(se abre en una pestaña nueva)).

Cada línea que añades para mejorar al agente debilita todas las demás. La ingeniería de grafos es nuestra forma de salir de esa trampa.

Qué es la ingeniería de grafos: la definición y nuestra visión

La ingeniería de grafos consiste en diseñar un sistema de agentes como un grafo: los nodos hacen el trabajo, las aristas deciden qué se ejecuta después y el estado viaja entre ellos. Ese es el significado común, y el término no lo hemos acuñado nosotros. LangGraph es una biblioteca para construir esos grafos. La ingeniería de grafos es la disciplina.

Un CLAUDE.md de 412 líneas dividido en tres: la tabla de enrutamiento, la lista de comprobación de lanzamientos y «pregunta siempre antes de desplegar» se convierten en un flujo de trabajo con un punto de control de revisión de código, las reglas de código y las lecciones pasan a archivos de estándares, y solo queda un archivo de identidad de 8 líneas.

Nuestra visión va un paso más allá. El grafo sustituye al archivo de instrucciones. El agente nunca lee el proceso entero de golpe. Lee un paso, hace exactamente ese paso y avanza. Tres cosas ocupan el lugar del archivo largo:

Lo que desapareceLo que ocupa su lugarEn una línea
El archivo de instruccionesUn archivo de identidad de 8 líneasQuién es el agente, y «sigue el paso y después avanza»
Los párrafos de procesoFlujos de trabajo: un grafo de pasos, decisiones y puntos de controlUna petición entra por un nodo y una decisión la envía por el camino que le corresponde
Los párrafos de reglasEstándares: archivos markdown sencillos, uno por temaEl agente al que llama cada paso los lee en ese paso

La frase de la que cuelga toda la idea: el conocimiento crece, el prompt no.

Ejecutamos estos grafos como flujos de trabajo de ConvOps(se abre en una pestaña nueva), y cada ejemplo de abajo es uno de ellos, mostrado con datos de demostración.

Las cinco piezas del grafo

Nuestros grafos tienen cinco tipos de pieza, y cada uno elimina una sección del antiguo prompt.

Las cinco piezas en la funcionalidad de lista de espera de Brightloom: un paso (Build), una decisión (Triage), un punto de control (Code review, cuyo no lleva a Fix review findings y de vuelta a Run tests), un estándar (testing.md, que lee el agente del paso) y la ficha de la tarea, que guarda el paso actual y la nota de cada paso.

PiezaQué esQué sustituye en el prompt
Paso (nodo)Una unidad de trabajo con sus propias instrucciones: planificar, construir, ejecutar los tests, revisar«Planifica siempre antes de programar, luego…»
DecisiónUn nodo con varias aristas. Envía una petición por el camino que le corresponde, por ejemplo funcionalidad o bugLa tabla de enrutamiento
Punto de controlUn paso que no puede continuar sin un sí o un no explícito. Nuestros puntos de control le dicen al agente que se detenga y pregunte a una persona. Un no envía el trabajo a un paso de corrección«Pregunta siempre antes de…»
EstándarUn archivo markdown en standards/ que lee el agente al que llama el pasoReglas pegadas en el prompt
EstadoLa tarea, su paso actual y la nota que deja cada paso en ellaVolver a explicarlo todo en cada sesión

¿Por qué llamarlo ingeniería? Porque el trabajo consiste en elegir nodos y aristas. Por dónde entra una petición. Qué decisión la envía a cada sitio. Qué agente lee qué estándares. Dónde tiene que decir que sí una persona. Los pasos dejan notas en la tarea, así que el estado sobrevive a cualquier sesión.

Una ejecución paso a paso: una tarea, tres sesiones

El ejemplo más pequeño muestra la idea entera: una tarea recorre tres sesiones que nunca la ven completa, y el archivo de instrucciones nunca explica cómo. Pongamos Brightloom, un equipo ficticio de cuatro personas que crea una app de reserva de clases para estudios de yoga. El archivo de instrucciones completo de su agente, con los nombres de las herramientas en palabras sencillas:

# Who you are

You are the team's co-worker in this repo. The task system is your task list and your memory.

# How you work

1. Every request becomes a task: search first, then create one if none exists.
2. The task carries a workflow. Read the current step, do exactly what it says, then advance. Repeat until the workflow completes.

Nada sobre planificar, probar, aprobar ni retomar. Entra una petición: «Añade la política de cancelación al email de confirmación de reserva». El agente crea la tarea y el flujo de trabajo de seis pasos se asocia solo: Intake (entrada), Analyze (análisis, con aprobación), Implement (implementación), Verify (verificación, con aprobación), Capture Learnings (registro de aprendizajes) y Complete (cierre).

Tres sesiones sobre una misma tarea con una aprobación humana entre cada una: la barra de progreso de seis pasos se detiene en el punto de control Analyze, después en el de Verify, y termina en Complete, 6 de 6.

SesiónQué se le diceQué hace el agenteDónde se detiene
1La peticiónIntake y después un plan: editar emails/booking_confirmed.html, añadir un párrafo y comprobar la vista previaPunto de control Analyze
PersonaAprueba fuera de la sesión del agente
2«Sigue donde lo dejamos.»Encuentra la tarea abierta, hace el cambio y escribe un informe de verificación: la vista previa se muestra bien y el párrafo está ahíPunto de control Verify
PersonaAprueba
3«Sigue donde lo dejamos.»Escribe la nota de aprendizaje «las plantillas de email están en emails/» y cierra la tareaComplete, 6 de 6

Ninguna sesión guarda el estado. Cada sesión nueva convierte «sigue» en: busca la tarea activa, lee su paso y haz ese paso. El archivo de identidad nunca dice cómo, porque la tarea ya sabe dónde está.

Un grafo construido conversando

Construimos grafos describiéndolos, no programándolos. El responsable del equipo de Brightloom describe el proceso en una conversación: una decisión separa funcionalidades y bugs, un planificador escribe un plan que espera aprobación, los bugs empiezan con un test que falla, y todo termina en un bloque compartido de construir, ejecutar los tests y una revisión de código que devuelve el trabajo si dice que no. El agente convierte esa descripción en los flujos de trabajo.

En una conversación posterior, el responsable pide una revisión de estándares después de los tests. El agente la añade como un pequeño subflujo con su propio bucle de corrección, al que se entra desde una decisión, y la tarea que la añade pasa por el nuevo paso antes de cerrarse. El grafo crece. El archivo de identidad no cambia ni una línea. Las lecciones llegan de la misma forma: cada una va al paso o al estándar que la necesitaba, el bucle que hay detrás de cómo construimos un sistema de IA que se mejora a sí mismo.

El grafo de programación con la funcionalidad de lista de espera trazada en doce pasos numerados: la primera revisión de código dice que no porque el test nunca llena la clase, así que el trabajo pasa por una corrección, los tests y la revisión de estándares antes de que una segunda revisión diga que sí.

Después pasa una funcionalidad: «Añade una lista de espera a las clases completas».

PasoQuiénResultadoPunto de control
Triage: funcionalidad o bugdecisiónCamino de funcionalidadautomático
Plan the featureplannerjoin_waitlist(class_id, member), por orden de llegada, asciende al siguiente cuando alguien cancela, 5 testssí humano
Build y después Run testsdeveloper y después la sesión principalwaitlist.py y 5 tests, 5 superadosnota
Standards gate, Standards reviewstandards-reviewerRevisado según standards/testing.md: 0 hallazgossí humano
Code review, ronda 1code-reviewer«test_full_class_goes_to_waitlist nunca llena la clase antes, así que pasa con una clase vacía»no de una persona
Fix review findings (corregir los hallazgos de la revisión)developerLlena la clase hasta su capacidad de 12 antes de apuntarsenota
Run tests, estándares, Code review ronda 2sesión principal, standards-reviewer, code-reviewer5 superados, estándares correctos, sin hallazgossí humano
DoneTarea completada

El no es lo importante. El revisor detecta un test que no demuestra nada, una persona está de acuerdo y el grafo envía el trabajo a Fix, después a los tests y después a una segunda revisión. Nadie escribió «si la revisión falla, vuelve atrás» en un prompt. Es una arista.

Qué falla: traspasos y caminos del no sin probar

Un grafo saca el proceso del prompt. No hace seguros por sí solo los traspasos ni los caminos sin probar. Nos topamos con ambos.

El siguiente agente no lee las notas. Después de Plan the feature, el agente developer arranca solo con su encargo. El plan aprobado está en la tarea como una nota de paso que nunca abre, y una sesión nueva solo ve vistas previas cortas de las notas más recientes. La regla que aplicamos ahora: la sesión principal mete el plan aprobado y los hallazgos abiertos en el encargo del siguiente agente. La nota se queda en la tarea como registro, y el encargo lleva lo que necesita el siguiente paso.

Un camino del no que nadie ha recorrido no está demostrado. Nuestro primer bucle de revisión pasó la validación sin errores, pero el primer no real no pudo tomar la arista de vuelta. Una validación limpia demuestra la forma, no el camino.

La regla: planta un fallo en una tarea desechable y observa cómo el camino del no se ejecuta de principio a fin. En Brightloom eso significa una función sin test: la revisión de estándares lo detecta, Fix añade el test, la nueva comprobación pasa y la tarea desechable se cancela.

Cuándo merece la pena la ingeniería de grafos

Un grafo es una carga extra para el trabajo puntual y se amortiza en todo lo que el equipo repite.

Prompt o grafo: el trabajo puntual se queda en un prompt sencillo, todo lo que el equipo repite tiene un grafo, y los puntos de control van solo donde el trabajo debe detenerse a la espera de un sí o un no.

SituaciónMejor opción
Scripts puntuales, exploración, una pregunta rápidaUn prompt sencillo
Un proceso que el equipo repite: funcionalidades, bugs, lanzamientos, revisionesUn grafo. Cada repetición sigue los mismos pasos
Varias personas o agentes haciendo el mismo tipo de trabajoUn grafo. El proceso vive en un solo sitio, no en el archivo de cada persona
Trabajo que necesita el sí de una persona antes de seguirUn grafo con puntos de control. Un punto de control es un nodo, así que espera una aprobación en cada ejecución
Un archivo de instrucciones de más de unos cientos de líneasUn grafo. Saca primero el proceso y después las reglas

Si tu archivo ya ha pasado ese punto, ¿CLAUDE.md demasiado largo? Qué recortar y adónde llevarlo explica la auditoría línea a línea.

Para probar la ingeniería de grafos en un proceso que tu equipo repite, conecta tu agente a ConvOps(se abre en una pestaña nueva), describe el proceso y lleva tu próxima tarea por el flujo de trabajo que construya. Si quieres un grafo que se ejecute de forma programada sin que nadie lo arranque, mira cómo hacemos experimentos de SEO con Claude Code, o un bucle de autorreparación para tu web en el que cada bug tiene su propia ejecución en un entorno aislado. Para ver una empresa entera funcionando con estos grafos, lee cómo dirigimos nuestra empresa con flujos de trabajo que recuerdan. Si buscas otras herramientas que ejecutan flujos de trabajo de agentes, consulta el directorio de orquestación de agentes de IA.

Preguntas frecuentes

¿Qué es la ingeniería de grafos?

La ingeniería de grafos consiste en diseñar un sistema de agentes de IA como un grafo: los nodos hacen el trabajo, las aristas deciden qué se ejecuta después y el estado viaja entre ellos. En ConvOps, el grafo es un conjunto de flujos de trabajo que el agente recorre paso a paso, así que el archivo de instrucciones puede reducirse a un archivo de identidad de 8 líneas mientras el proceso vive en el grafo.

¿La ingeniería de grafos es lo mismo que LangGraph?

No. LangGraph es una biblioteca para construir grafos de agentes en código, y la ingeniería de grafos es la disciplina de diseñarlos. Con ConvOps, el grafo es un conjunto de flujos de trabajo que el agente recorre mediante sus herramientas de tareas, sin código de grafos en el repositorio. Las decisiones de diseño son las mismas en ambos casos: por dónde entra una petición, qué decisión la enruta y dónde se detiene el trabajo a la espera de un sí.

¿Qué hago cuando mi CLAUDE.md es demasiado largo?

Saca el proceso, no solo las reglas. Reparte el archivo en tres montones: quién es el agente se queda, todo lo que tenga un orden de trabajo se convierte en un paso, una decisión o un punto de control de un flujo de trabajo, y cada regla pasa a un archivo de estándares. En ConvOps los flujos de trabajo guardan los pasos, así que cada lección nueva va a un paso o a un estándar en lugar de al archivo.

¿Desaparece el archivo CLAUDE.md o AGENTS.md?

No. Se reduce a un archivo de identidad: quién es el agente, que cada petición se convierte en una tarea y que sigue el paso actual y después avanza. En la configuración que muestra esta guía son 8 líneas, y no cambian cuando el grafo crece, porque el proceso nuevo va a los flujos de trabajo y las reglas nuevas a los estándares.

¿Qué impide que el agente se salte un punto de control?

El flujo de trabajo. Un punto de control no puede avanzar sin un sí o un no explícito, y en ConvOps las propias instrucciones de ese paso le dicen al agente que se detenga y pregunte a una persona. El archivo de identidad nunca tiene que decir «pregunta siempre antes de desplegar», porque la parada está en el paso donde se aplica.

¿Necesitan los agentes sus propias instrucciones?

Sí, pero cortas. Cada rol (planner, developer, code-reviewer, standards-reviewer) tiene un archivo de agente de pocas líneas que dice qué hace y lo dirige a standards/. El paso del flujo de trabajo decide qué rol se ejecuta, así que los archivos de rol siguen siendo pequeños y el proceso se queda en el grafo.

Apréndelo en directo

Claude Code for Teams

Ver el taller