Instalación y configuración inicial

En el capítulo anterior entendimos la filosofía de Impeccable: un framework de design skill creado por Paul Bakaus que convierte a tu agente de IA de coding en un compañero con criterio de diseño. Vimos el por qué. Ahora toca el cómo: poner Impeccable a funcionar dentro de tu proyecto, conectarlo con tu herramienta de IA favorita y dejar la skill lista para invocarla.

La buena noticia es que la instalación está pensada para ser casi automática. Impeccable detecta qué herramientas de IA ya usas en el proyecto (mediante sus carpetas de configuración, llamadas harness folders) e instala los hooks nativos de cada proveedor por ti. En este capítulo recorreremos las tres vías de instalación —CLI, submódulo de git y copia manual—, la lista completa de proveedores compatibles, la estructura de archivos que se crea y, finalmente, cómo verificar que todo quedó en su sitio.

Antes de empezar: requisitos

Impeccable se distribuye en npm bajo el nombre impeccable, es de código abierto con licencia Apache 2.0 y se ejecuta a través de npx, así que no necesitas instalarlo de forma global. Solo requieres:

• Node.js con npx disponible (viene con npm). En este proyecto trabajamos con Bun, pero el instalador de Impeccable se invoca igualmente con npx.
• Un proyecto con al menos una herramienta de IA de coding configurada (por ejemplo, una carpeta .claude/, .cursor/ o .codex/).

Todos los comandos de instalación se ejecutan desde la raíz del proyecto. Esto es importante: Impeccable necesita ver tus carpetas de configuración para detectarlas correctamente.

Opción 1: instalación con el CLI (recomendada)

Es la vía más sencilla y la que deberías usar en la mayoría de los casos. Desde la raíz del proyecto:

npx impeccable install

Al ejecutarlo, el instalador hace algo clave: escanea tu entorno en busca de carpetas de harness. Te muestra las carpetas que detectó —por ejemplo ~/.claude, ~/.codex o una .cursor local del proyecto— y te deja conservar ese conjunto detectado o personalizar la lista de proveedores. Esta detección automática es lo que evita que tengas que configurar a mano cada herramienta.

Una vez confirmas, Impeccable:

1. Copia la skill y sus comandos en la carpeta de cada proveedor seleccionado.
2. Instala los hooks nativos del proveedor (el detector automático que se ejecuta al editar archivos).
3. Crea los archivos de configuración compartida y local que veremos más adelante.

Mantener Impeccable al día

Cuando salga una nueva versión y quieras refrescar la skill y los hooks instalados, ejecuta:

npx impeccable update

Este comando vuelve a aplicar la versión más reciente sobre los proveedores que ya tenías configurados, sin que tengas que repetir todo el proceso de selección.

Opción 2: submódulo de git (ideal para equipos)

Si trabajas en equipo y quieres que todos compartan exactamente la misma versión de Impeccable, ancla el framework como submódulo de git. Así la versión queda fijada en el repositorio y cualquiera que clone el proyecto obtiene la misma base:

git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor

El primer comando añade el repositorio de Impeccable como submódulo en la carpeta .impeccable. El segundo, link, enlaza esa fuente con los proveedores que indiques en --providers (en el ejemplo, Claude Code y Cursor). En lugar de copiar archivos sueltos, vincula los proveedores contra la versión que vive en el submódulo.

Cuando actualices el submódulo a una versión más reciente, vuelves a ejecutar el mismo comando link para re-enlazar:

npx impeccable link --source=.impeccable --providers=claude,cursor

La ventaja frente al CLI de la Opción 1 es la reproducibilidad: la versión de Impeccable forma parte del historial de git, no de la máquina de cada desarrollador.

Opción 3 y 4: descarga o copia manual

Para escenarios específicos —por ejemplo, una herramienta que prefieras configurar a mano, o un entorno sin acceso a npx— puedes descargar Impeccable desde su sitio (impeccable.style) o copiar los archivos directamente desde el repositorio, usando las rutas específicas de cada herramienta (.claude/, .cursor/, .codex/, etc.).

Es la vía menos automática y, salvo que tengas una necesidad concreta, conviene preferir el CLI o el submódulo. La copia manual no te da la detección de harness ni la instalación de hooks “llave en mano”.

Proveedores y herramientas soportadas

Impeccable es agnóstico respecto a la herramienta de IA: instala la misma skill traducida al formato nativo de cada una. Estos son los proveedores compatibles:

Herramienta	Nombre de proveedor (para scripts)
Cursor	cursor
Claude Code	claude
GitHub Copilot	github
Gemini CLI	gemini
Codex CLI	codex
OpenCode	opencode
Pi	pi
Kiro	(carpeta propia)
Trae	trae / trae-cn
Rovo Dev	rovo-dev
Qoder	qoder

Los nombres de la columna derecha son los identificadores que pasas en --providers cuando usas link o cuando personalizas la instalación. Por ejemplo, para enlazar contra Claude Code, Cursor y Codex a la vez: --providers=claude,cursor,codex.

Estructura de archivos que crea Impeccable

Entender qué archivos genera el instalador te ayuda a saber qué versionar en git, qué ignorar y dónde tocar si necesitas ajustar el comportamiento. Hay dos grupos: la configuración propia de Impeccable y los hooks por proveedor.

Configuración compartida y local

.impeccable/config.json         # Configuración compartida (se versiona en git)
.impeccable/config.local.json   # Preferencias por desarrollador (gitignored)

• config.json contiene los ajustes que el equipo comparte: el ciclo de vida del hook, las reglas del detector que se quieren ignorar a nivel de proyecto y los globs de archivos a excluir del escaneo. Como representa una decisión de equipo, se versiona en git.
• config.local.json guarda las preferencias de cada máquina —incluido el consentimiento de instalación del hook— y por eso está pensado para quedar fuera de git (gitignored). Lo que un desarrollador active o silencie en su entorno no debe afectar a los demás.

Esta separación entre lo compartido y lo local es una decisión de diseño deliberada: las reglas del proyecto viajan con el repositorio, las preferencias personales no.

Hooks por proveedor

Cada herramienta de IA usa su propio formato de hooks, y Impeccable escribe el archivo correspondiente en la ubicación nativa de cada una:

.claude/settings.local.json      # Claude Code (gitignored, local de la máquina)
.codex/hooks.json                # Codex CLI (a nivel de proyecto)
.cursor/hooks.json               # Cursor (a nivel de proyecto)
.github/hooks/impeccable.json    # GitHub Copilot (compartido por el equipo)

Fíjate en una diferencia importante de comportamiento: el hook de Claude Code, Codex y GitHub Copilot se engancha en el evento post-tool-use —se ejecuta después de que el agente escribe o edita un archivo: si encuentra problemas emite un prompt de corrección, si hay temas pendientes vuelve a recordarlos, y si un archivo “de UI” queda limpio da un breve acuse (salvo que el modo silencioso esté activo). En cambio, Cursor usa preToolUse, que actúa antes de que la escritura aterrice: el detector evalúa la operación de Write/Edit/Shell propuesta y la bloquea solo cuando detecta problemas.

Contexto de diseño del proyecto

Además de la configuración y los hooks, durante la puesta a punto del proyecto Impeccable también genera los archivos de contexto de diseño:

PRODUCT.md   # Qué es el producto y para quién
DESIGN.md    # El sistema de diseño visual del proyecto

Estos dos archivos no los crea el instalador base, sino el comando de inicialización de la skill. Los estudiamos a fondo en el capítulo 3: El contexto de diseño, así que aquí basta con saber que existen y que son la “memoria de diseño” que Impeccable consulta.

El flujo de instalación, paso a paso

El siguiente diagrama resume qué ocurre desde que ejecutas el instalador hasta que la skill queda lista:

flowchart TD
    A["npx impeccable install"] --> B{"Detecta carpetas<br/>de harness"}
    B --> C[".claude/"]
    B --> D[".cursor/"]
    B --> E[".codex/"]
    B --> F["...otros proveedores"]
    C & D & E & F --> G["Confirmas o<br/>personalizas proveedores"]
    G --> H["Copia skill + comandos"]
    G --> I["Instala hooks nativos<br/>por proveedor"]
    G --> J["Crea config.json +<br/>config.local.json"]
    H & I & J --> K["Recargas la herramienta"]
    K --> L["Skill disponible:<br/>/impeccable &lt;comando&gt; &lt;target&gt;"]

La detección de harness es el corazón del proceso: en lugar de preguntarte qué herramientas usas, Impeccable las descubre por las carpetas que ya existen en tu entorno y te propone instalarse en todas ellas.

Verificar la instalación e invocar la skill

Tras instalar, recarga tu herramienta de IA (reinicia la sesión o vuelve a abrir el agente) para que cargue la skill recién copiada. A partir de ahí, todos los comandos de Impeccable se invocan con la forma:

/impeccable <comando> <target>

Por ejemplo, para auditar la calidad de diseño de una sección llamada blog:

/impeccable audit blog

O para pasar una revisión final de pulido a un componente concreto:

/impeccable polish src/components/Button.tsx

Si quieres atajos sueltos sin el prefijo, Impeccable ofrece fijar (pin) un comando para exponerlo de forma directa. Por ejemplo, /impeccable pin audit crea un comando /audit independiente que llama internamente al mismo flujo.

Comprobar el detector desde la línea de comandos

Una forma rápida de confirmar que el motor funciona —sin pasar por el agente— es ejecutar el detector directamente. El detector aplica 44 reglas deterministas (lo veremos en detalle en el capítulo 4) y se puede correr sobre carpetas, archivos sueltos o incluso URLs:

npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect https://example.com
npx impeccable detect --json .

La bandera --json devuelve los hallazgos en formato JSON, útil para integrarlo en otros scripts o en CI. Si el detector responde con un análisis de tus archivos, la instalación del motor es correcta.

Gestionar exclusiones

Desde el mismo CLI puedes administrar qué archivos quedan fuera del escaneo, sin tener que editar a mano el config.json:

npx impeccable ignores list
npx impeccable ignores add-file "src/legacy/**"

Esto es práctico para excluir código heredado que no quieres que el detector marque constantemente.

Comprobar y administrar los hooks

Una vez instalado, el comportamiento automático del hook se gestiona con el subcomando hooks de la skill, que enruta las acciones al administrador interno. Las acciones disponibles incluyen:

/impeccable hooks status        # Muestra configuración y estado actual
/impeccable hooks on            # Activa la ejecución automática del hook
/impeccable hooks off           # Desactiva la ejecución automática
/impeccable hooks ignore-rule   # Suprime una regla del detector
/impeccable hooks ignore-file   # Excluye archivos por glob
/impeccable hooks reset         # Limpia configuración y cachés del proyecto

Ejecutar /impeccable hooks status justo después de instalar es la forma más directa de verificar que el hook quedó registrado y conocer si está activo o silenciado. Profundizaremos en la configuración avanzada de hooks y el workflow de equipo en el capítulo 12.

Qué versionar en git y qué no

Para cerrar la configuración inicial, conviene tener claro el reparto entre lo compartido y lo personal:

Archivo	¿Se versiona en git?	Motivo
.impeccable/config.json	Sí	Reglas y ajustes del equipo
.impeccable/config.local.json	No (gitignored)	Preferencias y consentimiento por máquina
.claude/settings.local.json	No (gitignored)	Hook local de Claude Code
.cursor/hooks.json	Sí	Hook a nivel de proyecto
.codex/hooks.json	Sí	Hook a nivel de proyecto
.github/hooks/impeccable.json	Sí	Hook compartido por el equipo
PRODUCT.md / DESIGN.md	Sí	Contexto de diseño del proyecto

Si trabajas con la Opción 2 (submódulo), recuerda además que el propio .impeccable queda registrado como submódulo en .gitmodules, fijando la versión exacta para todo el equipo.

Resumen

• Impeccable se instala de tres formas: con el CLI (npx impeccable install, recomendado), como submódulo de git (git submodule add ... .impeccable + npx impeccable link) para equipos, o por copia manual.
• El instalador detecta automáticamente las carpetas de harness (.claude, .cursor, .codex, etc.) e instala los hooks nativos de cada proveedor; se refresca con npx impeccable update.
• Soporta Cursor, Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, OpenCode, Pi, Kiro, Trae, Rovo Dev y Qoder.
• Crea .impeccable/config.json (compartido) y .impeccable/config.local.json (gitignored), más los hooks por proveedor (.claude/settings.local.json, .cursor/hooks.json, .codex/hooks.json, .github/hooks/impeccable.json).
• Claude Code, Codex y Copilot usan hooks post-tool-use (corrigen tras editar); Cursor usa preToolUse (bloquea antes de escribir).
• La skill se invoca con /impeccable <comando> <target>; verifica con /impeccable hooks status y prueba el motor con npx impeccable detect src/.

Con Impeccable instalado y los hooks activos, el siguiente paso es darle a tu agente el contexto de diseño de tu proyecto: qué construyes, para quién y con qué sistema visual.

Siguiente: El contexto de diseño: init, PRODUCT.md y DESIGN.md