Impeccable lenguaje de diseño para agentes de IA: el repositorio pbakaus/impeccable se describe como «el lenguaje de diseño que mejora el diseño de tu harness de IA». En concreto, es un skill (una instrucción reutilizable para un agente de código) acompañado de 24 comandos, un detector de 61 reglas para localizar los defectos típicos del frontend generado por IA y un modo de iteración en el navegador. El repositorio cuenta con unas 84 600 estrellas a finales de octubre de 2026.
¿Por qué hablar de ello en un blog de operaciones? Porque un skill que instala hooks, descarga un binario y propone telemetría es un componente de tu cadena de entrega. Este artículo sigue el README y la documentación del proyecto: qué hace, cómo instalarlo, qué escribe en tu disco y cómo medir lo que detecta. Para otro skill de la serie, consulta el skill de auditoría de seguridad de Cloudflare.
Una precisión de honestidad: span.observer no ha instalado Impeccable. Los comandos proceden del README y la captura procede del sitio del proyecto.
Impeccable lenguaje de diseño para agentes de IA: qué dice el repositorio
- Autor y licencia: el README indica que el proyecto lo creó Paul Bakaus; licencia Apache 2.0 (archivo LICENSE).
- Cifras revisadas el 22 de octubre de 2026: unas 84 600 estrellas, unos 5 100 forks, 2 517 commits. La página del repositorio no muestra ninguna release.
- Contenido anunciado: 1 skill, 24 comandos (
craft,shape,critique,audit,polish,harden,animate,live…), 61 reglas deterministas de detección y comandos LLM de crítica. - Origen: el README dice que el proyecto partió del skill
frontend-designde Anthropic; no se presenta como un producto de esa empresa. - Herramientas admitidas: Cursor, Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, Grok Build, OpenCode y una decena más, según la lista del README.
El principio del README: todos los modelos han aprendido con las mismas plantillas de SaaS, de ahí los mismos defectos (Inter en todas partes, degradados violeta-azul, tarjetas dentro de tarjetas). El skill da un vocabulario común al agente, y el detector verifica el resultado sin modelo ni clave de API.
Recorrido: qué busca el detector
El sitio del proyecto ilustra cada defecto con una página de ejemplo. Esta es la de los degradados violeta: una página deliberadamente típica, con una marca ficticia, que el proyecto clasifica entre los patrones que evitar.

La documentación del detector muestra un hallazgo real sobre un pequeño archivo CSS (regla gradient-text, línea 3) y los comandos de escaneo.

