Argui

Estándares base

Los estándares base se crean en F4.6 del workflow — después del backlog y antes de los agentes especializados. El orden importa: si los agentes se crean primero, cada uno establece patrones implícitos que nadie decidió conscientemente.

Principio

Los estándares de Argui aseguran calidad, eficiencia y consistencia en la elaboración del PMV (Producto Mínimo Viable). No son burocracia: cada estándar existe para prevenir un modo de falla específico. Si un estándar no previene nada en tu proyecto, elimínalo.

Principio transversal: lo verificable se verifica como código

Un control de calidad o de riesgo que se puede comprobar automáticamente se codifica como gate ejecutable —en verify/CI (Continuous Integration)— no como documento ni como revisión manual que algún día se olvida. Es el hilo que ya cruza estos estándares:

  • accesibilidad → axe/lint en CI (§3, §4), no inspección a ojo;
  • descubribilidad → metadatos y datos estructurados verificados en el build (§8);
  • verificación objetiva → suite de integración, no QA manual (§4);
  • salud del despliegue → health gate + rollback automático (§7);
  • gobernanza de archivos compartidos (en equipos) → guarda de gobernanza en CI + CODEOWNERS, no confiar en que el revisor note el cambio en el diff (ver teams.md).

El §10 lo aplica al caso más exigente: cuando el producto lleva IA dentro, el control de riesgo (umbral de eval, guardrail) es código que corre, no una promesa.

Es el espíritu de policy-as-code (término de seguridad/infra: políticas versionables y ejecutables en vez de documentos). No exige un motor de políticas dedicado ni nada pesado: en un PMV, “como código” puede ser un test, un linter o un check en el pipeline. Si algo verificable sigue dependiendo de que alguien se acuerde de revisarlo, todavía no es un estándar.

Estándares mínimos

1. Base del proyecto

  • Naming conventions: variables, funciones, archivos, ramas
  • Estructura de carpetas: dónde vive cada cosa y por qué
  • Formato de commits: convención elegida (ej. Conventional Commits)
  • Patrones de manejo de errores: cómo se capturan, registran y comunican los errores

2. Backend

  • Patrones de API (Application Programming Interface) (REST/GraphQL/RPC, versionado, formatos de respuesta)
  • Manejo de autenticación y autorización
  • Acceso a datos y migraciones
  • Logging y observabilidad mínima para un PMV

3. Frontend

  • Patrones de componentes
  • Manejo de estado
  • Uso del design system y sus tokens — el design system crece con el prototipo (semilla en fase 3 → se consolida al aprobarlo, extraído del prototipo) y es la referencia de apariencia; el frontend no inventa apariencia (ver prototype.md)
  • Accesibilidad (mínimo del PMV): HTML semántico primero; ARIA (Accessible Rich Internet Applications) solo donde la semántica nativa no alcanza. aria-label para controles sin texto visible (botones de ícono), nunca como parche de un elemento no semántico. Operable por teclado, foco visible, toda entrada/control con etiqueta, alt en imágenes informativas, contraste suficiente, landmarks/encabezados correctos. La a11y se hornea en el design system (componentes y tokens accesibles por defecto), no se resuelve por pantalla

4. Tests

Es un PMV: los tests deben encontrar un balance entre cobertura y agilidad.

  • Pirámide de testing: muchos unit, menos integración, pocos E2E (end-to-end)/UI (interfaz de usuario). Preferir siempre la capa más baja que dé confianza — lo objetivo del triage (API/BD (base de datos)/lógica) vive en integración, no se sube a E2E
  • E2E delgado y resiliente: solo journeys críticos; selectores estables (roles / data-testid, nunca CSS o texto frágil). Los roles ARIA del estándar de accesibilidad (§3) doblan como anclas estables → menos flaky y menos rompimiento cuando cambia la UI
  • Indispensable: cobertura completa de las funcionalidades críticas
  • Frontend: usar Playwright para los tests, aplicando el gate de costo de efficiency.md — automatizar lo que se repite y es crítico, no todo
  • Definir explícitamente qué es “crítico” en el proyecto — pagos, autenticación, el flujo principal de valor
  • Lo no crítico puede esperar: no bloquear el avance del PMV por cobertura exhaustiva de casos secundarios
  • Verificación objetiva en la suite, no en QA (Quality Assurance) manual: respuestas de API, estado/invariantes de BD y lógica de negocio se cubren con tests de integración (corren en verify/CI), no como pruebas manuales (ver triage de QA en efficiency.md)
  • Aislamiento de datos: los tests automáticos corren contra una base de datos separada y dedicada, nunca la de desarrollo o QA manual — se puede crear/limpiar libremente, permite correr en paralelo y no contamina el seed de QA
  • Accesibilidad automatizada: linter de a11y (eslint-plugin-jsx-a11y o equivalente) + axe-core en los tests de frontend (con el gate de costo), corriendo en el CI. Convierte la accesibilidad en gate, no en revisión manual olvidable

