Phase 14 - Lesson 33

Instrucciones de Agente como Restricciones Ejecutables

Las instrucciones escritas como prosa son deseos. Las instrucciones escritas como restricciones son pruebas. La mesa de trabajo convierte cada regla en algo que un agente puede verificar en tiempo de ejecución y un revisor puede comprobar a posteriori.

Tipo: Build Idiomas: Python (stdlib) Prerrequisitos: Fase 14 · 32 (Mesa de Trabajo Mínima) Tiempo: ~50 minutos

Objetivos de Aprendizaje

• Separar la prosa de enrutamiento de las reglas operativas.
• Expresar reglas de inicio, acciones prohibidas, definición de terminado, manejo de incertidumbre y límites de aprobación como restricciones verificables por máquina.
• Implementar un verificador de reglas que califique una ejecución contra el conjunto de reglas.
• Hacer que el conjunto de reglas sea amigable con diffs para que la revisión pueda ver qué cambió.

O Problema

Un archivo AGENTS.md típico se lee como documentación de inducción (onboarding). Le dice al agente que "tenga cuidado", "pruebe a fondo" y "pregunte si no está seguro". Tres días después, el agente publica un cambio sin pruebas, escribe en un directorio prohibido y nunca pregunta porque nunca supo dónde estaba el límite.

Las instrucciones son poderosas cuando son operativas y débiles cuando son aspiracionales. La solución es escribir reglas que la mesa de trabajo pueda interpretar y el revisor pueda calificar.

O Concepto

Las reglas pertenecen a docs/agent-rules.md, lejos del enrutador raíz corto. Cada regla tiene un nombre, una categoría y una verificación.

flowchart LR
  Router[AGENTS.md] --> Rules[docs/agent-rules.md]
  Rules --> Checker[rule_checker.py]
  Checker --> Report[rule_report.json]
  Report --> Reviewer[Revisor]

Cinco categorías que cubren la mayoría de las reglas

Una regla que no encaja en una de estas cinco generalmente requiere dividirse en dos reglas. Fuerza la división.

Reglas son legibles por máquina

Cada regla tiene un identificador (slug), una categoría, una descripción de una línea y un campo check que nombra a una función en rule_checker.py. Agregar una regla significa agregar una verificación; el verificador crece junto con la mesa de trabajo.

Reglas son amigables con diffs

Las reglas viven una por encabezado en un solo archivo markdown. Los cambios de nombre son visibles en los diffs. Las reglas nuevas se colocan al principio de su categoría. Las reglas obsoletas se eliminan, no se comentan, porque la mesa de trabajo es la fuente de verdad, no el historial de chat de cómo se sentía el equipo el trimestre pasado.

Reglas frente a salvaguardas de framework

Las salvaguardas de framework (salvaguardas del SDK de OpenAI Agents, interrupciones de LangGraph) aplican reglas a nivel de tiempo de ejecución. El conjunto de reglas de esta lección es el contrato legible por humanos y revisable que implementan esas salvaguardas. Necesitas ambos: el tiempo de ejecución captura las violaciones durante un turno, el conjunto de reglas demuestra que el tiempo de ejecución está haciendo lo correcto.

Constrúyelo

El archivo code/main.py incluye:

• Un analizador de agent-rules.md que carga las reglas en una dataclass.
• Funciones verificadoras de estilo de rule_checker.py, una por referencia de check.
• Una ejecución de demostración del agente que viola dos reglas y un paso de verificación que las captura.

Ejecútalo:

python3 code/main.py

Salida: conjunto de reglas analizado, traza de ejecución, aprobado/fallido por regla y un rule_report.json guardado junto al script.

Patrones de producción en la práctica

Tres patrones separan a un conjunto de reglas que dura un trimestre de uno que se deteriora en una semana.

Etiquetado de gravedad en el momento de la escritura. Cada regla lleva una gravedad (severity): block, warn o info. El verificador informa las tres; el tiempo de ejecución solo rechaza en caso de block. La mayoría de los equipos exageran la gravedad al principio y luego la debilitan silenciosamente bajo la presión de las fechas de entrega; etiquetar en el momento de la escritura fuerza la calibración por adelantado. Combínalo con la puerta de verificación (Fase 14 · 38), que registra cualquier anulación de una regla block en un registro de auditoría overrides.jsonl.

