Funciones de los agentes

Coroid no utiliza un único agente de uso general. Cada fase del proceso desde la descripción hasta pull request es gestionada por un agente con una función específica y un conjunto de herramientas deliberadamente limitado.

Estas restricciones son esenciales. Un agente que no puede escribir código no podrá escribir código por error.

Las funciones#

Función	Fase	Puede modificar tu código
Arquitecto	Especificación y plan	No
Desarrollador	Compilar	Sí
Control de calidad (QA)	Verificar	No
Revisor	Revisión	No
Probador web	Verificar flujos del navegador	No
Explorador	Investigar, cualquier fase	No
Analizador de dependencias	Análisis	No

Los cuatro primeros son los agentes de entrega que aparecen en todas las tareas. En modo estándar, se ejecutan en este orden:

Arquitecto → Desarrollador → Control de calidad (QA) → Revisor

En modo Coordinador, un coordinador determina el orden durante la ejecución de la tarea. Ambos modos se describen a continuación.

Solo un rol —el desarrollador— puede modificar archivos en tu repositorio. Todos los demás agentes solo leen, ejecutan, generan informes o crean tareas de seguimiento.

Dos formas de ejecutar una tarea#

Una tarea se ejecuta en uno de los dos modos. Su AI profile y tu despliegue determinan cuál se utiliza.

Modo coordinador. El arquitecto no entrega su plan y se retira. Permanece en la tarea como coordinador. Tras la planificación, el coordinador proporciona las instrucciones al desarrollador y espera el informe. Luego solicita al equipo de control de calidad que verifique lo desarrollado y al revisor que analice lo aprobado por el equipo de control de calidad. Después de cada informe, el coordinador decide qué hacer a continuación: enviar los hallazgos de vuelta al desarrollador, responder una pregunta, revisar el plan o finalizar la tarea. La reelaboración constituye un paso adicional para el coordinador, no una nueva ejecución.

Modo estándar. La plataforma hace avanzar la tarea por los cuatro agentes en un orden fijo, y si una comprobación falla, la devuelve al desarrollador. Algunos trabajos siempre se ejecutan así, como resolver un conflicto de fusión, y el modo estándar es la alternativa cuando el modo coordinador no está disponible.

En ambos modos, los mismos agentes realizan el trabajo con las mismas restricciones y los mismos filtros de control. Lo que varía es quién determina el siguiente paso: la plataforma en modo estándar o el coordinador en modo Coordinator.

El coordinador#

El coordinador es el agente de planificación que permanece vinculado a la tarea. Lee tu base de código y no puede modificarla, por lo que todas sus acciones consisten en orientar el proceso.

Qué hace el coordinador#

• Planificaciones. El coordinador explora el repositorio y luego guarda el plan con los criterios de aceptación que determinan si la tarea se completó con éxito.
• Se delega. El coordinador trabaja con un agente a la vez. Sus instrucciones indican el objetivo, los criterios de aceptación que requieren atención especial y, al devolver el trabajo, las correcciones exactas a aplicar. Mientras el agente trabaja, el coordinador espera sin consumir tiempo de modelo.
• Responde preguntas. Un agente que necesite tomar una decisión puede consultar al coordinador. El coordinador responde con la decisión y el motivo. De este modo, la pregunta no queda pendiente de resolución por parte de una persona.
• Reacciona. Si la fase de control de calidad falla o el revisor solicita cambios, el coordinador envía las correcciones al desarrollador y el control de calidad verifica la nueva versión.
• Finaliza la tarea. El coordinador finaliza la tarea o la marca como fallida y explica el motivo.

Qué no puede hacer el coordinador#

El coordinador guía el proceso; no realiza la evaluación. La plataforma aplica estos límites, por lo que no dependen de las decisiones del coordinador:

1. Los veredictos corresponden al equipo de control de calidad y al revisor. Solo el equipo de control de calidad y el revisor emiten veredictos, cada uno con su propio resultado. Las instrucciones del coordinador no incluyen la emisión de veredictos, y el coordinador no puede marcar una comprobación como aprobada.
2. Para finalizar, se requieren las validaciones necesarias. Una tarea solo puede finalizarse cuando el control de calidad haya validado la versión exacta que se entregará (o el código tal como está si no hay cambios) y, cuando la tarea requiera revisión, el revisor haya aprobado esa versión. Si la rama cambió después de ejecutar el control de calidad, se rechazará la finalización y la nueva versión volverá al control de calidad.
3. El trabajo adicional está limitado. Cada agente puede iniciarse únicamente un número limitado de veces por tarea, y un plan solo se puede revisar unas pocas veces. El número de pasos y el tiempo total de ejecución también están limitados. Al alcanzar dicho límite, el coordinador solo podrá finalizar o marcar la tarea como fallida.
4. La espera está acotada. Toda espera tiene un plazo límite.

Así, una tarea gestionada por un coordinador concluye de una de estas tres maneras: un pull request para que tú lo apruebes; la confirmación del control de calidad de que el código ya cumple con lo solicitado en la tarea, por lo que no hay nada que modificar; o una tarea fallida que indica el motivo. No finaliza simplemente porque el agente encargado lo declare completado.

Rutas que puede seguir un coordinador#

El coordinador decide cómo una tarea accede a las etapas de validación. Las etapas mencionadas anteriormente son las mismas en todas las rutas.

• La ruta completa. Planificar, desarrollar, verificar, revisar, finalizar. Así se ejecuta una tarea salvo que el coordinador tenga motivos para seguir otra ruta.
• Devolver el trabajo. Cuando el control de calidad rechaza el trabajo o el revisor solicita cambios, las correcciones vuelven al desarrollador. La nueva versión debe superar el control de calidad antes de que la tarea pueda finalizarse. La aprobación de la versión anterior no se transfiere a la nueva.
• Ya hecho. Es posible que el código ya cumpla con lo solicitado en la tarea. En ese caso, el coordinador puede pedir al control de calidad que verifique el código sin modificaciones frente a los criterios de aceptación en lugar de generar algo nuevo. Si el control de calidad lo aprueba y el revisor da su visto bueno cuando corresponde, la tarea finaliza sin necesidad de un pull request, ya que no hay nada que fusionar. La verificación del control de calidad es el resultado final. Esta ruta se cierra una vez que la ejecución genera algún cambio propio, ya que de lo contrario el control de calidad aprobaría código que no es el que se entregará.

Existen dos rutas más cortas opcionales. Coroid no las utiliza por defecto. Cambian la ruta del coordinador, nunca las etapas de validación:

• Un cambio rápido. Para una corrección pequeña en un lugar conocido, el coordinador elabora un plan más breve y proporciona al desarrollador instrucciones específicas que indican los archivos afectados por el cambio. El desarrollador trabaja dentro de un presupuesto de pasos menor, y cualquier modificación fuera de esos archivos se notifica al control de calidad y al revisor.
• Una revalidación más específica. Tras una corrección pequeña detectada por el control de calidad o el revisor, el control de calidad comienza desde ese hallazgo y las pruebas del proyecto. No obstante, emite su veredicto sobre la versión completa actualizada.

Cuándo se requiere un revisor#

Por defecto, una tarea que ejecutas por tu cuenta siempre pasa por el revisor. Independientemente de la ruta que siga el coordinador, incluso cuando no sea necesario realizar cambios, la tarea no puede finalizarse hasta que el revisor apruebe la versión validada por el control de calidad. El control de calidad siempre realiza la verificación, con o sin revisión, y la revisión nunca sustituye la aprobación del control de calidad. Las tareas que forman parte de un plan siguen las reglas de su categoría correspondiente.

Coroid también incluye una política opcional basada en el nivel de riesgo. Esta no está activada por defecto. Bajo esta política, una tarea que ejecutes de forma independiente puede finalizarse sin necesidad de revisión si el cambio es pequeño y común. El revisor sigue siendo obligatorio cuando:

