Notas prácticas: Gráficos de contexto para agentes de IA: Darle a la IA la memoria de un profesional experimentado
Guía paso a paso para utilizar las notas prácticas: Gráficos de contexto para agentes de IA: Darle a la IA la memoria de un profesional experimentado: contratos, verificaciones y espacios para código reutilizable para los equipos que implementan este patrón.
Por qué la próxima generación de agentes de IA necesita más que búsquedas vectoriales, embeddings y ventanas de contexto más grandes
Cite los pasajes que realmente sustentan la respuesta. Sin citas, los operadores no pueden distinguir entre alucinaciones y brechas en el indexado.
¿Qué es un grafo de contexto?
EmployeeController.java exists.
ReimbursementService.java exists.
SecurityConfig.java exists.
ADR-17.md exists.
EmployeeController
|
| follows_pattern
v
EmployeeApiConvention
|
| requires
v
TenantValidation
ReimbursementEndpoint
|
| handled_by
v
ReimbursementOrchestrator
|
| writes_to
v
ReimbursementRepository
|
| persists
v
HrReimbursement
ReimbursementEndpoint
|
| governed_by
v
ADR-17
ADR-17
|
| created_because_of
v
ProductionIncident-928
Un grafo es básicamente puntos y líneas
En la fase de “A Graph Is Basically”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos procesos que generen gastos o modifiquen datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase de “A Graph Is Basically”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
Node ---- Relationship ---- Node
Vaibhav ---- works_at ---- PeopleStrong
Controller ---- calls ---- Service
Service ---- calls ---- Repository
Repository ---- writes_to ---- DatabaseTable
Endpoint ---- protected_by ---- Permission
Feature ---- explained_by ---- ADR
ADR ---- resulted_from ---- Incident
Test ---- validates ---- Endpoint
Gráfico de conocimiento vs. gráfico de contexto
Al trabajar en la etapa de comparación entre el gráfico de conocimiento y el gráfico de contexto, anote primero los requisitos: entradas necesarias, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener la transparencia en los cambios posteriores del código. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Haga un punto de control después de los pasos más costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Employee
WORKS_FOR
Organization
Order
BELONGS_TO
Customer
PaymentService
USES
PaymentRepository
PaymentService
USES
PaymentRepository
PaymentService
GOVERNED_BY
ADR-12ADR-12
CREATED_AFTER
Incident-492PaymentService
REQUIRES
FinancePermissionPaymentRepository
WRITES_TO
PaymentTransactionPaymentTransaction
MUST_BE_SCOPED_BY
OrganizationIDPaymentTransaction
MUST_BE_SCOPED_BY
TenantID
La parte más importante: los gráficos de contexto almacenan el “porqué”
Al trabajar en la etapa de “La parte más importante”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones en el código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Discount = 25%
Approved = true
ApprovedBy = 182
Customer-482
RECEIVED
25% Discount
25% Discount
APPROVED_BY
SalesDirector25% Discount
EXCEPTION_TO
StandardDiscountPolicyException
BECAUSE
CustomerMigrationRiskCustomerMigrationRisk
DOCUMENTED_IN
Opportunity-928Decision
PRODUCED
SuccessfulRenewal
Componentes clave de un grafo de contexto
Al trabajar en los componentes principales de una etapa, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en los componentes principales de una etapa, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
1. Entidades: las cosas que existen
La etapa de 1 Entidad y Las Cosas funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Repository
Module
Package
Class
Method
API Endpoint
Database Table
Database Column
Configuration
Skill
Rule
Architecture Decision
Pull Request
Commit
Issue
Incident
Test
Developer
Team
Node: ReimbursementController
Type: JavaClass
Path: services/hr/.../ReimbursementController.java
Node: POST /reimbursements
Type: Endpoint
Node: HrReimbursement
Type: DatabaseTable
2. Relaciones: Cómo se conectan las cosas
Las 2 relaciones mediante las cuales Things stage funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
ReimbursementController
EXPOSES
POST /reimbursements
POST /reimbursements
CALLS
ReimbursementService
ReimbursementService
USES
ReimbursementRepository
ReimbursementRepository
WRITES_TO
HrReimbursement
POST /reimbursements
REQUIRES_PERMISSION
CREATE_REIMBURSEMENT
ReimbursementService
FOLLOWS_PATTERN
OrchestratorPattern
3. Propiedades: detalles sobre nodos y relaciones
Los 3 detalles de las propiedades relacionadas con la etapa funcionan mejor cuando se tratan como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente. Mantenga el estado de los gráficos simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo e interrumpen la continuación después de las interrupciones. Los 3 detalles de las propiedades relacionadas con la etapa funcionan mejor cuando se tratan como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
JavaClass:
name = ReimbursementController
language = Java
framework = Spring Boot
module = hr-service
Endpoint:
method = POST
path = /api/v1/reimbursements
authenticationRequired = true
Service
CALLS
Repository
since = 2026-04-18
confidence = 1.0
source = static-analysis
4. Tiempo
Para la etapa de 4 Tiempos, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
Controller
USES
FieldInjection
FieldInjectionPattern
validUntil = 2025-01-15
ConstructorInjectionPattern
validFrom = 2025-01-16
5. Origen — ¿De dónde proviene esta información?
Para la etapa de Origen Comprobado, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en aquellos procesos que implican gastos o modifican datos de producción. La conexión establecida en tiempo de compilación no equivale a la completitud del proceso empresarial.
Rule:
All employee APIs must validate TenantID.
Rule
EXTRACTED_FROM
ADR-0027.md
Rule
OBSERVED_IN
14 Production Endpoints
Rule
INTRODUCED_BY
PR-8421
6. Memoria a corto plazo
Para la etapa de Memoria a Corto Plazo 6, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. Para la etapa de Memoria a Corto Plazo 6, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
CurrentTask
TARGETS
AdminAPI
CurrentTask
EXCLUDES
EmployeeApp
7. Memoria a Largo Plazo
Al trabajar en la etapa de Memoria a Largo Plazo, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener la transparencia en los cambios posteriores del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Repository
USES
Java17
Repository
USES
SpringBoot3EndpointCreation
REQUIRES
ControllerTestEndpointCreation
REQUIRES
ServiceTest
8. Memoria de Decisión o Razonamiento
Al trabajar en la etapa 8 de toma de decisiones o razonamiento, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de consumo excesivo.
Approach A:
Controller -> Repository
Business logic must pass through the service/orchestrator layer.
Approach-A
REJECTED_BECAUSE
ArchitectureRule-42
¿Cómo funciona realmente el grafo de contexto?
Al trabajar en la fase de “So How Does the”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta de éxito como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras realizadas posteriormente. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en la fase de “So How Does the”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Trate esta fase como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina las verificaciones de éxito y rechace las completaciones parciales silenciosas.
Task:
Create Endpoint
Domain:
ReimbursementOperation:
ApproveActor:
Admin
Paso 1: Encontrar los nodos de inicio
La Etapa 1: Encontrar la etapa funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga el estado del gráfico simple y con tipos definidos. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Reimbursement
Approve
Endpoint
Admin
ReimbursementController
ReimbursementService
HrReimbursement
ReimbursementStatus
APPROVE_REIMBURSEMENT permission
ReimbursementWorkflow
Etapa 2: Ampliar sus relaciones
La etapa 2, “Expandir su escenario”, funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso después de las interrupciones.
ReimbursementController
|
+--- FOLLOWS_PATTERN ---> ExpenseController
|
+--- CALLS -------------> ReimbursementService
|
+--- PROTECTED_BY ------> FinancePermission
ReimbursementService
|
+--- USES --------------> ReimbursementOrchestrator
ReimbursementOrchestrator
|
+--- WRITES_TO ---------> HrReimbursement
|
+--- GOVERNED_BY -------> ADR-24
ADR-24
|
+--- CREATED_AFTER -----> Incident-842
Etapa 3: Filtrar el grafo
La etapa de Filtro Paso 3 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado de los gráficos simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación. La etapa de Filtro Paso 3 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
current branch
current module
task
user permission
repository version
organization
time
confidence
Paso 4: Construir el contexto del agente
En el Paso 4, “Construir la etapa”, se deben definir las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Se deben registrar los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Se debe incluir la aprobación humana en aquellas acciones que generan gastos o modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
TASK
Create reimbursement approval endpoint.
RELEVANT PATTERN
ExpenseApprovalController.REQUIRED ARCHITECTURE
Controller -> Service -> Orchestrator -> Repository.SECURITY
Permission APPROVE_REIMBURSEMENT required.TENANCY
Queries must include OrganizationID and TenantID.DATABASE
HrReimbursement.IMPORTANT DECISION
ADR-24 prohibits direct status updates.TEST PATTERN
ExpenseApprovalControllerTest.
Paso 5: El agente realiza el trabajo
En la etapa 5, “El agente realiza la acción”, defina las entradas, el responsable de dicha etapa y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la etapa desde un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en las acciones que generan gastos o modifican datos de producción. La conexión establecida en tiempo de compilación no equivale a la completitud del proceso empresarial.
Controller
Request DTO
Response DTO
Service
Orchestrator
Repository query
Authorization
Tenant filtering
Tests
Paso 6: Guardar lo que ocurrió
En la etapa “Almacenar en el paso 6”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la etapa “Almacenar en el paso 6”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
PR-9928
IMPLEMENTED
ReimbursementApprovalEndpoint
ReimbursementApprovalEndpoint
FOLLOWS
OrchestratorPattern
PR-9928
VALIDATED_BY
ArchitectureTests
Banco de datos vectorial vs gráfico de contexto
Al trabajar en la etapa de comparación entre el banco de datos vectorial y el gráfico de contexto, anote primero los requisitos: entradas necesarias, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener la transparencia en los cambios posteriores del código. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Haga un punto de control después de los pasos más costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
EmployeeController.java
EmployeeService.java
EmployeeRepository.java
SecurityConfig.java
ADR-17.md
Incident-928.md
EmployeeControllerTest.java
add-end-point/SKILL.md
Qué hace una búsqueda vectorial
Al trabajar en la etapa de Búsqueda Vectorial, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
EmployeeController.java similarity 0.94
CandidateController.java similarity 0.89
EndpointGuide.md similarity 0.87
EmployeeService.java similarity 0.82
ADR-17.md
Qué hace un grafo de contexto
Al trabajar en la etapa de “What a Context Graph”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta de éxito como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras realizadas posteriormente. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en la etapa de “What a Context Graph”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y rechace las completaciones parciales silenciosas.
EmployeeEndpoint
EmployeeEndpoint
MUST_FOLLOW
EmployeeApiPattern
EmployeeApiPattern
REQUIRES
TenantIsolation
TenantIsolation
DEFINED_BY
ADR-17
ADR-17
INTRODUCED_AFTER
SecurityIncident-28
Preguntas de la Búsqueda Vectorial:
La etapa de Preguntas de la Búsqueda Vectorial funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo por token o consulta junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Mantenga el estado del grafo plano y con tipos definidos. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Preguntas del Grafo de Contexto:
El gráfico de contexto de Asks stage funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el gráfico. Mantenga el estado del gráfico plano y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Pero no deseches su base de datos vectorial
La etapa “Pero no lances” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes posteriores. Mantenga el estado de los gráficos simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación. La etapa “Pero no lances” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
Vector Search
+
Graph Traversal
+
Metadata Filters
+
Keyword Search
+
Agent Reasoning
Un modelo mental simple
En la fase de “Un modelo mental simple”, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Prefiera salidas estructuradas con validación de esquema sobre textos en formato libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta.
Gráficos de contexto dentro de un repositorio Git
Para los gráficos de contexto dentro de una etapa, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar que los operadores puedan auditar sin necesidad de leer todo el gráfico. Coloque la aprobación humana en los enlaces que generan gastos o modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
employee-platform/
│
├── services/
│ ├── employee-service/
│ ├── payroll-service/
│ └── recruitment-service/
│
├── docs/
│ └── adr/
│
├── database/
│ └── migrations/
│
├── .agents/
│ ├── AGENTS.md
│ │
│ ├── skills/
│ │ └── add-end-point/
│ │ ├── SKILL.md
│ │ ├── templates/
│ │ └── references/
│ │
│ └── context/
│ ├── repository.yml
│ ├── architecture.yml
│ └── rules.yml
add-end-point
Diseño de un gráfico de contexto de repositorio
En la etapa de Diseño de un Contexto de Repositorio, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la etapa de Diseño de un Contexto de Repositorio, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
Repository
Module
Service
Class
Method
Endpoint
DatabaseTable
DatabaseColumn
Skill
ArchitecturePattern
Rule
Permission
ADR
Issue
PullRequest
Commit
Test
Repository CONTAINS Module
Module CONTAINS ClassController EXPOSES EndpointEndpoint CALLS ServiceService USES RepositoryRepository READS_FROM TableRepository WRITES_TO TableEndpoint REQUIRES PermissionClass TESTED_BY TestClass FOLLOWS PatternPattern DEFINED_IN ADRRule GOVERNED_BY ADRCommit CHANGES ClassPullRequest CONTAINS CommitIssue RESOLVED_BY PullRequestSkill APPLIES_TO EndpointSkill REQUIRES Rule
Un pequeño gráfico de ejemplo
Al trabajar en la etapa del “Pequeño gráfico de ejemplo”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
EmployeeController
|
| CALLS
v
EmployeeService
|
| DELEGATES_TO
v
EmployeeHandler
|
| USES
v
EmployeeRepository
|
| WRITES_TO
v
HrEmployee
EmployeeController
|
| REQUIRES
v
EmployeePermission
EmployeeRepository
|
| FILTERS_BY
+----> TenantID
|
+----> OrganizationID
EmployeeController
|
| TESTED_BY
v
EmployeeControllerTest
add-end-point
|
| USES_PATTERN
v
EmployeeEndpointPattern
¿Cómo construimos este gráfico?
Al trabajar en la etapa de “¿Cómo lo construimos?”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Java source
imports
method calls
Spring annotations
package structure
repository interfaces
SQL queries
DDL
configuration
test classes
Git history
ADR documents
AGENTS.md
SKILL.md
Fase 1 — Análisis de código estático
Al trabajar en la fase 1 de Código Estático, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en la fase 1 de Código Estático, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
@RestController
@RequestMapping("/employees")
public class EmployeeController {
private final EmployeeService employeeService; @PostMapping
public EmployeeResponse create(
@RequestBody EmployeeRequest request) {
return employeeService.create(request);
}
}
EmployeeController
TYPE
Controller
EmployeeController
EXPOSES
POST /employeesEmployeeController
CALLS
EmployeeService.create
Fase 2: Análisis del repositorio
La etapa de análisis del repositorio en la Fase 2 funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
public interface EmployeeRepository
extends JpaRepository<EmployeeEntity, Long> {
}
EmployeeRepository
OPERATES_ON
EmployeeEntity
@Entity
@Table(name = "HrEmployee")
EmployeeEntity
MAPS_TO
HrEmployee
Fase 3: Historial de Git
La etapa de Historial de Git de Fase 3 funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Commit 812ac3
Message:
Add tenant filtering to employee repository.
Reason:
Prevent cross-tenant access.
EmployeeRepository
CHANGED_IN
Commit-812ac3
Commit-812ac3
PART_OF
PR-982PR-982
INTRODUCED
TenantIsolationRule
Fase 4 — Documentos de Arquitectura
La etapa de Documentos de Arquitectura de Fase 4 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente. Mantenga el estado de los gráficos simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo e interrumpen la continuación después de las interrupciones. La etapa de Documentos de Arquitectura de Fase 4 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
All employee mutations must pass through the EmployeeHandler.
EmployeeMutation
MUST_USE
EmployeeHandler
rule source:
ADR-17
Fase 5 — Habilidades de IA
Para la etapa de habilidades de IA de Fase 5, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
.agents/skills/add-end-point/SKILL.md
Before creating an endpoint:
1. Identify the nearest existing endpoint pattern.
2. Resolve authentication and authorization rules.
3. Resolve tenant and organization isolation.
4. Identify service/orchestrator pattern.
5. Identify persistence pattern.
6. Identify required tests.
get_context(
task="create-endpoint",
domain="employee",
operation="create"
)
El Servicio de Gráfico de Contexto
En la etapa del Servicio de Gráfico de Contexto, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el gráfico. Coloque la aprobación humana en los enlaces que generan gastos o modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
AI Agent
|
v
Context API / MCP Server
|
+--------> Graph Database
|
+--------> Vector Database
|
+--------> Git Repository
find_entity
get_neighbors
find_path
get_architecture_context
get_security_context
get_database_context
get_change_history
get_similar_implementations
get_context_for_task
record_decision
get_context_for_task(
repository="employee-platform",
skill="add-end-point",
task="create reimbursement approval endpoint"
)
¿Qué base de datos gráfica deberíamos usar?
En la etapa de “What Graph Database Should”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la etapa de “What Graph Database Should”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
JSON files
+
NetworkX
+
SQLite
Una representación muy simple similar a Neo4j
Al trabajar en la etapa de “Una representación muy simple similar a Neo4j”, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Ver la información sobre costos desde el principio evita facturas inesperadas cuando el proceso pasa de una demostración a entornos compartidos. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
CREATE (:Class {
name: "EmployeeController",
type: "Controller"
});
CREATE (:Service {
name: "EmployeeService"
});CREATE (:Repository {
name: "EmployeeRepository"
});
MATCH (c:Class {name:"EmployeeController"}),
(s:Service {name:"EmployeeService"})
CREATE (c)-[:CALLS]->(s);
MATCH (s:Service {name:"EmployeeService"}),
(r:Repository {name:"EmployeeRepository"})
CREATE (s)-[:USES]->(r);
Consultar el grafo
Al trabajar en la etapa de Consulta al Gráfico, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el gráfico. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
MATCH path =
(endpoint:Endpoint)-[*1..4]-(context)
WHERE endpoint.domain = "employee"
RETURN path
Controller
Service
Handler
Repository
Table
Permission
Tenant Rule
Tests
ADR
Una arquitectura mejor: recuperación híbrida
Al trabajar en la etapa A Better Architecture Hybrid, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Mida la capacidad de recuperación con un conjunto fijo de preguntas antes de ajustar los prompts. El cambio constante de prompts rara vez soluciona un sistema de recuperación deficiente. Al trabajar en la etapa A Better Architecture Hybrid, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina las verificaciones de éxito y rechace las completaciones parciales silenciosas.
User Request
|
v
Context Retriever
|
+--------------+--------------+
| | |
v v v
Vector Graph Keyword
Search Traversal Search
| | |
+--------------+--------------+
|
v
Context Ranking
|
v
Agent Context
|
v
LLM
El problema del presupuesto de contexto
La etapa del Problema de Presupuesto de Contexto funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
Repository:
8 million tokens
Controller conventions
Service convention
Security rule
Two repositories
One ADR
Three tests
Total:
18,000 tokens
Gráfico de Contexto + Habilidad del Agente
La etapa de la habilidad Context Graph Agent funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Developer
|
v
AI Agent
|
v
add-end-point Skill
|
v
Context Graph Query
Developer
|
| "Create employee endpoint"
v
AI Agent
|
| reads
v
.agents/skills/add-end-point/SKILL.md
|
| SKILL.md says:
| "Before generating code,
| call get_task_context"
v
MCP Tool
get_task_context(...)
|
v
Context Graph Service
|
+---- Neo4j / Graph DB
|
+---- Vector Search
|
+---- Git metadata
|
v
Relevant Context
|
v
AI Agent
|
| follows retrieved rules
v
Generate / modify code
Nearest endpoint:
LeaveRequestController
Controller pattern:
@RestController
constructor injectionService pattern:
interface + implementationArchitecture:
Controller
-> Service
-> Handler
-> RepositorySecurity:
LEAVE_VIEWTenant rules:
OrganizationID + TenantIDPersistence:
HrLeaveBalanceTesting:
ControllerTest
ServiceTest
RepositoryITArchitecture decision:
ADR-42
Luego el agente genera código
La etapa “Then the Agent Generates” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
LeaveBalanceController
LeaveBalanceRequest
LeaveBalanceResponse
LeaveBalanceService
LeaveBalanceServiceImpl
LeaveBalanceHandler
LeaveBalanceRepository
LeaveBalanceProjection
LeaveBalanceException
LeaveBalanceControllerTest
LeaveBalanceServiceTest
LeaveBalanceRepositoryTest
La etapa “Then the Agent Generates” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
Does the endpoint follow the required architecture?
YES.Does it apply security?YES.Does repository filtering include TenantID?YES.Does it include OrganizationID?YES.Are mandatory tests present?YES.
Arranque del repositorio
En la fase de Bootstrap del repositorio, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en los que se gastan fondos o se modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
bootstrap-context
2-3 representative endpoints
architecture
build files
framework versions
dependency injection
security
database patterns
testing
exception handling
transactions
module boundaries
Repository
USES
Java17
Repository
USES
SpringBoot3Endpoint
FOLLOWS
Controller-Service-Handler-RepositoryDatabaseQuery
MUST_INCLUDE
TenantIDDatabaseQuery
MUST_INCLUDE
OrganizationID
Las habilidades se vuelven mucho más reducidas
En la etapa en la que las habilidades se vuelven mucho más simples, defina los insumos, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en aquellos procesos que implican gastos o modificaciones en los datos de producción. La conexión establecida en tiempo de compilación no equivale a la completitud del proceso empresarial.
For employee APIs use EmployeeHandler.
For payroll APIs use PayrollOrchestrator.For recruitment APIs use ActionHandler.For employee APIs tenant filtering happens...For payroll APIs...
1. Understand the requested endpoint.
2. Query the repository Context Graph.3. Resolve:
- architecture pattern
- closest implementation
- security
- data ownership
- persistence
- testing requirements4. Generate code.5. Validate generated changes against graph constraints.6. Record newly confirmed repository knowledge.
Las habilidades indican al agente CÓMO
En la fase de Skills Tell the Agent, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
El grafo de contexto le indica al agente qué es cierto aquí
Para que el grafo de contexto indique la etapa a seguir, se deben definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe referirse a una única responsabilidad y no a un proceso complicado. Se debe incluir la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La conexión de componentes en tiempo de compilación no equivale a la completitud del proceso empresarial.
Grafos de contexto y sistemas multiagente
En la etapa de Gráficos de Contexto y Multi-Agentes, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
Architecture Agent
Security Agent
Backend Agent
Testing Agent
Database Agent
Reviewer Agent
duplicate work
different conclusions
large token usage
conflicting decisions
Context Graph
/ | \
/ | \
v v v
Backend Security Testing
Agent Agent Agent
Endpoint requires FINANCE_WRITE
Los Gráficos de Contexto pueden aprender de las solicitudes de pull
En la etapa en la que los gráficos de contexto pueden aprender, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Coloque la aprobación humana en las conexiones que generan gastos o modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
repository.findByEmployeeId(employeeId);
EmployeeRepositoryQuery
MUST_FILTER_BY
TenantID
EmployeeRepositoryQuery
MUST_FILTER_BY
OrganizationIDRule
LEARNED_FROM
PR-11882
Un gráfico de contexto no es el cerebro del LLM
En la etapa de Gráfico de Contexto A, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el gráfico. Prefiera salidas estructuradas con validación de esquema sobre texto libre cuando el siguiente paso sea código o una llamada a una herramienta.
LLM
=
Reasoning Engine
Context Graph
=
Structured MemoryVector Database
=
Semantic Memory SearchSkills
=
ProceduresTools
=
Actions
AI Agent
|
+---------+---------+
| | |
v v v
Skills Context Tools
Graph
|
+-------+-------+
| |
v v
Vector Graph
Search Store
Gráfico de Contexto vs Afinamiento
En la etapa de Context Graph vs Fine-Tuning, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial. En la etapa de Context Graph vs Fine-Tuning, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
OldRule
status = deprecated
NewRule
status = active
Gráfico de contexto vs. prompt enorme
Al trabajar en la fase de Gráfico de contexto vs. prompt enorme, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Almacene en caché las instrucciones del sistema estables y los esquemas de herramientas. Reenviar un preámbulo idéntico es una causa común de consumo excesivo.
AGENTS.md
= 40,000 lines
Task
|
v
Relevant Subgraph
|
v
Prompt
Entire Organization
|
v
Prompt
Cómo desplegar una primera versión
Al trabajar en la etapa de “Cómo desplegar”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación ayuda a mantener honestos los cambios posteriores en el código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Repository:
employee-service
Skill:
add-end-point
Module
Class
Endpoint
Service
Repository
Table
Rule
Permission
Test
ADR
CONTAINS
EXPOSES
CALLS
USES
WRITES_TO
READS_FROM
REQUIRES
TESTED_BY
FOLLOWS
DEFINED_IN
Despliegue sugerido
Al trabajar en la etapa de Despliegue Sugerido, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Haga un punto de control después de los pasos costosos. Resume no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
Git Repository
|
|
v
Repository Indexer
|
+------ Java Parser
|
+------ Git Parser
|
+------ Markdown Parser
|
+------ SQL Parser
|
v
Context Graph DB
|
+------ Vector Index
|
v
Context Service / MCP
|
v
AI Coding Agent
|
v
Repository Skills
Actualizar el grafo de forma incremental
Al trabajar en la etapa de “Actualizar el grafo de forma incremental”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
EmployeeController.java
EmployeeService.java
ADR-42.md
git diff HEAD~1
changed files
|
v
re-index
|
v
update graph
El contexto debe tener confianza
Al trabajar en la etapa de “El contexto debe generar confianza”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre los datos de entrada y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
EmployeeController
CALLS
EmployeeService
confidence = 1.0
source = static-analysis
Employee APIs
PROBABLY_REQUIRE
ManagerPermission
confidence = 0.62
source = llm-inference
FACT
OBSERVATION
INFERENCE
DECISION
RULE
Los seres humanos deben poder corregir el grafo
Al trabajar en la etapa “Humans Must Be Able”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto a los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Payroll APIs use Handler architecture.
HandlerPattern
status = deprecated
OrchestratorPattern
status = active
La idea más amplia: de la búsqueda en repositorios a su comprensión
Al trabajar en la etapa “The Bigger Idea From”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones en el código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Question
|
v
Search Files
|
v
Read Files
|
v
Generate Code
Question
|
v
Understand Task
|
v
Identify Relevant Entities
|
v
Traverse Architecture
|
v
Recover Rules
|
v
Recover History
|
v
Recover Decisions
|
v
Build Context
|
v
Execute Skill
|
v
Validate Result
|
v
Record Learning
La analogía del ingeniero senior
Al trabajar en la etapa de la analogía del ingeniero senior, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haga un punto de control después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior. Al trabajar en la etapa de la analogía del ingeniero senior, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina las verificaciones de éxito y rechace las completaciones parciales silenciosas.
Esa es la verdadera promesa
Esa etapa, que es la real, funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
El repositorio futuro podría verse muy diferente
CODE
What the system does.
SKILLS
How agents should perform work.CONTEXT GRAPH
What the agent should understand about this repository.
my-platform/
│
├── services/
│
├── database/
│
├── docs/
│
├── tests/
│
│
├── AGENTS.md
│
├── .agents/
│ │
│ ├── skills/
│ │ ├── add-end-point/
│ │ ├── fix-bug/
│ │ ├── create-migration/
│ │ └── review-pr/
│ │
│ └── context/
│ ├── graph-schema.yml
│ ├── rules.yml
│ └── bootstrap.yml
│
└── context-graph/
├── indexer/
├── extractors/
├── graph-api/
└── validation/
Un último ejemplo
TASK
Create reimbursement endpoint.
DOMAIN
Finance / Employee.PATTERN
ExpenseController.ARCHITECTURE
Controller -> Service -> Orchestrator -> Repository.AUTHENTICATION
Session authentication required.AUTHORIZATION
CREATE_REIMBURSEMENT.TENANCY
OrganizationID + TenantID mandatory.DATABASE
HrReimbursement.TRANSACTION
Orchestrator owns transaction.IMPORTANT HISTORY
Direct reimbursement status mutation caused incident FIN-822.RULE
Use ReimbursementWorkflow.TESTING
Controller + Service + Repository tests required.REFERENCE PR
PR-11822 implemented similar Expense workflow.
Pensamiento final
LLM
gives the agent intelligence.
Skills
give the agent procedures.Tools
give the agent hands.Vector search
helps the agent find things.Context Graph
helps the agent understand how those things are connected.Decision history
helps the agent understand why.
Lista de verificación operativa
Lecturas relacionadas
- Notas prácticas: ¿Qué son los agentes de voz IA y cómo funcionan? — Guía paso a paso de las Notas prácticas: ¿Qué son los agentes de voz IA y cómo funcionan?: contratos, verificaciones y espacios para código listos para usar para los equipos que implementan este patrón.
- Notas prácticas: Estoy ejecutando un agente de programación IA localmente y es casi dos veces más rápido — Guía paso a paso de las Notas prácticas: Estoy ejecutando un agente de programación IA localmente y es casi dos veces más rápido: contratos, verificaciones y espacios para código listos para usar para los equipos que implementan este patrón.