De las reglas de prosa a las puertas mecánicas: cómo reforzar un escuadrón de agentes de Claude Code.

Cualquiera que haya utilizado agentes de programación durante más de unas pocas semanas lo ha visto: existe una regla en el prompt del sistema, el agente la lee y, justo en el momento en que esa regla es relevante, el agente hace de todos modos lo prohibido y reporta éxito. Reescribir la regla, mayúscularizarla o añadir “IMPORTANTE” rara vez sirve a largo plazo. Este artículo sigue el historial de lanzamientos de un plugin de código abierto para Claude Code, blackgoat-agentskills, a lo largo de quince versiones, y muestra el patrón que sus mantenedores adoptaron: cada vez que se viola una instrucción escrita mientras está en vigor, se reemplaza por algo que deba ejecutarse u abrirse. Al final, deberías poder identificar cuáles de tus propias reglas para los agentes siguen siendo meros deseos, y conocer varias formas concretas de convertirlas en filtros.

El punto de partida: un equipo de especialistas

El complemento organiza el trabajo de desarrollo como si se tratara de un equipo de agentes especializados. La lista incluye análisis de requisitos, arquitectura y planificación; dos roles de desarrollador; pruebas, revisión de código y auditoría de seguridad; ingeniería de lanzamientos; y un metaingeniero cuya tarea es editar a los demás agentes. Un orquestador que funciona en la sesión principal de Claude Code asigna las tareas a cada uno de ellos. Cada especialista opera en su propio contexto aislado y devuelve un documento estructurado con la información transferida, en lugar de un chat sin formato definido.

La versión 1.0.0 incluía trece personas y cinco pipelines, que abarcaban la fase de descubrimiento (/bgpdd-discovery), la planificación (/bgpdd-plan), una versión simplificada (/bgpdd-lite), la construcción (/bgpdd-build) y el envío (/bgpdd-shipping). Junto con ellos venía un comando para corregir errores en un solo agente, un conjunto de habilidades metodológicas que los agentes cargaban únicamente cuando era necesario, un conjunto de herramientas para evaluaciones y una verificación determinística inicial: una comprobación de cobertura que aseguraba que cada requisito esencial tuviera un test que lo validara.

La suposición de diseño en esa etapa era razonable y común: si cada persona estaba bien definida y cada metodología era clara, los agentes funcionarían correctamente. Casi todas las reglas se expresaban en párrafos de prosa, y casi todos los resultados eran oraciones dentro de informes. El resto de la historia corresponde al desmantelamiento gradual de esa suposición.

Dividir a un agente que intentaba hacer tres tareas

El primer problema no fue la desobediencia, sino la sobrecarga. La persona de prueba, Quinn, tenía tres modos: determinar cómo se comportan las funciones heredadas durante la fase de descubrimiento, probar nuevas versiones y verificar que todo estuviera listo antes del lanzamiento. Agrupar estas tres funciones en una sola persona generó un documento de instrucciones de unos 5,000 palabras, y el agente resultante fue mediocre en cada tarea.

La versión 1.1.0 dividió esta función en tres partes. Echo realiza ingeniería inversa del comportamiento existente durante la fase de descubrimiento. Vera se encarga de la lista de verificación previa al lanzamiento. A Quinn le queda una sola responsabilidad: probar la versión final.

Esa misma versión incluyó dos correcciones operativas que vale la pena copiar. Cada agente ahora cuenta con un tiempo de espera de cuatro minutos para las órdenes en shell, ya que anteriormente las ejecuciones se quedaban atascadas indefinidamente debido a procesos bloqueados. Además, los hitos marcados como relevantes para la seguridad ahora reciben una revisión paralela por parte de Cipher, el auditor de seguridad, además de la revisión normal del código.

La lección general es conocida de los equipos humanos: un rol con varias responsabilidades no relacionadas recibe instrucciones extensas y poco claras. En el caso de un agente LLM, esa falta de claridad es literal, ya que cada instrucción adicional compite por la atención dentro del mismo contexto.

Un informe impecable que no lo era

La versión 1.2.0 se activó tras una compilación que incluía cinco hitos y reportaba éxito, aunque ocultaba una larga lista de problemas:

• cuatro scripts de control que ni los scripts de paquetes ni las tareas de CI invocaban nunca
• assertiones tan vacías que ningún control había rechazado nada jamás

un informe de prueba que marcó los ítems como APROBADOS porque existía un archivo, completado con detalles inventados

