Crear un subagente que audita endpoints de Laravel

Hola, bienvenido. En la lección anterior vimos qué es un subagente, cómo trabaja hoy y cómo se crea sin el asistente de /agents, y en esta lección vamos a escribir el primero de claude-tasks: route-contract-auditor. Es un subagente que revisa de una sola vez todas las piezas de un endpoint de Laravel, desde la ruta hasta los tests, y te devuelve un veredicto con los hallazgos y dónde está cada uno. Por el camino vamos a separar algo que se suele mezclar al escribir subagentes: qué parte de su comportamiento es una instrucción que Claude intenta cumplir y qué parte es una restricción que Claude Code aplica aunque el modelo no quiera.

¿Por qué empezar por un auditor de endpoints? Porque en un endpoint de Laravel los fallos suelen aparecer donde se juntan las piezas. La ruta apunta a un controlador, el controlador recibe un Form Request, el Form Request valida unos campos y autoriza o no la petición, el modelo acepta unos campos en asignación masiva y el test comprueba lo que pasa. Si el Form Request valida name pero el controlador guarda también email, o si la ruta no lleva el middleware auth y nadie lo nota porque el test siempre hace login, cada archivo por separado parece correcto y el conjunto no lo es.

Revisar esa cadena en la conversación principal implica abrir 5 o 6 archivos, y todo ese contenido se queda en tu contexto para el resto de la sesión. Es el caso de uso que vimos para un subagente: una tarea que se sostiene sola, que genera mucha lectura y que termina en un resumen. Además, un auditor no tiene por qué poder editar nada, y eso lo vamos a garantizar en su definición.

Para seguir esta lección necesitas claude-tasks con el último commit y una sesión de Claude Code abierta en la raíz del proyecto. Vamos a comprobar el archivo con claude plugin validate, que necesita la versión 2.1.233 o posterior, y el curso trabaja con la 2.1.283. Y un aviso que ya te adelanté: la carpeta .claude/agents/ todavía no existe, así que cuando la creemos habrá que reiniciar la sesión para que Claude Code la vea.

El contrato de un endpoint es lo que promete a quien lo llama: qué método y qué URI responde, quién puede llamarlo, qué datos acepta, qué hace con ellos y qué devuelve. route-contract-auditor recorre las piezas que sostienen esa promesa en una aplicación Laravel 13:

• La ruta, con su método, su URI, su nombre, su middleware y la acción del controlador.
• El controlador, que tiene que hacer una cosa y no validar en línea si ya hay un Form Request.
• El Form Request, con reglas para cada campo que se guarda y un authorize() que compruebe algo.
• La autorización, con una policy, Gate::authorize(), el middleware can o el propio Form Request.
• El modelo, con los campos asignables en #[Fillable([...])] y los sensibles en #[Hidden([...])], como ya hacen User y Task.
• La respuesta, con el código de estado o la redirección esperados y sin campos internos.
• Los tests, que tienen que cubrir el caso correcto, la validación y el acceso no autorizado.

Fíjate en que varias de esas comprobaciones coinciden con la guía de seguridad que escribimos para el plugin security-guidance en la lección Revisar la seguridad del código con Claude Code: qué usar y cuándo. Tiene sentido, porque los 2 miran el mismo código, pero trabajan en momentos distintos: el plugin revisa cada cambio mientras Claude escribe, y el auditor revisa un endpoint entero cuando se lo pides, incluidos los tests y la forma de la respuesta, que no son cosa del plugin.