Instalación paso a paso
Paso 1 — El instalador recomendado
Desde la raíz de tu proyecto:
npx impeccable install
/impeccable init
El instalador detecta tus herramientas (por ejemplo ~/.claude o una carpeta .cursor del proyecto), pregunta si la instalación es para el proyecto o para el equipo y después coloca el skill. Las opciones --providers=claude,cursor y --scope=project|global evitan las preguntas en un script. Para actualizar: npx impeccable update. En el agente, /impeccable init escribe un archivo PRODUCT.md que describe público, uso y restricciones.
Paso 2 — Alternativas del README
- Submódulo de Git:
git submodule add https://github.com/pbakaus/impeccable .impeccable, y despuésnpx impeccable link --source=.impeccable --providers=claude,cursor. - Claude Code:
/plugin marketplace add pbakaus/impeccable, y después instalación desde/plugin. - Copia manual desde
dist/, o ZIP del sitio oficial.
Paso 3 — El detector solo, sin agente
npx impeccable detect src/
npx impeccable detect http://localhost:3000
npx impeccable detect --json src/
npx impeccable detect --github src/
El README precisa los códigos de salida: 0 sin hallazgos, 2 con hallazgos, 1 si no se pudo analizar un objetivo. La opción --github produce anotaciones para GitHub Actions (como máximo 10 de cada tipo por paso y 50 por job, según el README). Es la parte más útil para un equipo SRE: un control en integración continua, sin modelo.
Qué escribe y qué envía la herramienta
- Hooks: en Claude Code, Copilot, Codex, Cursor y Grok Build, el instalador añade un manifiesto de hooks que lanza el detector después de cada edición de un archivo de interfaz. El README advierte de que, en Claude Code, estos hooks se ejecutan con independencia de la aprobación de herramientas: el primer evento puede descargar y almacenar en caché el motor en
~/.impeccable/bin/. Revisa los hooks antes de una ejecución desatendida. - Carpeta
.impeccable/: capturas, estado del modo live y cachés. El README da un bloque.gitignoreque copiar y lista los archivos que versionar (config.json,design.json,surfaces/*.md). - Telemetría: el skill llama a la API del sitio impeccable.style para sacar una «mano» de mundos visuales; salvo oposición, se envía un registro anónimo de la elección. El README dice que no salen ni el nombre del proyecto, ni los archivos, ni el código, ni
PRODUCT.md. Para cortarla:npx impeccable telemetry off, oDO_NOT_TRACK=1, oIMPECCABLE_NO_TELEMETRY=1. - Modo live: edita un repositorio local mediante un servidor de desarrollo; aplicarlo a un sitio de producción no está admitido. La aplicación de cambios de texto ejecuta el script opcional
impeccable:manual-edit-validatede tupackage.jsonen un shell: revísalo en un repositorio desconocido.
Observar Impeccable
Impeccable no es un servicio: no hay trazas ni métricas que exportar, y el README no describe ninguna. Lo que se puede medir:
- Hallazgos del detector: la salida
--jsono las anotaciones--githubdan un número de hallazgos por regla. Síguelo a lo largo de las pull requests, como indicador de calidad, sin convertirlo en un objetivo absoluto: el README recuerda que un escaneo limpio no es una prueba de calidad visual ni de accesibilidad. - Ejecución de los hooks: el parámetro
hook.auditLogde.impeccable/config.json(o la variableIMPECCABLE_HOOK_LOG) escribe una línea NDJSON por llamada de hook. Conecta ese archivo a tu colector de logs. - Coste en tokens: los comandos de crítica pasan por el modelo de tu agente. Para atribuirlo, sigue la monitorización de un agente de código.
Límites y puntos abiertos
- El proyecto cambia rápido (24 comandos, una quincena de herramientas admitidas): revisa la documentación antes de cada actualización.
- El detector aplica reglas de gusto: «sin Inter», «sin degradado violeta» siguen siendo decisiones de diseño por discutir, no errores absolutos. Las excepciones se declaran en la configuración.
- Una parte del flujo (el sorteo de mundos visuales) pasa por el servidor del proyecto; sin red, el README no dice qué ocurre. Pruébalo antes de depender de ese modo.
- Compatibilidad: la página del repositorio no mostraba ninguna release en la fecha de revisión.
Buenas prácticas
- Prueba primero el detector solo en CI, y solo después el skill en el agente.
- Desactiva la telemetría en los equipos sujetos a una política de datos, y versiona la decisión en
.impeccable/config.json. - Somete los skills de tus agentes a revisión como si fueran código; consulta también el repertorio oficial de plugins de Claude Code.
- No declares una excepción global para silenciar una regla: prefiere la renuncia acotada en el archivo.
Preguntas frecuentes
¿Funciona Impeccable sin clave de API?
El detector sí: el README dice que la CLI y la extensión de navegador ejecutan las reglas deterministas sin modelo ni clave. Los comandos de diseño pasan por el agente que ya usas.
¿Hace falta Node.js?
Solo para npx. El skill incluye un lanzador que ejecuta un binario autónomo, descargado una vez en ~/.impeccable/bin/ si no se entrega con él.
¿Está relacionado con Anthropic o con Cursor?
El README no lo presenta como un producto ni de Anthropic ni de Cursor: dice haber partido del skill frontend-design de Anthropic y admite numerosas herramientas, entre ellas esas dos.
Conclusión
Impeccable ofrece un lenguaje común para pedir a un agente algo mejor que un frontend «genérico», y un detector que se integra en la CI. Su buen uso se resume en tres ajustes: detector primero, telemetría decidida, hooks revisados. Fuentes: repositorio pbakaus/impeccable y documentación del detector.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y las opciones en su documentación oficial.