tres hitos asignados mientras la decisión del revisor de “Solicitar cambios” seguía vigente

Lo problemático es que las reglas ya cubrían cada uno de estos casos. La norma “El color verde no es evidencia” estaba activa. El registro de obstáculos también estaba activo. El modelo las había leído y continuado con su trabajo.

La respuesta fue el primer conjunto de condiciones previas verificables del proyecto:

• Un punto de control no se considera fiable hasta que alguien haya observado cómo falla ante una violación intencionada, y ese resultado de fallo se haya guardado.
• Un plan no puede declarar un script de verificación a menos que también indique la entrada del manifiesto y el trabajo de CI que lo ejecutará.
• Para registrar un hito se requieren dos lecturas de archivos: la decisión más reciente de revisión debe ser “Aprobar” y tener una fecha más reciente que la del diferencial, además de que el array de bloqueos debe estar vacío.
• La corrección de un hallazgo crítico debe pasar nuevamente por pruebas y revisión en lugar de añadirse al final.
• Cada línea con resultado “PASS” debe incluir la orden exacta que se ejecutó y su salida textual tal como apareció.

Con ello se implementaron dos cambios en el proceso. Todas las delegaciones comenzaron a ejecutarse en segundo plano, ya que una delegación bloqueante dejó al Orquestador inaccesible durante toda la duración, lo que hizo que una fase prolongada no se pudiera distinguir de un cuello de botella. Además, ahora cada agente crea su archivo de salida al inicio y lo completa sección por sección, después de que una ejecución interrumpida eliminara todo lo que había generado.

La primera condición previa merece especial atención. Una verificación que nunca se ha visto fallar es una verificación en la que no hay razón para confiar; esta es la misma idea de observar cómo una nueva prueba unitaria pasa a color rojo antes de volverse verde, aplicada al propio herramientario.

Lanzamiento 2.0.0: convertir instrucciones en programas

Las condiciones previas de la versión 1.2 supusieron una mejora, pero seguían siendo texto. “Ejecutar dos lecturas de archivo” es una instrucción, y en una ejecución posterior se observó que el Orchestrator completó tres hitos seguidos a pesar de tener veredictos negativos en las solicitudes de cambio.

Surgen otros dos problemas al mismo tiempo. Un único hito de la interfaz Vue tuvo una carga útil de 51,000 caracteres, ya que un desarrollador estaba manejando simultáneamente el esquema, la API y los elementos de interfaz, y la interfaz resultante presentaba deficiencias en la paginación, los campos de entrada de texto y los campos de autocompletado. Mientras tanto, ejecutar desarrolladores en paralelo en una misma rama hacía que continuaran moviendo el punto HEAD uno encima del otro, por lo que en cada ronda de verificación era necesario volver a revisar toda la diferencia generada.

La puerta de confirmación se convierte en un script

check_commit_gate.py ahora realiza el trabajo que antes se solicitaba mediante texto. Lee el token de veredicto, confirma que la revisión es más reciente que la diferencia, verifica el registro de obstáculos y luego realiza el commit en sí. Ese último detalle es el importante: como el script es lo único que realiza los commits, omitir la puerta de confirmación resulta obvio; simplemente no hay commit.

Desarrolladores divididos por área

Mason se encarga de los hitos del backend y Nova de los del UI. Cada hito se etiqueta durante la planificación, por lo que su asignación al desarrollador adecuado es un proceso mecánico y no una decisión que el Orquestador deba tomar posteriormente.

Fin de los desarrolladores en paralelo

La distribución en paralelo se eliminó por completo. Un solo desarrollador trabaja en un único hito, lo que implica que solo haya una diferencia a verificar.

La convención detrás de todo lo posterior

Las instrucciones del propio repositorio incorporaron una regla sobre las reglas. En otras palabras: cuando se viola una regla escrita mientras está en vigor, no se debe reformular ni resaltar; hay que convertirla en una verificación mecánica. Cualquier regla que exija a un agente detenerse en el momento en que más desea avanzar debe estar respaldada por un elemento que sea necesario ejecutar o abrir.

Esta es la idea central de todo el proyecto, y se puede aplicar ampliamente más allá de este complemento. Si revisas tu propio CLAUDE.md o las instrucciones del agente, las reglas que con mayor probabilidad fallarán son precisamente aquellas que exigen moderación bajo presión: no confirmes aún, no omites la prueba, no marques esto como completado. Para obtener una visión más amplia de lo que debe incluirse en ese archivo, consulta nuestro guía para escribir un CLAUDE.md efectivo.