5. Documentación

  • Qué se documenta y qué no (en un PMV, documentar de más es tan costoso como documentar de menos)
  • Dónde vive la documentación
  • El CLAUDE.md como documento vivo central

6. Workflow

  • Cómo fluye un cambio desde el backlog hasta producción
  • El ciclo OpenSpec personalizado (apply → verify → qa → archive)
  • Quién aprueba qué y cuándo

7. Despliegue continuo

  • Pipeline de CI/CD (Continuous Integration / Continuous Delivery) — se configura temprano: es uno de los primeros items del backlog (item CHQ-002, junto con el design system), no algo que se agrega al final
  • Ambientes (mínimo: desarrollo y producción)
  • Criterios para desplegar
  • Versión trazable en cada despliegue. Todo build desplegable lleva dos identidades:
    • SemVer (Semantic Versioning) (MAJOR.MINOR.PATCH) — legible, comunica el tipo de cambio. Es derivable de los Conventional Commits (ver operations.md): fix→PATCH, feat→MINOR, BREAKING CHANGE→MAJOR. Recomendado, no obligatorio para un PMV.
    • git SHA (el hash del commit) — el punto exacto e inequívoco del código del que salió el build (reproducible, sin ambigüedad).
    • La app expone su versión y SHA en runtime (p. ej. endpoint /version o /health, o un manifiesto de build): siempre se puede responder qué hay exactamente en producción ahora.
  • Artefactos inmutables y versionados. Cada versión se construye una vez y se guarda etiquetada con su SemVer+SHA; desplegar es promover un artefacto existente, no reconstruir. Se retiene al menos el último build estable (known-good).
  • Rollback automático. El despliegue pasa por un gate de salud (health check / smoke test). Si falla, el pipeline revierte solo al último artefacto known-good —sin intervención manual—. El rollback es re-promover el artefacto anterior; por eso los artefactos deben ser inmutables y estar retenidos.

8. Descubribilidad (SEO/GEO) — cuando aplica

Estándar condicional. No todo producto necesita ser encontrado fuera de su propio acceso. Una app interna, un SaaS detrás de login o una API privada no llevan nada de esto; una landing, un producto público, una tienda o documentación que aspira a ser citada, sí. La aplicabilidad se decide en el PRD (Product Requirements Document) de negocio (fase 2): si la respuesta es “no”, este estándar se elimina (principio: si no previene nada, fuera).

Cuando aplica, son tres capas independientes — se activa solo la que el producto necesita:

  • (a) SEO (Search Engine Optimization) base (humano, vía buscador). Contenido renderizado en servidor (no solo JS de cliente), metadatos (title, description, Open Graph), sitemap.xml, URLs limpias y datos estructurados Schema.org / JSON-LD (Organization, Product, FAQPage, SoftwareApplication según el caso). Es lo que sigue alimentando tanto a buscadores como a los modelos.
  • (b) GEO (Generative Engine Optimization)/AEO (Answer Engine Optimization) (que la IA te descubra y te cite). No hay archivo mágico: mueven la aguja el contenido factual y citable + permitir o bloquear conscientemente los crawlers de IA en robots.txt (GPTBot, ClaudeBot, OAI-SearchBot, PerplexityBot, Google-Extended). Permitir/bloquear es una decisión de negocio explícita, no un default accidental.
  • (c) llms.txt (B2A (business-to-agent) — para agentes, no para ranking). Archivo en la raíz que indexa el sitio para agentes e IDEs (Claude Code, Cursor, Copilot) y MCP (Model Context Protocol) servers. Encuádralo con honestidad: no es un factor de descubrimiento ni de ranking —los crawlers de búsqueda casi no lo leen y Google declaró que no lo soporta—; su valor es B2A: que un agente ya dentro de tu producto/docs navegue mejor. Barato de generar; inclúyelo cuando tu público usa esas herramientas, no como póliza de SEO.

Las capas activas se vuelven verificables (metadatos/structured data en build, robots.txt/llms.txt presentes), no revisión manual olvidable.

9. Monitoreo en producción

El despliegue (§7) verifica la salud en el momento de publicar (health-check + rollback). El monitoreo cubre lo continuo y posterior: saber si el producto sigue sano para los usuarios y detectar cuándo se rompe. Mínimo y proporcional a un PMV — no observabilidad de empresa.

Mínimo (todo producto desplegado):

  • Disponibilidad. Un chequeo externo periódico al endpoint de salud, con alerta cuando cae. El /health (§7) responde a HEAD además de GET: los monitores de uptime usan HEAD por barato (sin cuerpo). Ej.: UptimeRobot (gratis, alerta por correo).
  • Errores en runtime. Las excepciones no controladas se capturan y reportan a un error tracker, etiquetadas con la versión/SHA del build (§7) para ubicar en qué release aparecieron. Es la extensión en producción de los patrones de manejo de errores (§1): lo que se captura y registra localmente, en producción además se agrega y alerta. Ej.: Sentry (free: 5.000 errores/mes). → un error recurrente es un candidato de backlog (Fase 6, captura en origen).