• ya se haya iniciado la revisión de la tarea, o las reglas de revisión de tu proyecto o el Quality Graph de tu organización lo exijan;
• el cambio afecte a la autenticación, sesiones, permisos, secretos o criptografía, migraciones de base de datos, configuración de compilación y despliegue, archivos de dependencias o código que se comunique con servicios externos;
• el cambio sea grande (por defecto, más de 80 líneas modificadas) o incluya archivos binarios, enlaces simbólicos o submódulos;
• Coroid no puede interpretar la política ni el propio cambio. En caso de duda, la revisión es obligatoria.

Un cambio que no altera nada nunca necesita revisión. La decisión la toma el código, no el coordinador, y este no puede ignorar ese criterio. Al final de la descripción de la pull request se indica el motivo y el resultado: comienza con «Revisor requerido» o «Revisor no requerido».

Arquitecto#

Convierte tu descripción en una especificación y la especificación en un plan. Lee el código fuente para adaptar el plan a lo que realmente existe, pero no escribe ningún código.

Su resultado es lo que debes aprobar antes de iniciar la compilación. En modo Coordinator, este agente sigue actuando como coordinador.

Desarrollador#

Realiza el trabajo: lee el código correspondiente, realiza los cambios, escribe o actualiza las pruebas y las ejecuta localmente en el espacio de trabajo hasta que se superan.

Cuando el Revisor envía los Hallazgos de vuelta, el Desarrollador El coordinador es el rol que actúa sobre ellos. En modo Coordinator, el Coordinador transmite los Hallazgos junto con las correcciones a aplicar.

Control de calidad#

Realiza la verificación de forma independiente del agente que escribió el código: tu suite de pruebas, las puertas de calidad configuradas para el proyecto y los criterios de aceptación establecidos en la especificación.

El equipo de control de calidad emite un dictamen. No corrige los hallazgos detectados; los errores se devuelven al Desarrollador como reelaboración.

Revisor#

Lee el diff finalizado y genera Hallazgos, aplicando las reglas de Revisión configuradas en tu organización. Los Hallazgos se envían de vuelta al desarrollador para que realice la reelaboración o se adjuntan al pull request para tu revisión.

Probador web#

Utiliza un navegador real para probar una vista previa en ejecución de tu aplicación y verificar los flujos de usuario de extremo a extremo. Se emplea cuando no es posible determinar el comportamiento a partir del código únicamente.

Explorador#

Es un rol de investigación de solo lectura. Otros agentes lo utilizan para responder preguntas sobre el código base sin necesidad de cargar toda la información en su propio contexto: "¿dónde se gestiona la autenticación?", "¿qué llama a esta función?".

Analizador de dependencias#

Examina las dependencias y cómo los cambios se propagan por todo el código base, incluso en proyectos donde existen dependencias entre proyectos configuradas.

Por qué es importante esta separación#

De esta forma de dividir el trabajo se derivan cuatro propiedades clave:

1. La verificación es independiente. El agente que revisa el trabajo no es el mismo que lo redactó, por lo que no tiene interés personal en el resultado.
2. El alcance del impacto está delimitado. Solo el rol de desarrollador dispone de herramientas para escribir código; por tanto, un fallo en la revisión o en el análisis no puede dañar tu repositorio.
3. Cada rol utiliza un modelo adaptado a sus necesidades específicas. La planificación requiere un amplio conocimiento del entorno; la escritura de código que compile exige otra cosa distinta. AI profile Incluye un modelo por rol precisamente por este motivo.
4. La finalización de la tarea se determina mediante comprobaciones, no por el agente encargado de ella. En modo Coordinator, el coordinador que dirige la tarea no puede finalizarla sin los dictámenes del equipo de control de calidad y del revisor.

Siguiente#

Volver a Cómo una tarea se convierte en pull request para ver las etapas a las que se asignan estos roles, o ¿Qué es Coroid? para obtener un resumen más breve.