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.

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 desaparece | Lo que ocupa su lugar | En una línea |
|---|---|---|
| El archivo de instrucciones | Un archivo de identidad de 8 líneas | Quién es el agente, y «sigue el paso y después avanza» |
| Los párrafos de proceso | Flujos de trabajo: un grafo de pasos, decisiones y puntos de control | Una petición entra por un nodo y una decisión la envía por el camino que le corresponde |
| Los párrafos de reglas | Estándares: archivos markdown sencillos, uno por tema | El 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.

| Pieza | Qué es | Qué 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ón | Un nodo con varias aristas. Envía una petición por el camino que le corresponde, por ejemplo funcionalidad o bug | La tabla de enrutamiento |
| Punto de control | Un 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ándar | Un archivo markdown en standards/ que lee el agente al que llama el paso | Reglas pegadas en el prompt |
| Estado | La tarea, su paso actual y la nota que deja cada paso en ella | Volver 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).

| Sesión | Qué se le dice | Qué hace el agente | Dónde se detiene |
|---|---|---|---|
| 1 | La petición | Intake y después un plan: editar emails/booking_confirmed.html, añadir un párrafo y comprobar la vista previa | Punto de control Analyze |
| Persona | Aprueba 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 |
| Persona | Aprueba | ||
| 3 | «Sigue donde lo dejamos.» | Escribe la nota de aprendizaje «las plantillas de email están en emails/» y cierra la tarea | Complete, 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.

Después pasa una funcionalidad: «Añade una lista de espera a las clases completas».
| Paso | Quién | Resultado | Punto de control |
|---|---|---|---|
| Triage: funcionalidad o bug | decisión | Camino de funcionalidad | automático |
| Plan the feature | planner | join_waitlist(class_id, member), por orden de llegada, asciende al siguiente cuando alguien cancela, 5 tests | sí humano |
| Build y después Run tests | developer y después la sesión principal | waitlist.py y 5 tests, 5 superados | nota |
| Standards gate, Standards review | standards-reviewer | Revisado según standards/testing.md: 0 hallazgos | sí humano |
| Code review, ronda 1 | code-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) | developer | Llena la clase hasta su capacidad de 12 antes de apuntarse | nota |
| Run tests, estándares, Code review ronda 2 | sesión principal, standards-reviewer, code-reviewer | 5 superados, estándares correctos, sin hallazgos | sí humano |
| Done | Tarea 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.

| Situación | Mejor opción |
|---|---|
| Scripts puntuales, exploración, una pregunta rápida | Un prompt sencillo |
| Un proceso que el equipo repite: funcionalidades, bugs, lanzamientos, revisiones | Un grafo. Cada repetición sigue los mismos pasos |
| Varias personas o agentes haciendo el mismo tipo de trabajo | Un 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 seguir | Un 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íneas | Un 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.