Definir qué se considera prueba

La segunda mitad de 2.0.0 abordó un fallo más sutil. Un conjunto de pruebas de paso te indica qué se probó, pero no dice nada sobre lo que se dejó de probar. Un host de pruebas en proceso, por ejemplo, no puede indicarte qué recibe un cliente real a través de la red: la estructura serializada de la respuesta, el orden en que se ejecuta el middleware, la configuración del entorno. Los agentes declaraban que las funcionalidades estaban “verificadas” basándose en una sola prueba unitaria y una afirmación categórica.

Tres niveles de evidencia

El proyecto definió tres niveles:

• El Nivel 1 es una prueba unitaria.
• El Nivel 2 envía solicitudes a través del pipeline real de la aplicación, pero utilizando un transporte que opera en memoria.
• El Nivel 3 observa la aplicación en ejecución desde el exterior con un cliente real.

Una reclamación que requiere el nivel 3 nunca podrá ser satisfecha con un pase de nivel 2. La descripción de la habilidad expresa claramente esta asimetría: se permite que una observación en tiempo de ejecución demuestre la falsedad de una reclamación sobre el wire, pero nunca que la confirme.

Superficies de verificación elegidas en el momento de la planificación

Cada hito recibe una etiqueta de superficie de verificación durante la planificación, y dicha etiqueta determina qué pruebas exigirán los controles. Una superficie API requiere una respuesta capturada fuera del proceso, además de un documento OpenAPI al que sea posible acceder realmente. Una superficie UI requiere salida renderizada. Designar como medio de transporte a un cliente de pruebas en tiempo de ejecución como WebApplicationFactory o supertest se considera un fallo del control, no una solución inteligente.

Capturas con sidecars con evidencia de manipulación

La evidencia se recopila como una captura: un comando ejecutado a través de un envoltorio silencioso que guarda la salida junto con un archivo auxiliar generado por la máquina. Este archivo auxiliar registra los parámetros de comando, el directorio de trabajo, el ID del proceso, las marcas de tiempo, el código de salida real y los hashes de ambos archivos. Gates vuelve a calcular esos hashes, por lo que editar una captura posteriormente rompe la verificación.

Ese estándar luego se extendió a todos los lugares donde una afirmación había sido considerada como una sentencia. Una entrada de cobertura que solo dice “PASS, done” se marca como UNEVIDENCED y se trata como no cubierta. Los agentes de seguridad e inicio deben finalizar cada una de sus líneas de verificación señalando a la captura correspondiente. Además, cada persona cuenta con una salida honesta: si no se pudo realizar la verificación, el resultado es BLOCKED, nunca PASS, y debe indicarse qué faltó. Como dice el proyecto, “verificado” es una descripción, no una prueba.

La escotilla de escape BLOQUEADA es tan importante como las reglas estrictas. Si las únicas opciones de un agente son APROBAR o fallar, se encuentra bajo presión para inventar una forma de APROBAR. Al darle un tercer estado legítimo, se reduce en gran medida esa presión.

Auditoría de los auditores: versión 2.1.0

Un comprobador de metadatos añadido durante una fase de reforzamiento detectó dos habilidades cuyas descripciones en YAML no se podían parsear sin generar error alguno. bgpdd-verify nunca había sido registrado desde el día en que se lanzó, y doubt-driven-development no había sido registrado ni una sola vez desde el commit inicial. Antes de que existiera este comprobador, una auditoría completa del plugin había arrojado un resultado positivo en las dieciocho métricas evaluadas.

Las correcciones de esta versión subsanan todas las discrepancias entre lo que una verificación parecía comprobar y lo que realmente comprobaba:

• El comprobador de errores se ejecuta ahora primero en cada auditoría: analiza los archivos antes de leer cualquier texto.
• Los registros del libro mayor están ahora vinculados mediante hash, por lo que se puede detectar la inserción, edición o eliminación de un registro.
• Marcar como completado un hito ahora implica escribir un script en lugar de que el modelo teclee tres caracteres.
• El cliente de prueba registrado en una captura debe provenir de una lista blanca de clientes reales.
• La evidencia de la interfaz de usuario renderizada debe ser una imagen real: no vacía, con los bytes especiales correctos y más reciente que los archivos modificados. Esto surgió después de que se descubriera que un screenshot.png de cero bytes cumplía con la verificación anterior.
• El texto del veredicto que aparece en un ejemplo entre viñetas o debajo de un encabezado de apéndice se ignora al determinar el resultado de la revisión. Anteriormente, un bloque ilustrativo reemplazaba silenciosamente una solicitud real de cambios.