Expiración de reglas como una función de presión. Cada regla lleva una fecha expires_at (por defecto 90 días desde su creación). El verificador emite una advertencia cuando una regla no expirada ha tenido cero violaciones durante 60 días consecutivos; la próxima revisión trimestral justifica mantenerla, la debilita a info o la elimina. Los datos de revisión de código de IA en producción de Cloudflare (abril de 2026, 131,246 ejecuciones de revisión en 5,169 repositorios en 30 dias) mostraron que los conjuntos de reglas con expiración explícita se mantuvieron por debajo de 30 reglas por repositorio; los conjuntos sin ella crecieron a más de 80 y la mayoría nunca se activó.

Markdown como origen, JSON como caché. El archivo agent-rules.md es el archivo creado; agent-rules.lock.json es un caché que el verificador lee en la ruta crítica de ejecución. El archivo de bloqueo se regenera mediante un hook de pre-commit. Los diffs en markdown son fáciles de revisar; el análisis sintáctico de JSON queda fuera de cada ejecución del agente. Tiene la misma forma que package.json / package-lock.json y Cargo.toml / Cargo.lock.

Úsalo

En producción:

• Claude Code, Codex y Cursor leen las reglas al comienzo de la sesión y las citan al rechazar acciones. El verificador las vuelve a ejecutar en CI para detectar desviaciones silenciosas.
• Las salvaguardas del SDK de OpenAI Agents registran las mismas verificaciones como salvaguardas de entrada y salida. El markdown es la interfaz de documentación; el SDK es la interfaz de tiempo de ejecución.
• Las interrupciones de LangGraph se activan cuando un nodo en ejecución viola una regla. El controlador de interrupciones lee la regla, pregunta al humano y reanuda.

El conjunto de reglas es portátil entre los tres porque es solo markdown más nombres de funciones.

Entrégalo

El archivo outputs/skill-rule-set-builder.md entrevista al propietario de un proyecto, clasifica sus instrucciones en prosa existentes en las cinco categorías y emite un agent-rules.md versionado junto con un esbozo del verificador (checker stub).

Ejercicios

1. Agrega una sexta categoría si tu producto realmente la necesita. Defiende por qué no se reduce a una de las cinco.
2. Extiende el verificador para que una regla pueda llevar una gravedad (block, warn, info) y el informe se agregue en consecuencia.
3. Conecta el verificador a CI: haz fallar la compilación si una regla con gravedad block falla en la última ejecución del agente.
4. Agrega un campo de expiración por regla. Después de 90 días sin fallas en la verificación, la regla estará sujeta a revisión.
5. Encuentra un AGENTS.md real y reescríbelo como reglas de cinco categorías. ¿Cuántas de sus líneas eran operativas? ¿Cuántas eran aspiracionales?

Términos Clave

Lecturas Adicionales

• OpenAI Agents SDK guardrails
• LangGraph interrupts
• Anthropic, Building Effective Agents
• Rick Hightower, Agent RuleZ: A Deterministic Policy Engine — gravedad block/warn/info en producción
• Cloudflare, Orchestrating AI Code Review at Scale — 131k ejecuciones de revisión, lecciones de composición de reglas
• microservices.io, GenAI development platform — part 1: guardrails — defensa en profundidad entre reglas y CI
• Type-Checked Compliance: Deterministic Guardrails (arXiv 2604.01483) — Lean 4 como el límite superior en regla-como-verificación
• logi-cmd/agent-guardrails — implementación de puerta de fusión: alcance, pruebas de mutación, presupuestos de violación
• Fase 14 · 32 — la mesa de trabajo mínima en la que se inserta este conjunto de reglas
• Fase 14 · 38 — la puerta de verificación que consume el informe de reglas
• Fase 14 · 39 — el agente revisor que califica el cumplimiento de las reglas