Capítulo 13: Agentes y revisores

[ GUÍA ]Capítulo 13 de 18

Agentes y revisores

Los seis agentes revisores de solo lectura y el agente ayudante mecánico, sus herramientas, modelos y controles, el formato de salida y la regla de enmascarado que comparten, y el protocolo de revisión con su vuelta de correcciones y el momento de elevar el caso.

El código y el contenido de los archivos quedan en inglés, como en el repositorio público de la guía.

Cómo está hecho un revisor

Todos los revisores siguen el mismo patrón:

  1. Solo lectura por su lista de herramientas: tools: Read, Glob, Grep (más las herramientas de solo lectura de la herramienta de diseño, para el revisor de marca, y WebFetch para las fechas del registro de paquetes, para el revisor de code-stack). No puede editar porque no tiene ninguna herramienta para editar.

  2. Dos líneas de apertura, escritas palabra por palabra en el archivo del agente y en cada envío. La línea de solo lectura:

    You are read-only. You may use Read, Grep and Glob (and the design tool’s read tools where listed). You never edit, write, run shell commands or call write tools. If a fix is needed, describe it; the main session applies it.

    La línea de enmascarado:

    Never repeat personal information in your output: replace a name or street address with the participant ID or [name] / [address], and mask any other identifier (first two and last two characters, the rest *; six characters or fewer become ****).

  3. Lista para leer primero: los archivos de gobernanza que son su lista de control.

  4. Controles numerados, cada uno citable como Rule: <n>.

  5. Salida fija, el mismo bloque en todos los revisores. El bloque abre con Return only this, no narrative: y después:

    VERDICT: APPROVE | REQUEST FIXES
    Scope: <what you reviewed>
    Inspected: <every file path you opened, plus any design-tool query or registry URL>
    Findings:
    1. File: <path> | Location: <line, heading, card or node> | Fails: <what> | Would pass: <what> | Rule: <check number>

    Y cierra con: If there are no findings, write `Findings: none`. Report only what you verified in files. Un revisor puede agregar líneas después del bloque (por ejemplo, los agregados que propone el revisor de marca para la lista de patrones a evitar); nunca cambia el bloque. El Apéndice B escribe completos estas líneas y el bloque en cada archivo de agente.

  6. Modelo y esfuerzo: Opus, esfuerzo high (revisar es trabajo de criterio).

Los seis revisores

AgenteHerramientasControles
process-gate-reviewerRead, Glob, Grep1 el paso declarado coincide con la tabla de pasos; 2 el orden (ningún paso pasado mientras uno anterior no está ni pasado ni salteado); 3 criterios de cierre probados con archivos que existen; 4 formato y estado de la frase del problema, agreed con quién y cuándo si arrancó algún paso posterior; 5 que las opciones, las tarjetas y las medidas se remonten a la frase del problema; 6 nada de lenguaje que ordene las ideas en Bocetar; 7 Decidir: una sola persona que decide, de 2 a 3 opciones con beneficio y costo, el razonamiento registrado; 8 Entregar: cada estado, medidas con línea de base, meta y fuente; 9 límites de la IA (ni tipos de cliente, ni decisiones, ni sesiones hechas por la IA, ni conversaciones reemplazadas). En los planes de puesta al día: el paso inferido se muestra como propuesta y las candidatas no se marcan como agreed
prd-card-reviewerRead, Glob, Grep1 las catorce secciones del PRD del 06 presentes, Registro de decisiones incluido (el PRD de la carpeta central no queda exento de ninguna), ningún valor sin completar; 2 frontmatter completo y válido, decider presente, un solo H1 igual al título; 3 entregas: como máximo una abierta, de 2 a 5 resultados, formato de ID, una entrega cerrada tiene una declaración de seguridad con su autor; 4 las nueve secciones de la tarjeta, en orden; 5 un resultado por tarjeta, que existe en la entrega abierta; 6 exactamente una línea de FALSIFIER; 7 puertas: la cantidad En curso coincide con su marca y es ≤ 3, las tarjetas En curso pasan Empezar, las Terminadas tienen prueba, los resultados cerrados son válidos; 8 coherencia del tablero y marcas de forma; 9 los ID de excepción de marca existen; 10 ningún dato personal
brand-design-system-reviewerRead, Glob, Grep + las herramientas de lectura del servidor de Figma tal como las da el plugin figma: mcp__plugin_figma_figma__search_design_system, get_metadata, get_screenshot, get_variable_defs (mismo prefijo), más la herramienta de sesión del servidor si las búsquedas la necesitan (confirmá cada nombre en la lista de herramientas de la sesión activa)1 solo la biblioteca permitida, verificada contra la herramienta (una muestra de al menos cinco nombres más los dudosos); 2 ningún valor de diseño, valor en bruto o componente inventado, salvo que esté rotulado PROPOSAL; 3 igual para todas las marcas, salvo que exista un ID de excepción; 4 lista de patrones a evitar, más los agregados propuestos; 5 el tono coincide con el archivo de tono, tone unverified mientras sea un borrador, sin jerga, sin superlativos sin respaldo; 6 ortografía de la región. La salida agrega Proposed avoid-list additions:
accessibility-reviewerRead, Glob, GrepLista de control de WCAG 2.2 AA con los números de criterio (SC). Código: semántica, etiquetas, autocompletado, foco, ARIA, regiones que se anuncian solas, tamaño del área para tocar, reacomodo del contenido, lang, límites de tiempo. Especificaciones: cada estado con nombre accesible y anuncio, el texto de error dice cómo arreglarlo, ningún significado que dependa solo del color. Contraste solo con valores reales; si no, not verifiable. Documentos sin interfaz: solo controlar que los requisitos estén donde corresponde
code-stack-reviewerRead, Glob, Grep, WebFetch (solo metadatos del registro público)1 versiones de las herramientas fijadas; 2 versiones exactas; 3 antigüedad de versión ≥ 14 días y configuración del espacio de trabajo; 4 última versión estable; 5 archivo de versiones fijas presente y versionado en Git; 6 primero las bibliotecas propias, con sus razones; 7 sin secretos, .env* ignorado; 8 programas: operaciones destructivas protegidas, sin llamadas de red con contenido del proyecto, entradas validadas
privacy-reviewerRead, Glob, Grep1 ningún dato personal en el PRD, el README, el CLAUDE.md, las tarjetas, los resúmenes, los informes, los archivos de gobernanza ni los commits; 2 códigos de participante; 3 contains_pii: true donde haya datos personales; 4 .gitignore excluye las entrevistas y .env*; 5 los informes muestran solo cantidades y muestras enmascaradas; 6 nombres del personal anotados solo junto a datos de clientes. El revisor usa los patrones de búsqueda de <CENTRAL>/marketplace/plugins/<PLUGIN>/hooks/lib/pii.mjs (correos, formatos de teléfono, identificadores propios de cada región) y después abre cada coincidencia para juzgar el contexto