El caso de la captura de pantalla sirve como un buen recordatorio de que los agentes se optimizan en función de lo que realmente verifica la comprobación. Si la comprobación es “existe un archivo con este nombre”, eventualmente aparecerá un archivo de cero bytes.

Un canal de corrección de errores basado en pruebas grabadas

La orden de corrección de errores para un solo agente se comportaba originalmente como la de un desarrollador apresurado: leer el código, modificarlo, ejecutar algo y hacer un commit. Durante su primera evaluación completa, el sistema registró que la corrección se había realizado diecisiete minutos antes de que se ejecutara cualquier comprobación.

La versión 2.2.1 reestructuró este canal en seis fases, con una comprobación entre cada una:

• Un informe de error que debe superar una verificación de formato.
• Una captura RED realizada por el probador antes de modificar cualquier código, para documentar el fallo.
• Un paso de enrutamiento decidido por un script y no por el modelo, que selecciona la ruta más rápida, la ruta completa o la escalada al equipo de planificación.

La corrección en sí misma.

Una captura VERDE del comando idéntico, validada por un script que exige que ambas capturas tengan sidecars, el mismo argv, una salida distinta de cero para ROJO, una salida cero para VERDE, y que GREEN sea más reciente.

Un revisor nuevo, seguido de la puerta de commit.

En el caso de errores impredecibles, la vía puede requerir N ejecuciones verdes desde N procesos distintos, ya que superar cuatro de cinco pruebas no implica que el error esté corregido. Además, el generador no tiene capacidad alguna para realizar commits.

Vías para cambios pequeños

Hasta la versión 2.3.0, el plugin gestionaba bien los proyectos grandes pero no contaba con nada para tareas menores. Los cambios de nombre, ajustes en la configuración o la adición de un solo test no tenían vía asignada, por lo que se realizaban a mano, y la disciplina desaparecía precisamente en el nivel donde es fácil pasar por alto errores.

Las adiciones:

• /bg, una puerta de entrada que clasifica cada solicitud y la envía a un único canal.
• /bgpdd-quick para cambios que afectan a menos de tres archivos. No genera agentes; solicita una breve nota de tres líneas, captura una sola verificación y finaliza con una puerta que realiza el commit.
• Un gancho de sesión siempre activo para que una sesión de chat ordinaria sepa que existen los canales.
• Un paquete de revisión: al revisor se le entrega el propio diff, procesado y hashificado, en lugar de rutas de archivos para navegar en un árbol de trabajo, donde una corrección ya parece ser el estado actual y una línea eliminada es invisible.

Ese último punto merece ser adoptado incluso sin agentes. Revisar archivos en su estado final oculta los cambios; revisar el diff los muestra.

Uso de auditorías para encontrar la siguiente puerta

La versión 2.4.0 surgió de una auditoría de 21 métricas realizada en la versión 2.3, que identificó seis métricas problemáticas. Dos ejemplos: los agentes de seguridad y de lanzamiento seguían pudiendo marcar una verificación como APROBADA sin ninguna evidencia que lo respaldara, y no había nada que comparara el código de salida del cuerpo de captura con el del sidecar. Incluso la estructura de integración del plugin contenía una captura cuyo sidecar estaba fechado 223 días después que ella.

Las correcciones vinculan las reclamaciones con los archivos. Cada verificación que se ejecuta en esos informes ahora indica el nombre de su captura, cuyo sidecar debe estar presente, ser consistente en su hash y coincidir con el código de salida indicado en la línea correspondiente. Cualquier punto de control que utilice una captura también compara su contenido con su sidecar. El registro de bloqueos cuenta ahora con un esquema estructurado que incluye la gravedad y el alcance del hito. El equipo también midió el costo de una evaluación de disparador, que en ese momento era aproximadamente 1,77 dólares y 250 segundos por ejecución, y utilizó esa cifra para decidir con qué frecuencia realizarlas.

