Inicio / Artículos

Su AGENTS.md fue escrito para un modelo peor: auditoría de la deuda en los prompts

Las reglas antiguas de AGENTS.md sobreviven a los defectos del modelo que corrigieron. Aprenda a detectar deudas en los prompts, a reducir las habilidades a enrutadores, a establecer permisos y a definir qué se ha completado antes de iniciar el proceso.

Editor: REACTAPP.TOP8 min de lectura1854 palabras

Fuentes: Your AGENTS.md Was Written for a Worse Model

Cada línea en un archivo AGENTS.md solía agregarse para solucionar un fallo real. Los modelos mejoran, el fallo desaparece, pero la regla permanece. Esto es deuda de prompts: una solución temporal para la debilidad de un modelo que se convierte en una política permanente. La solución consiste en asignarle al archivo una función más específica, que abarque invariantes, restricciones ocultas y límites de permisos, además de una definición clara de lo que se considera completado.

Cada vez que un agente de programación falla de manera memorable, alguien agrega una regla. Este modifica demasiado, por lo que el archivo indica que solo se debe tocar lo necesario. Omite la verificación, por lo que otra línea exige realizar todo el conjunto de pruebas cada vez. Cambia una dependencia sin ser solicitado, por lo que los cambios en las dependencias pasan a requerir aprobación. Se mueve de un lugar a otro en el repositorio, por lo que el archivo especifica qué documentos leer primero.

Cada regla tenía sentido cuando se escribió. Luego, el modelo cambió.

OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done

La nueva generación de modelos, tomando como ejemplo a GPT-6 Astra, sigue las instrucciones de manera notablemente mejor que los modelos de programación anteriores, lo que cambia la dinámica económica relacionada con las instrucciones de entrada. Un modelo débil podría ignorar una regla demasiado amplia, mientras que uno fuerte podría cumplirla al pie de la letra. Por lo tanto, una instrucción diseñada para compensar las deficiencias de un modelo antiguo puede convertirse en un obstáculo para uno más reciente. Si actualizas el modelo sin auditar sus instrucciones, mantienes las debilidades antiguas como política estable dentro del nuevo sistema. El modelo mejoró, pero la forma de dar instrucciones permaneció igual.

Cada fallo deja un vestigio

El código acumula deuda técnica cuando una solución temporal local se convierte en una restricción estructural. Las instrucciones dirigidas a los agentes generan deuda de la misma manera.

Supongamos que un modelo de programación antiguo seguía olvidándose de verificar sus cambios, por lo que alguien añadió:

Always run the entire test suite after every change.

En ese momento eso podría haber mejorado la fiabilidad. Un año después, el modelo ya identifica las pruebas afectadas y verifica su propio trabajo, pero la instrucción sigue estando allí. Ahora, una simple corrección de texto de una palabra puede desencadenar veinte minutos de pruebas de integración. Nada está roto, y el agente sigue fielmente las indicaciones del repositorio. El problema es que un antiguo parche de comportamiento se ha convertido en una política de ingeniería permanente.

Eso es deuda rápida: una regla soluciona un problema real, el problema desaparece, y la regla permanece.

Las habilidades cuestan algo antes de ejecutarse

Las habilidades parecen económicas, ya que su contenido completo solo se carga cuando es necesario. El formato Agent Skills describe una divulgación progresiva: primero se cargan el nombre y la descripción de una habilidad, y el archivo completo solo cuando hay una tarea que coincida.

Pero antes de que el modelo pueda elegir una habilidad, debe reconocer las opciones, por lo que los nombres y las descripciones ya compiten por la atención.

Imagínese un repositorio con habilidades separadas que abarcan migraciones de bases de datos, PostgreSQL, diseño de esquemas, persistencia en el backend, optimización de consultas y recuperación. Cada una incluye una descripción general que menciona SQL, migraciones, esquemas, consultas, modelos y almacenamiento. Incluso un pequeño ajuste en una consulta ahora parece relevante para la mitad de las habilidades disponibles, por lo que el agente debe clasificarlas antes de poder codificar.

El patrón más adecuado sigue siendo la divulgación progresiva, algo que también defiende la documentación de habilidades de OpenAI: las guías detalladas se encuentran en archivos de soporte que solo se entregan cuando una tarea las necesita.

