← Volver al listado de tecnologías ← Índice de Impeccable

Hooks, configuración avanzada y workflow de equipo

Por: Artiko
impeccablehooksconfiguraciónpinequipo

Hooks, configuración avanzada y workflow de equipo

En el capítulo anterior cerramos el lazo manual: con /impeccable live el agente abre tu interfaz en un navegador real, la observa y la corrige hasta que el resultado coincide con tu intención. Ese flujo es poderoso, pero todavía depende de que tú, o el agente, invoquen un comando de forma explícita. En este último capítulo damos el paso final hacia la automatización: hacemos que el detector se ejecute solo, en cada edición de un archivo de interfaz, sin que nadie tenga que pedirlo.

Eso es exactamente lo que hace el sistema de hooks de Impeccable. Y como un hook que solo te sirve a ti es la mitad de la historia, también veremos cómo configurarlo con precisión, cómo crear atajos cómodos con pin, y cómo adoptar Impeccable en un equipo completo: versionando el contexto de diseño, compartiendo reglas y enchufando el detector en tu pipeline de integración continua. Al terminar tendrás una visión completa del recorrido “de 0 a hero”.

Qué es un hook y por qué importa

Un hook es un punto de enganche que el agente de coding ejecuta automáticamente cuando ocurre un evento, típicamente justo antes o justo después de que una herramienta escriba en un archivo. La idea de Impeccable es sencilla pero potente: en lugar de confiar en que recuerdes correr el detector, lo conectamos al ciclo de edición para que cada cambio en un archivo de interfaz dispare un análisis determinista.

El instalador despliega un hook nativo que cumple dos funciones:

  1. Corre el detector sobre las ediciones directas a archivos relevantes para el diseño.
  2. Devuelve los hallazgos al flujo del agente, de modo que el propio agente reaccione a ellos sin intervención manual.

Los archivos que el hook considera “relevantes para el diseño” incluyen las extensiones más comunes del frontend: .tsx, .jsx, .html, .vue, .svelte, .astro, .css, .scss, .sass, .less, además de .ts y .js. Si tu edición no toca ninguno de esos tipos de archivo, el hook se mantiene en silencio y no interrumpe nada.

El hook se adapta a cada proveedor

Aquí está la decisión de diseño más interesante de Impeccable: el hook no se comporta igual en todos los agentes. Como el bundle de la skill se instala mediante manifiestos específicos por proveedor, cada plataforma recibe la integración que mejor encaja con sus capacidades nativas.

El instalador deja el manifiesto en una ubicación distinta según el proveedor:

ProveedorManifiesto del hookCompartido en el repo
Claude Code.claude/settings.local.jsonNo (gitignored, local a la máquina)
Codex.codex/hooks.jsonSegún configuración
Cursor.cursor/hooks.jsonSegún configuración
GitHub Copilot.github/hooks/impeccable.jsonSí (compartido por el equipo, versionado)

La diferencia de comportamiento se reduce a un eje: bloquear antes frente a surfacear después.

Cursor: bloquea la escritura problemática antes del commit

Cursor utiliza un hook de tipo preToolUse. Esto significa que el detector se ejecuta sobre la escritura propuesta, antes de que llegue a tocar el disco. Si el detector encuentra un problema real, Cursor puede bloquear esa escritura para que no aterrice. Si la escritura está limpia, el hook permanece en silencio y permite la operación sin ruido.

Este es el modelo más estricto y proactivo: el código problemático nunca llega siquiera a guardarse. Es ideal cuando quieres una garantía dura de que cierto tipo de AI slop (bordes laterales en pestañas, gradientes morados, easing con rebote, glows oscuros) no entra al repositorio.

Claude Code, Codex y GitHub Copilot: surfacean los hallazgos después de la edición

Estos tres proveedores usan un hook de tipo postToolUse. El flujo es distinto: la edición sí ocurre, y justo después el hook inyecta un breve recordatorio del sistema en el contexto del agente. Si el detector encontró un problema, el agente recibe un prompt de corrección; si hay cuestiones pendientes de un análisis previo, recibe un “re-nudge”, un empujón para retomarlas.

La filosofía aquí es de colaboración, no de bloqueo: se confía en que el agente, ya consciente del hallazgo gracias al recordatorio, corrija el archivo en el siguiente turno. Es menos rígido que el modelo de Cursor, pero se integra con naturalidad en el ciclo conversacional de estos agentes.

Codex: requiere aprobación manual del hook la primera vez