Una auditoría posterior realizada en la versión 2.6.0 utilizó nueve lentes y las mismas 21 métricas, y confirmó la existencia de 23 bloqueos, todos resueltos en la versión 2.6.1. Dos casos destacan. La procedencia de las pruebas no se pudo determinar: el desarrollador y el revisor compartían un único directorio de pruebas, por lo que una revisión que no arrojó resultados podía referirse a la captura de pantalla del desarrollador. Además, en un entorno sin herramientas del navegador, un hito de la interfaz de usuario quedó atascado: no podía cumplir con los requisitos establecidos, y el sistema rechazó la única alternativa, que era revisar únicamente el código fuente.

The fixes split evidence directories by producer, made UI milestones stop and ask the user when no browser is available instead of looping, and insisted, without exceptions, that a capture match the command its note says was executed. Wake-up payloads were slimmed by moving rationale out of the core persona text into references, without losing any rules. The changelog also gained a "Known, not fixed" section, because a commit gate that would accept an entirely forged evidence base is a limit that should be documented rather than hidden.

From checking afterwards to refusing beforehand

Up to release 2.5.0 every gate ran after the fact, and the model still decided whether to run it. A rule like "do not commit by hand while a lane is active" can still be read and ignored.

La solución fue un gancho PreToolUse que bloquea las llamadas a las herramientas antes de que se ejecuten. Se niega a:

• realizar un git commit manual mientras haya una ruta activa
• editar un archivo de prueba ya existente durante la corrección de errores
• iniciar un subagente mientras el proceso de entrada aún no se haya completado
• realizar cambios manuales en cualquier archivo generado por una barrera de control

Para determinar si una ruta está activa, el gancho inspecciona los archivos de estado en el disco y los considera vigentes durante 12 horas; nunca confía en lo que dice el modelo sobre su propio estado. También falla inmediatamente ante cualquier error interno. Ese es un compromiso deliberado: una protección que interrumpa las sesiones será desinstalada, y una protección desinstalada no impone ninguna restricción.

La versión también incluyó un controlador que emite el siguiente paso obligatorio en lugar de depender del Orquestador para recordarlo, además de un validador para las transferencias de agentes. El validador verifica que existan los caminos mencionados, que los archivos listados como modificados estén realmente en la diferencia, y marca contradicciones como un estado de BLOQUEADO junto a una línea de bloqueos que dice “Ninguno”.

Cubriendo el trabajo entre funcionalidades

Antes de 2.6.0, varios tipos de tareas de ingeniería rutinarias no contaban con ninguna metodología, entre ellas la actualización de dependencias, la introducción de flags de funcionalidades, la creación de tareas en segundo plano, la adición de capacidades de observabilidad y la modificación de contratos API. Los agentes las resolvían de forma improvisada. El equipo de desarrollo rápido también adivinaba el comando de prueba del proyecto.

La versión añadió cinco habilidades para esas áreas, cada una con un contrato de ejecución y una evaluación que verifica dicho contrato. Un detector de pilas ahora propone la orden de verificación y los elementos de prueba congelados del repositorio, y una persona los confirma en lugar de que la vía lo elija silenciosamente. Para los hitos de API, la puerta de confirmación también ejecuta una comparación OpenAPI, lo que significa que no se puede implementar un cambio que rompa funcionalidades sin una justificación por escrito. Cada vez que había al menos dos opciones candidatas para una decisión de diseño, se requería un ADR, y un herramienta de análisis verificaba que el registro de diseños hiciera referencia a él. Finalmente, cada metodología obtuvo una “tarjeta rápida”: las cinco reglas importantes para cambios en tres archivos o menos, cada una con un enlace a su sección completa, de modo que la vía rápida pueda cargar una tarjeta breve en lugar del contrato completo.

Conviertiendo lecciones antes de que se conviertan en hábitos

La versión 2.6.2 surgió de una situación realmente épica. Quinn fue reasignado cuatro veces para resolver el mismo problema del entorno, lo que consumió unos 1.2 millones de tokens. Una transferencia marcada como COMPLETA indicaba que el artefacto seguía lleno de marcadores tipo TODO. Además, volver a activar un agente existente se registraba como una nueva asignación, lo que inflaba el registro de ejecución.

El proceso de aprendizaje identificó tres lecciones y las convirtió en pasos obligatorios antes de aplicarlas. Una transferencia cuyo artefacto aún contiene estructuras temporales ahora falla en la validación. Una reactivación se registra simplemente como tal. Y cuando el obstáculo solo puede ser resuelto por un humano, como una credencial faltante o un servicio que se niega a iniciarse, el flujo de trabajo se detiene y solo puede reanudarse con una orden explícita dada por una persona. Esa interrupción es precisamente lo que habría permitido ahorrar la mayor parte de esos 1.2 millones de tokens.