database/
├── router.md
└── references/
    ├── migrations.md
    ├── performance.md
    └── recovery.md

El archivo raíz solo necesita lo suficiente para enrutar la tarea. Un cambio en el esquema conduce a migrations.md, una consulta lenta a performance.md, y una restauración o pérdida de datos a recovery.md. Los detalles no se descartan; aparecen cuando la tarea da al agente una razón para leerlos, lo cual permite utilizar mejor el contexto en lugar de recurrir a conocimientos operativos basados en conjeturas.

AGENTS.md debe contener lo que el código no puede explicar

Las instrucciones a nivel de repositorio se comportan de manera diferente porque acompañan al agente en casi todas las tareas. Archivos como AGENTS.md se cargan en una sesión como contexto permanente, tal como lo describen los documentos de memoria de Claude Code, y eso los hace costosos cuando están equivocados, desactualizados o son innecesariamente amplios.

Una prueba útil: ¿podría un ingeniero competente al examinar este repositorio resolverlo de manera segura y económica? Si es así, es posible que la regla no deba estar en AGENTS.md. Si no, probablemente sí.

Compare dos instrucciones. La primera es un conocimiento específico del repositorio que un modelo no puede inferir de forma segura, por lo que permanece allí:

KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.

El segundo describe un flujo de trabajo que podría ser adecuado para una refactorización arquitectónica, pero es excesivo para corregir un error tipográfico de una sola palabra, por lo que debería eliminarse o trasladarse:

MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies

Las instrucciones persistentes deben abarcar principalmente tres aspectos: invariantes que deben mantenerse verdaderos, restricciones ocultas que el código no deja evidentes, y límites de autonomía que indican dónde puede actuar el agente y dónde es necesario que decida un humano. Eso representa una tarea mucho más sencilla que enseñar a un modelo cómo realizar ingeniería de software.

Los modelos mejores hacen que los permisos sean más importantes

Un seguimiento más estricto de las instrucciones conlleva un tipo de fallo más sutil. El agente puede respetar tanto tus límites que se detiene justo donde tú querías que continuara.

Supongamos que implementa un cambio y que una prueba local afectada por ese cambio falla. Informa que auth_spec.ts está fallando y pregunta si debe arreglarlo. El modelo sabe cómo reparar la prueba, pero no sabe si esa reparación está dentro de las competencias que se le han asignado. En ese caso, otorgar un permiso resulta más útil que cualquier otro procedimiento:

Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.

Esas líneas le indican al agente tres cosas que no siempre puede deducir por sí mismo: que el entorno es seguro, que la corrección está dentro del alcance y que puede seguir avanzando. Los límites establecidos de esta manera guían mejor las decisiones que prohibiciones generales como “nunca ampliar el alcance”.

Una forma de dividir la responsabilidad en la práctica:

Necesita aprobación humana:

  • Eliminar datos de producción.
  • Modificar la política de autenticación.
  • Incumplir un contrato de API pública.
  • Introducir una migración con riesgo operativo.

Por lo general, el agente puede continuar con:

  • Reparar una prueba que su propio cambio dañó.
  • Actualizar tipos locales cercanos.
  • Formatear los archivos que modificó.
  • Volver a ejecutar las pruebas locales afectadas.

La consecuencia es lo que separa las listas; las acciones vecinas no siempre requieren el mismo nivel de aprobación.

Defina qué significa “terminado” antes de describir el proceso

Los prompts antiguos suelen describir la ruta:

Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.

Eso puede ser útil cuando un flujo de trabajo es realmente frágil, pero un agente competente suele beneficiarse más con un punto de extremo claro. Compare la solicitud simple.

Implement the avatar endpoint.

con una versión que añade una línea de meta:

Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.

El segundo nunca indica qué archivo abrir primero. Solo describe cómo se verá el resultado final. Esta distinción se vuelve más marcada a medida que los modelos adquieren suficiente capacidad de juicio para elegir su propio camino a través de un código. Las personas definen el destino y los límites peligrosos, y el agente determina la ruta a seguir.

Mantenga la jerarquía de instrucciones deliberada