Codex añade una particularidad de seguridad. Como en Codex los hooks son una capacidad sensible, el usuario debe aprobar el hook mediante /hooks la primera vez que se vaya a ejecutar. Hasta que des esa aprobación explícita, el hook permanece inactivo. Es un pequeño paso adicional de consentimiento: Codex no ejecuta automáticamente código de hooks sin que tú lo autorices.

Recuerda este detalle si instalas Impeccable en Codex y notas que el detector no se dispara solo: lo más probable es que aún no hayas corrido /hooks para aprobarlo.

flowchart TD
    Edit[El agente edita un archivo de UI] --> Type{¿Tipo de hook<br/>del proveedor?}
    Type -->|Cursor: preToolUse| Pre[Detector evalúa la escritura propuesta]
    Pre --> Clean{¿Limpia?}
    Clean -->|Sí| Allow[Permite la escritura en silencio]
    Clean -->|No| Block[Bloquea la escritura antes del commit]
    Type -->|Claude Code / Codex / Copilot:<br/>postToolUse| Post[La edición aterriza]
    Post --> Surface[Inyecta recordatorio en el contexto del agente]
    Surface --> Fix[El agente corrige en el siguiente turno]

Configuración avanzada: .impeccable/config.json

El comportamiento de Impeccable se ajusta desde un único archivo de configuración versionado: .impeccable/config.json. Aquí defines tanto las reglas del detector como el control de los hooks. Una configuración típica se ve así:

{
  "detector": {
    "ignoreRules": ["purple-gradient", "bounce-easing"],
    "ignoreFiles": ["src/legacy/**", "**/*.stories.tsx"],
    "ignoreValues": ["#6b46c1"]
  },
  "designSystem": {
    "enabled": true
  },
  "hook": {
    "enabled": true,
    "auditLog": true
  }
}

Veamos cada bloque y por qué existe.

El bloque detector

Estas tres claves te permiten silenciar falsos positivos sin desactivar el detector entero, algo fundamental en proyectos reales donde no todo el código está bajo tu control:

El bloque designSystem

Con designSystem.enabled activas o desactivas la conciencia del sistema de diseño. Cuando está en true, los comandos de Impeccable contrastan tus cambios con el DESIGN.md del proyecto en lugar de aplicar solo reglas genéricas. Es lo que hace que polish y compañía respeten tus tokens y no unos por defecto.

El bloque hook

Además de las claves mostradas, el hook admite afinaciones como hook.quiet para reducir el ruido de los recordatorios cuando prefieres una integración más discreta.

Preferencias por desarrollador: config.local.json

No todo lo que quieres configurar debe imponerse a tus compañeros. Para eso existe .impeccable/config.local.json, un archivo gitignored pensado para preferencias específicas de cada máquina o de cada desarrollador. Lo que pongas ahí no viaja al repositorio y, por tanto, no afecta al resto del equipo.

La regla mental es simple:

Atajos cómodos: /impeccable pin

Escribir /impeccable audit blog cada vez es preciso, pero verboso. Para los comandos que usas a diario, Impeccable ofrece pin, que genera un atajo standalone:

/impeccable pin audit

Tras ejecutarlo, dispones de un nuevo comando directo /audit que equivale a /impeccable audit. Puedes anclar cualquier comando del catálogo que cubrimos en los capítulos previos, por ejemplo:

/impeccable pin critique
/impeccable pin polish
/impeccable pin live

Esto te deja con /critique, /polish y /live listos para usar. El objetivo es puramente ergonómico: reducir la fricción de los comandos que forman parte de tu rutina, para que la calidad de diseño sea el camino de menor resistencia.

Workflow de equipo

Hasta aquí hemos hablado de tu máquina. Pero el valor real de Impeccable se multiplica cuando todo el equipo comparte el mismo criterio de diseño. Veamos cómo lograrlo.

Instalación como submódulo de Git

Para un setup compartido y reproducible, Impeccable puede añadirse como submódulo de Git:

git submodule add https://github.com/pbakaus/impeccable .impeccable

Así todo el equipo apunta a la misma versión del bundle, y las actualizaciones se gestionan de forma explícita y deliberada, igual que cualquier otra dependencia versionada.

Versionar el contexto de diseño: PRODUCT.md y DESIGN.md

La skill genera y mantiene dos documentos clave que ya conociste en el capítulo del contexto de diseño: PRODUCT.md (qué construyes y para quién) y DESIGN.md (cómo se ve y se comporta tu producto). Estos archivos deben commitearse al repositorio.