Detección de pruebas que se prueban a sí mismas

La versión 2.7.0 solucionó uno de los hallazgos más preocupantes. En un proyecto real, trece de las veinte especificaciones de Playwright generadas por los canales resultaron ser falsas. Dichas especificaciones volvían a implementar la función que se estaba probando, ya sea directamente o dentro de una llamada a page.evaluate, y luego verificaban su propia copia. Este tipo de prueba muestra color ROJO y luego VERDE en cada ejecución, de forma trivial, y el sistema de control de colores no puede detectarlo porque la tautología supera ambas etapas.

check_test_authenticity.py ahora se ejecuta en cada captura de color ROJO en cualquier canal que genere pruebas. Busca cuatro tipos de especificaciones falsas:

• una especificación que no importa nada del código de producción
• una reimplementación directa del código que se está probando
• la evaluación del texto fuente
• un DOM sintético que sustituye a la aplicación real

Al calibrarse con ese conjunto real, rechaza exactamente los trece falsos y acepta las siete especificaciones genuinas, sin codificar de forma fija ningún nombre de archivo. La metodología de pruebas también incorporó lo que denomina prueba de eliminación: si una prueba sigue pasando después de eliminar el código en producción que supuestamente cubre, se trata de un hallazgo crítico. Es una verificación mental rápida que se puede aplicar a cualquier prueba, ya sea escrita por humanos o no; nuestro artículo sobre anti-patterns en las pruebas de React aborda formas relacionadas en las que los conjuntos de pruebas generan confianza falsa.

Lecciones de otra herramienta de revisión de código

Para la versión 2.7.1, los mantenedores analizaron el sistema de revisión de código abierto de Alibaba, que según se informa alcanza una precisión de aproximadamente el 34% en pruebas públicas, en comparación con entre el 7% y el 16% cuando Claude Code realiza revisiones sin ayuda, utilizando modelos idénticos. Estas cifras deben considerarse como la interpretación del proyecto de dicha prueba en ese momento y no como un resultado independiente. La observación interesante fue que las dos plantillas de evaluación eran casi idénticas. La diferencia radicaba en los elementos estructurales: una lista fija de archivos que deben incluirse obligatoriamente, los archivos generados se eliminan antes de que el revisor vea las diferencias, un límite de tamaño y una fase de verificación de hechos que solo permite descartar un hallazgo por uno de dos motivos especificados.

Dos incidentes de evaluación se integraron en la misma versión. Una evaluación sin interfaz gráfica que no contaba con un repositorio Git en sus archivos de prueba buscó uno en toda la máquina e interrogó un sistema real de seguimiento de problemas. Además, una ejecución de corrección de errores con plugins costó 11,06 dólares pero no generó ninguna prueba capaz de fallar con la versión defectuosa, lo que significa que nadie se daría cuenta si se revertía la corrección.

Los cambios resultantes son los siguientes:

• La puerta de control de commits rechaza una aprobación si aparece alguna hallazgo crítico o importante sin resolver en cualquier sección de revisión. En efecto, el veredicto se calcula a partir de los hallazgos, y una expresión regular confirma dicho cálculo.
• Sin una línea de revisión dedicada para cada archivo en la diferencia, el commit se rechaza.
• El paquete de revisión elimina archivos de bloqueo, archivos minificados y archivos generados a cualquier profundidad, enumera lo que ha quitado y rechaza diferencias de más de 1.500 líneas a menos que una persona escriba una exención.

Cada reunión informativa para los desarrolladores en una evaluación sin interfaz ahora repite un preámbulo sobre el alcance, y un mecanismo de detección aísla cualquier ejecución que se salga de su área de trabajo.

Las evaluaciones de resultados incorporaron un nuevo criterio: una solución solo cuenta si se incluye una prueba de regresión que mostraría un resultado negativo si la solución se revirtiera.

Una auditoría del registro de cambios encontró cinco commits publicados sin ninguna entrada correspondiente, y esos fueron cerrados.

La comparación no fue unilateral. Los 51 documentos de reglas de lenguaje de la otra herramienta no contenían información alguna para C#, Vue, PowerShell o SQL, lenguajes que recurren a una lista de verificación genérica; y precisamente esos son los entornos que abarcan las habilidades de este plugin.