Una configuración ordenada cuenta con tres capas separadas. La primera es el archivo del repositorio:

AGENTS.md
    ↓
Repository invariants
Safety boundaries
Global permissions

El segundo incluye habilidades:

Skills
    ↓
Specialized workflows
Loaded only when relevantTask prompt
    ↓
Immediate objective
Local constraints
Definition of done

El tercero es el propio prompt de la tarea. Los problemas surgen cuando las diferentes capas se mezclan: un flujo de trabajo de tarea puntual que se incluye en AGENTS.md, una regla de seguridad global oculta dentro de una habilidad que el modelo podría no cargar nunca, una habilidad que se convierte en una enciclopedia, o un prompt de tarea que repite conocimientos del repositorio que el modelo ya posee. A medida que los modelos ganan más capacidad, esa duplicación se vuelve cada vez más costosa.

Revisar las deudas de prompts cuando cambia el modelo

Una actualización del modelo debería desencadenar una auditoría de instrucciones. No es porque cada instrucción antigua esté equivocada, sino porque las suposiciones en las que se basan pueden haber cambiado. Una auditoría útil consta de cuatro pasos.

Hacer un inventario de las compensaciones históricas

Recopilar todo lo que influye en el comportamiento del agente:

  • AGENTS.md
  • descripciones de habilidades
  • contenido de las habilidades
  • prompts a nivel de sistema del repositorio
  • Instrucciones repetidas en las plantillas de tareas

Para cada regla, analice por qué existe y qué fallo llevó a que se añadiera.

Distinguir los invariantes reales de los hábitos

Pregúntese si un ingeniero competente podría deducir la regla de forma segura y económica a partir del repositorio. Si es posible, pruebe si puede eliminarse. De lo contrario, consérvela. Las reglas relacionadas con riesgos en la producción, artefactos generados, comportamientos de infraestructura ocultos y restricciones operativas poco evidentes requieren atención especial.

Convertir habilidades complejas en rutinas

Si una habilidad abarca varios flujos de trabajo, reduzca su punto de entrada. Muestre instrucciones de migración solo para las migraciones y procedimientos de recuperación solo cuando sea relevante. El conocimiento especializado permanece sin verse forzado a incluirse en cada tarea cercana.

Vuelva a leer cada prohibición para comprender el riesgo que implica

Las reglas del tipo NUNCA toques X, SIEMPRE pregunta antes de Y o SOLO modifica Z pueden seguir siendo adecuadas, pero cada una debe evaluarse en función de la consecuencia que se pretende evitar. A veces una regla mejor establece que X puede modificarse libremente en el desarrollo local, pero se necesita hacer una pregunta primero en producción, o que las regresiones causadas por los cambios propios del agente pueden corregirse, mientras que cualquier cambio más amplio requiere aprobación.

El objetivo no es la máxima autonomía. Es dirigir la atención humana allí donde las consecuencias lo justifiquen.

Qué debe perdurar más allá de cada actualización

Aun con los modelos más avanzados, algunas instrucciones siguen siendo necesarias. Una implementación podría requerir una bandera heredada no documentada. Los archivos generados pueden parecer editables aunque los cambios se sobrescriban. Un entorno local puede asemejarse al de producción al utilizar elementos temporales. Una migración podría tener que funcionar con dos versiones activas de una aplicación. Estas instrucciones tienen un gran valor porque la inteligencia por sí sola no permite detectarlas de manera fiable.

El criterio a utilizar es el valor informativo. Si la instrucción captura algo que el modelo no puede descubrir de forma segura, consérvela. Si solo describe cómo un modelo anterior debía realizar una tarea de ingeniería habitual, reconsideréela. Tener muchas instrucciones no es lo que genera deuda en los prompts; la deuda radica en aquellas cuya razón de existir ya no existe.

La antigua estrategia para programar agentes consistía en detallar cada vez más pasos del proceso. A medida que mejoran los modelos, un diseño más simple funciona mejor: mantener las invariantes, establecer los permisos y definir qué significa que una tarea se ha completado. Dejar el resto en manos del agente, y cuando se lance un nuevo modelo, revisar las reglas antes de escribir más código.