Los agentes personalizados están en beta. El comportamiento y las pantallas aún pueden cambiar.
Un agente por tema
Un agente que revisa arquitectura, seguridad y cobertura de pruebas a la vez tiene instrucciones vagas y produce hallazgos vagos. Divídelo: un agente por tema, cada uno con sus propios archivos, guías y etiqueta. La etiqueta le dice al equipo quién habla, y la página de cada agente muestra lo que publicó en los últimos 30 días, así ves cuál hace ruido.Escribe instrucciones enfocadas
Escribe las instrucciones como un brief para un revisor que conoce el código. Cubre tres cosas:- Qué buscar, en concreto: “imports de
src/domainensrc/http”, no “problemas de arquitectura”. - Qué ignorar: estilo, nombres, cosas que ya cubre otro agente o Kody.
- Qué prueba necesita un hallazgo: “nombra el archivo que muestra el patrón existente”, “muestra el camino desde el origen hasta el destino”, “cita la regla de
docs/ledger.md”.
- Vaga
- Enfocada
Di qué prueba necesita un hallazgo
Los hallazgos se verifican antes de publicarse. Dale al agente algo que pueda probar:- Una regla en una guía: vincula el doc o la skill y pide al agente que cite la regla. La cita se verifica en la guía de la rama de destino.
- Un resultado de CLI: las líneas de salida de la CLI que nombran el archivo van al comentario como evidencia.
- Una regla de ast-grep: una coincidencia cuenta como prueba por sí sola, sin verificación del modelo.
Haz los globs explícitos
- Define Files con el código que le importa al agente:
src/payments/**, no vacío. Un agente sin globs se ejecuta en todo pull request. - Usa Except para pruebas, fixtures y código generado.
- Nombra los archivos explícitamente cuando están en tus rutas ignoradas y el agente igual debe leerlos:
package.json,infra/**/*.tf. Un glob amplio como**/*.ts, o una carpeta comosrc/**, no llega a archivos ignorados. - En un directorio, los globs siguen empezando en la raíz del repositorio.
¿Skill o doc?
Los docs cuentan contra un presupuesto de 20.000 tokens por agente. Un manual largo funciona mejor como skill con archivos de referencia.
Prueba en un pull request real antes de activarlo
Un agente nuevo empieza apagado. Antes de activarlo:- Elige un pull request reciente que toque los archivos del agente, idealmente uno en el que sepas qué diría un buen revisor.
- Ejecuta Try it. Lee las llamadas a herramientas, las skills que abrió y cada hallazgo.
- Ajusta las instrucciones, los globs o la severidad mínima, y vuelve a ejecutar.
- Actívalo cuando los comentarios que se publicarían sean los que quieres ver en un pull request.
@kody -v <nombre> hace lo mismo en un pull request real, publicando los comentarios, mientras el agente sigue apagado.
Lee los motivos de descarte
Los hallazgos descartados te dicen qué corregir en el agente:Mantén el volumen adecuado
- Define Max comments per pull request en agentes que pueden producir muchos hallazgos, como un agente de código duplicado. Se conservan los más graves.
- Usa One PR comment para agentes cuyos hallazgos se leen mejor juntos, como un reporte de cobertura.
- Usa Suggested fix: Never cuando un fix sería una suposición, como mover algo de arquitectura.