Una segunda lectura generó tres reglas de precisión en la sección 2.7.2, añadidas antes de que cualquier fallo las exigiera. El revisor puede leer cualquier archivo para obtener contexto, pero los hallazgos se limitan a los archivos que forman parte del diff empaquetado; las observaciones sobre otros archivos se convierten en una nota fuera de alcance para el Orchestrator. La metodología de bases de datos incorporó una regla de inyección con una lista explícita de elementos que nunca deben reportarse, como enlaces parametrizados y declaraciones estáticas, ya que un hallazgo falso en código correcto hace que los revisores pasen por alto los reales. Además, la metodología de seguridad ahora exige una estructura de cinco secciones para los documentos de seguridad, y cada categoría OWASP incluida debe contar con una cita o una respuesta fundamentada de “No aplica”, ya que dejar una fila en blanco no constituye un veredicto.

Dónde se encuentra el proyecto

En el momento de escribir esto, el plugin cuenta con 16 personajes de agente, 45 habilidades y 32 scripts de control, además de 1,656 pruebas automáticas. Todos esos scripts son deterministas y no realizan llamadas a modelos de lenguaje grande; además, se ejecutan antes de cada lanzamiento. El conjunto de pruebas incluye 69 casos distribuidos en cuatro niveles; el nivel de resultados compara ejecuciones con el plugin activo y desactivado frente a pruebas ocultas, en lugar de verificar si se activó un camino específico. Desde la primera versión, 119 commits han añadido unas 67,000 líneas de código.

La métrica que los mantenedores afirman importarles realmente no es ninguna de estas. Se trata del número de reglas que siguen siendo descripciones en prosa que piden al modelo que se contenga justo en el momento en que más desea continuar. Esa cifra disminuye con cada lanzamiento, y cada disminución se debe a algún problema observado mientras la regla estaba activa.

Puntos clave

• Trate una regla que se violó mientras estaba en vigor como un informe de error contra dicha regla, y corríjala mediante una compuerta de control, no con redacciones más estrictas.
• Deje que los scripts realicen acciones irreversibles como los commits, de modo que una verificación omitida deje una ausencia visible en lugar de un paso silencioso.
• Defina niveles de evidencia y exija la salida del comando, hashada, en lugar de una frase que diga “verificado”.
• Ofrezca a los agentes un resultado LEGÍTIMO de BLOQUEADO para que inventar un resultado de APROBADO nunca sea el camino más fácil.
• Pruebe cada compuerta de control observando cómo falla ante una violación intencionada, y realice auditorías de las propias compuertas, ya que las verificaciones tienden a centrarse en los nombres de pruebas y en la existencia de archivos.
• Bloquee las llamadas a herramientas peligrosas antes de que se ejecuten, pero haga que la protección permita el paso para que nadie sienta tentaciones de eliminarla.

Aplique la prueba de eliminación a las pruebas generadas: si eliminar el código de producción no rompe la prueba, esta carece de valor.

El método consiste en un bucle: observe una ejecución, encuentre la instrucción que fue ignorada, cámbiela por algo que debe ejecutarse o abrirse, y observe la siguiente ejecución.

Lecturas relacionadas

• Dónde pertenecen las instrucciones de Claude Code: CLAUDE.md, reglas de ruta o gancho — Aprenda por qué Claude Code trata a CLAUDE.md como contexto, cómo reducirlo, aplicar reglas por ruta, mover los pasos obligatorios a ganchos y verificar qué se cargó realmente.
• Un plan práctico para escribir un archivo CLAUDE.md efectivo — Aprenda 21 reglas concretas y verificables para reducir el tamaño de un archivo CLAUDE.md excesivo, de modo que Claude Code siga siendo fiable, predecible y digno de confianza durante sesiones prolongadas.
• Enseñando a Claude Code tus reglas y habilidades de enrutamiento en un monorepo NestJS — Cómo configurar CLAUDE.md, reglas, habilidades y permisos para que Claude Code coloque el código en el servicio NestJS adecuado y siga las convenciones de su equipo.
• Impresión de Reglas en el Código: PreToolUse, PostToolUse y Stop Hooks — Aprenda por qué la autorización de los agentes LLM debe estar en los ganchos deterministas de llamada a herramientas, cómo denegar llamadas de forma segura y cómo envolver un distribuidor sin recursión.