Recomendado:

  • Uso / tráfico. Analítica liviana para ver si el producto se usa y por dónde. Por defecto, analítica respetuosa de la privacidad: sin cookies de seguimiento ni envío de datos personales a terceros — coherente con un producto sobre el que se puede responder qué se recoge y por qué. Ej.: GoatCounter (open source; gratis no-comercial o self-host — self-host = soberanía del dato).

Logs. No requiere herramienta dedicada en un PMV. Con visor de logs gestionado (Vercel/Render/Fly/Railway…), se usa ese. En VPS (Virtual Private Server)/bare-metal, los logs se consultan en el propio VPS (journald / docker logs / archivos de log): montar un agregador que consume tanta RAM como la app no compensa en un PMV, y los errores que importan ya los captura el error tracker (arriba).

La instrumentación es un entregable, no un documento. El endpoint de salud (con HEAD), el SDK (Software Development Kit) del error tracker (con etiqueta de release/SHA) y el snippet de analítica se cablean temprano, junto al CI/CD (item CHQ-002). El monitor externo de uptime es configuración del servicio, fuera del repo.

Las señales cierran el lazo, no terminan en un tablero. Todo lo que esta sección captura —errores (con su release/SHA), caídas de disponibilidad, patrones de uso— más las regresiones de eval (§10) y el feedback directo de usuarios (un formulario de contacto, un canal de soporte: es una señal, no un sistema de feedback que haya que montar) son entradas del intake de Fase 6: la señal que indique trabajo se vuelve candidato de backlog, capturado en el origen. Ese es el lazo runtime → planificación (ver workflow.md Fase 6).

10. Productos con IA — evals y guardrails (cuando aplica)

Estándar condicional, y ojo con la palabra “IA”. Toda esta metodología trata de construir software con IA (la IA como herramienta del taller). Este estándar es lo contrario: aplica solo cuando el producto que entregas lleva IA dentro —una funcionalidad apoyada en un modelo de lenguaje (LLM, Large Language Model) u otro modelo—. Si tu producto no incorpora IA, esta sección no existe (principio: si no previene nada, fuera). La aplicabilidad se decide en el PRD de negocio (fase 2).

Por qué es su propio estándar: un componente con IA no es determinista —la misma entrada puede dar salidas distintas—, así que el test tradicional (entrada → salida exacta) no lo cubre. El riesgo deja de ser algo que se revisa al final y entra como ciudadano de primera clase del ciclo.

Cuando aplica, en orden de lo más barato a lo más elaborado:

  • (a) El check más barato no necesita framework. Lo que sí es determinista se prueba como test normal en la capa baja de la pirámide (§4): que la salida cumpla el schema/formato esperado, que se haya llamado la herramienta correcta, que no se filtren datos personales/sensibles. Empieza por aquí.
  • (b) Evals — para lo subjetivo. Lo que no se puede comprobar con una igualdad (¿la respuesta es útil, fiel a la fuente, sin alucinar?) se mide con evals: rúbrica, un modelo como juez (LLM-as-judge) o comparación por pares —no lectura a ojo—. Reglas que sostienen su valor:
    • se mide contra un umbral aceptable, no verde/rojo (la salida varía entre corridas → promediar / fijar criterios);
    • corre en CI ante cada cambio; un eval que solo se corre a mano no protege nada;
    • el set de evals crece con el tiempo: cada fallo de producción que importe se vuelve un caso nuevo (la §9 alimenta este set, igual que alimenta el backlog de Fase 6).
    • Ejemplo: promptfoo (MIT, corre 100% local — los prompts no salen de tu infraestructura; config declarativa + CI) o DeepEval (estilo pytest) como alternativa.
  • (c) Guardrails — proporcional a un PMV. Barreras que acotan qué entra y qué sale del modelo: validación de entrada/salida, manejo de rechazo (qué hace el producto cuando el modelo no debe responder), límites de costo/rate, y manejo de datos sensibles —qué se manda a un modelo de terceros y qué no— (coherente con poder responder qué dato sale y por qué). El mínimo de un PMV es validar la salida; no hace falta más. Ejemplo: Guardrails AI (valida estructura de salida, re-prompt). Para productos conversacionales (control de tema y de flujo de la charla), NeMo Guardrails.

Las capas activas se vuelven gates verificables (evals en CI, guardrails en el código), no revisión manual olvidable — es el principio transversal aplicado al riesgo de IA.

Estándares especializados

Los estándares base son el piso común. Cada agente extiende este piso con criterios específicos de su dominio, definidos dentro del archivo del propio agente. El agente de backend define sus patrones de API; el de frontend, sus patrones de componentes.

Esta división evita dos problemas: estándares base inflados que nadie lee, y agentes sin criterios propios que improvisan.