Argui

Eficiencia de recursos

El objetivo: maximizar la calidad del proyecto minimizando el consumo de tokens. Las decisiones de optimización se toman a nivel de agente individual, no de fase, porque dentro de una misma fase coexisten tareas de juicio (que requieren un modelo más capaz) y tareas mecánicas (que se ejecutan bien con un modelo económico).

Los nombres de modelos (opus/sonnet/haiku) corresponden a los tiers de Claude, pero el principio es agnóstico: tier de razonamiento alto / medio / económico en cualquier proveedor.

Principios

  1. Fijar el modelo en el agente, no en el comando. Cada agente declara su modelo en el front matter. Un mismo apply o verify puede correr implementadores en sonnet y documentadores en haiku en paralelo.

  2. Gate antes de fanout. Antes de invocar agentes costosos (especialmente arquitectura), un paso barato clasifica si el cambio realmente los necesita. La invocación incondicional de agentes caros es la principal fuente de gasto innecesario.

  3. Skills sobre subagentes cuando aplique. Un subagente que solo invoca una skill y devuelve el resultado es overhead puro: cada subagente arranca con su propio prompt y contexto. Si la tarea cabe en una skill ejecutada desde el agente padre, esa es la opción.

  4. Batch en lugar de fanout por archivo. Si un revisor debe leer 8 archivos relacionados, es una invocación que lee los 8, no 8 invocaciones que leen uno cada una.

  5. Separar la decisión de la ejecución. Decidir qué agente crear o qué arquitectura adoptar es trabajo de juicio (modelo capaz). Escribir el archivo .md del agente o aplicar el patrón decidido es trabajo mecánico (modelo económico).

  6. La lógica de invocación vive en la skill, no en el agente. Qué modelo usa un agente se fija en el agente (principio 1); cuándo se le invoca —el gate, batch vs. fanout, resolver con una skill desde el padre, qué agentes corren por acción— vive en las skills de OpenSpec que orquestan el ciclo. Meterlo en cada agente infla el frontmatter, que se carga en cada prompt de routing. La primera frase del description (rol + límites) es lo único que el orquestador necesita para desambiguar (ver agents.md).

Asignación de modelos por tipo de agente

Tipo de agente Modelo Justificación
Arquitectura opus Decisiones que se compounden a lo largo del proyecto
Investigación / exploración para PRD (Product Requirements Document) opus Define el problema y el alcance
PRD (negocio y técnico) opus Documento fundacional del proyecto
UX/UI (experiencia / interfaz de usuario) (prototipo) sonnet Construye sobre PRDs ya definidos
Backlog sonnet Estructuración sobre PRDs ya existentes
Implementadores sonnet El spec del backlog ya hizo el trabajo de pensar
Revisores (juicio) sonnet Detección de bugs sutiles y calidad de código
Revisores (cumplimiento) haiku Verificación contra checklist de estándares
Testers haiku Ejecutar Playwright y reportar outputs es mecánico
Documentadores haiku Templates + extracción
Mantenedor de CLAUDE.md haiku Resumir y podar
Analizador de MCPs (Model Context Protocol)/skills haiku Matching contra catálogos públicos
Clasificador de impacto arquitectónico haiku Decisión binaria con criterios claros

Gates del ciclo iterativo

Gate de impacto arquitectónico (antes de apply)

Un paso en haiku clasifica el cambio como architectural: true | false con criterios explícitos:

  • Introduce una nueva dependencia mayor
  • Modifica contratos entre módulos
  • Cambia el modelo de datos
  • Afecta seguridad o autenticación
  • Introduce un nuevo patrón transversal

Solo si marca true se invoca al arquitecto (opus). Esto evita pagar opus en cambios rutinarios.

Verify en dos pases

  1. Pase de cumplimiento (haiku): lo objetivo — pasan los tests, se siguen los estándares, los criterios literales del spec se cumplen, no hay archivos fuera de lugar.
  2. Pase de juicio (sonnet): calidad de código, bugs sutiles, idoneidad del enfoque. Solo se ejecuta si el pase de cumplimiento aprobó o dejó flags que requieren juicio.

Triage de QA: qué se automatiza y qué llega al humano

La fase de QA (Quality Assurance) no es “una lista enorme de pruebas manuales para el humano”. Antes de involucrar a la persona, cada verificación se clasifica — y el default es automatizar, no delegar. La lista manual es el residuo después de automatizar, no el punto de partida.

  1. Objetivo y determinista → automatizado (y, de preferencia, ya en la suite de tests). Respuestas de API (Application Programming Interface) (status, contrato, payload), estado e invariantes de base de datos, resultados de lógica de negocio, integridad de datos. Baratos de automatizar, deterministas y de alto ROI (retorno de inversión): viven como tests de integración que corren en verify y en el CI (Continuous Integration), no como items manuales. Cuando se llega a QA, lo objetivo ya está verde.
  2. Requiere juicio humano → al humano. Corrección visual y de UX, “¿se siente bien?”, exploración de casos no previstos, aceptación ambigua del stakeholder. Esto —y solo esto— es lo que por defecto recibe la persona.
  3. Automatizable pero caro (flujos E2E (end-to-end) elaborados) → gate de costo. Crear y mantener scripts Playwright consume tokens y tiempo, y los tests de UI son frágiles ante cambios de interfaz. Antes de automatizar, evaluar:
    • ¿La prueba se repetirá en ciclos futuros (regresión) o es de un solo uso?
    • ¿El flujo es crítico (definido en el PRD técnico)?
    • ¿El costo de crear y mantener el script es menor que repetir la prueba manual N veces? Si no compensa, queda manual por ahora y se anota en el artifact como deuda de automatización —que, al aplazarse, genera un candidato de backlog para la fase 6 (ver workflow.md).

La automatización nunca elimina la validación humana: el cierre de QA es siempre del usuario — un flujo de calidad totalmente desatendido no existe en Argui. Lo que el triage garantiza es que el humano reciba una lista corta y de juicio, no un volcado mecánico.

QA y archive

  • En QA: la generación del artifact, el tracking de la fase y el registro de respuestas corren en haiku. Si se reporta un bug, la corrección re-entra al ciclo de apply con el modelo del implementador correspondiente.
  • En archive: la revisión de archivado corre en sonnet (más arquitecto en opus si el gate lo marcó); la actualización de progreso en todos los archivos corre en haiku.

Medición y ajuste

Después de los primeros 3 a 5 items del backlog, revisar el consumo real por fase y por agente. Los gastos suelen concentrarse en lugares no obvios — verify y archive con varios subagentes por item suelen pesar más que apply. Ajustar la asignación de modelos en el front matter de los agentes outliers, sin tocar la metodología general.

Esta revisión no es de una sola vez: de ahí en adelante se repite como auditoría periódica de consumo de tokens (cada sprint o cada 5 items archivados), porque con el avance se acumulan artefactos que degradan la eficiencia — CLAUDE.md inflado, agentes con modelo mal asignado, skills/MCPs con overhead, contexto sin podar. Ver operations.md.