Regla de WebFetch para el revisor de code-stack: nunca un permiso general de WebFetch; permití solo WebFetch(domain:registry.npmjs.org). El revisor lee las fechas de versión del registro de npm y no manda contenido del proyecto a ningún lado.

El agente ayudante

AgenteModelo / esfuerzoTrabajoSalida
retrofit-auditorSonnet / lowLeer un proyecto y el informe de su ensayo; escribir descripciones de una oración, corregir doc_type y process_step con sus razones, encontrar hasta cinco planteos del problema que ya existan y devolverlos como frases del problema candidatas, con sus fuentes, y anotar archivos fuera de lugar, casi duplicados y datos personales que los patrones no atraparon (enmascarados)Solo JSON: inspected, frontmatter_corrections, define_candidates, missed

El protocolo de revisión

Pick reviewers → dispatch in parallel (paths, read-only line, what changed)
      │
      ▼
Validate each return ── invalid (0 tool uses / no Inspected / no VERDICT)?
      │                     └─ re-dispatch once → still invalid → review it yourself, say so
      ▼
Collect findings (file, location, fails, would pass; else propose discarding with reason)
      │
      ▼
Decider (central: administrator) approves fixes → main session applies them, records approval
      │
      ▼
Re-dispatch only reviewers that requested fixes ── loop count +1
      │
      └─ two loops without APPROVE → STOP, escalate with findings, what was tried, options

Informe: una tabla (revisor, veredicto, hallazgos, corregidos, abiertos) y después los hallazgos abiertos, textuales. Sin transcripciones del razonamiento de los revisores.

Qué revisores corren y cuándo

MomentoRevisores
Proyecto nuevoprd-card, process-gate, privacy
Informe de puesta al díaprivacy, prd-card, process-gate (+ code-stack si hay código)
PRD a partir de las entrevistasprivacy, prd-card, process-gate
Avance de un paso del procesoprocess-gate (+ prd-card si cambió el tablero)
Armado de la interfazbrand-design-system, accessibility, code-stack
Revisión de seguridad de la entregaprivacy, accessibility, brand-design-system
Cambio de gobernanzalos que cubren el área; todos para MAJOR

Cómo sumar un revisor

  1. Escribí agents/<name>-reviewer.md con el patrón de arriba.
  2. Dale la lista de herramientas más chica que le permita verificar.
  3. Sumalo a la tabla del skill review.
  4. Anotá en ENFORCEMENT.md las reglas que controla.
  5. Sacalo como versión MINOR.

Contenido de la guía