Cuando viven en el control de versiones, ocurren tres cosas valiosas:

  1. Todos los agentes de todos los desarrolladores trabajan con la misma fuente de verdad de diseño.
  2. Los cambios de criterio (un nuevo color de marca, una decisión tipográfica) pasan por revisión en un PR, igual que el código.
  3. El historial te cuenta cómo evolucionó la identidad visual del producto a lo largo del tiempo.

El audit log como métrica de calidad

Con hook.auditLog activado, cada equipo acumula un registro de lo que el detector va encontrando. Ese log deja de ser un detalle técnico y se convierte en un termómetro de la deuda de diseño: ¿qué reglas se disparan más?, ¿en qué partes del código?, ¿está mejorando la tendencia tras adoptar Impeccable? Revisarlo periódicamente convierte la calidad de diseño en algo medible, no en una opinión.

Integración en CI

El último eslabón es la integración continua. El detector funciona como una CLI pura, sin necesidad de un agente de IA, lo que lo hace perfecto para un pipeline. En tu job de CI puedes correr:

npx impeccable detect src/

O, si quieres procesar el resultado de forma programática (por ejemplo para anotar un PR), pídelo en formato JSON:

npx impeccable detect --json .

Conectar esto a tu CI te da una red de seguridad de equipo: aunque alguien edite sin un agente con el hook instalado, o desde un entorno distinto, el detector vuelve a pasar antes de fusionar. Es el mismo análisis determinista de las 44 reglas, ahora como guardián del repositorio compartido.

flowchart LR
    subgraph Dev[Cada desarrollador]
        E[Edita UI] --> H[Hook corre el detector]
        H --> C[Corrige según hallazgos]
    end
    C --> PR[Pull Request]
    subgraph Team[Activos compartidos]
        P[PRODUCT.md / DESIGN.md]
        A[Audit log]
    end
    PR --> CI[CI: npx impeccable detect]
    CI -->|Limpio| Merge[Merge a main]
    CI -->|Hallazgos| Dev
    P -.contexto.-> H
    H -.registra.-> A
    Merge --> P

Cierre del curso: el recorrido completo

Has recorrido Impeccable de principio a fin. Vale la pena recapitular el flujo como un todo, porque es ahí donde se ve la coherencia del sistema:

  1. Init: con npx impeccable install y /impeccable init estableces el contexto de diseño en PRODUCT.md y DESIGN.md.
  2. Comandos: planificas con craft, shape, document y extract; revisas con critique, audit y polish; refinas con bolder, quieter, distill y harden; estructuras con layout, typeset y colorize; añades vida con animate, delight, overdrive y onboard; y adaptas el contenido con clarify, adapt y optimize.
  3. Detector: las 44 reglas deterministas atrapan el AI slop y los problemas de calidad sin depender de un modelo.
  4. Hooks: el detector se ejecuta solo en cada edición, bloqueando en Cursor o surfaceando en los demás proveedores.
  5. Live: con /impeccable live el agente itera contra el navegador real hasta que la interfaz coincide con tu intención.

Todo esto descansa sobre la misma filosofía con la que empezamos: el buen diseño no debería ser un golpe de suerte, sino el resultado por defecto de un proceso deliberado y repetible.

Próximos pasos

Resumen

El sistema de hooks de Impeccable convierte el detector en una garantía continua: el instalador despliega un hook nativo que corre el detector en cada edición de archivos de interfaz y devuelve los hallazgos al agente. Su comportamiento se adapta al proveedor: Cursor usa preToolUse para bloquear escrituras problemáticas antes de que aterricen, mientras que Claude Code, Codex y GitHub Copilot usan postToolUse para surfacear hallazgos tras la edición; en Codex debes aprobar el hook con /hooks la primera vez. Toda la afinación vive en .impeccable/config.json (detector.ignoreRules/ignoreFiles/ignoreValues, designSystem.enabled, hook.enabled, hook.auditLog), con preferencias personales en el config.local.json gitignored. Con pin creas atajos como /audit, y para el trabajo en equipo versionas el contexto de diseño, registras el audit log y ejecutas npx impeccable detect en CI. Así se cierra el lazo: del init al live, pasando por comandos, detector y hooks, la calidad de diseño deja de ser un acto de voluntad para volverse el comportamiento por defecto.

Siguiente: Volver al índice del curso

← Volver al listado de tecnologías ← Índice de Impeccable