Cómo integrar y usar impeccable

10 jun 2026

Cómo integrar y usar impeccable

En realidad no es nada complicado, solo se trata de integrar una herramienta de diseño en el proyecto HagiCode, que podría considerarse una solución completa aproximada—incluye la estructura del repositorio, el flujo de trabajo multilingüe y el mantenimiento del contenido, todo se ha ido descubriendo gradualmente en la práctica.

Antecedentes

Hablando de la calidad del diseño de UI/UX en el desarrollo de software, en realidad es bastante importante, ya que puede determinar directamente la experiencia del usuario y el éxito comercial del producto. Sin embargo, en el proceso de desarrollo tradicional, siempre hay un muro invisible entre diseñadores y desarrolladores: los diseñadores crean diseños estáticos exquisitos, y los desarrolladores se esfuerzan por implementarlos, pero siempre hay ciertas desviaciones en algunos detalles. Esta división hace que sea difícil que el producto final coincida completamente con la visión del diseño, y los costos de iteración también aumentan.

Al desarrollar aplicaciones de escritorio y productos web, el proyecto HagiCode también necesita soporte profesional de diseño UI/UX, y al mismo tiempo requiere una colaboración estrecha entre el diseño y la implementación del código. Para esto, introdujimos la herramienta impeccable: una herramienta profesional de diseño y optimización de interfaces frontend impulsada por IA. impeccable no solo proporciona orientación de diseño, sino que también puede procesar directamente la implementación del código, lo que ayuda a llenar el vacío entre el diseño y el desarrollo.

Para que impeccable se integre y se use efectivamente en el monorepo HagiCode, necesitamos establecer métodos de integración estandarizados, procesos de documentación y especificaciones de mantenimiento. Esto incluye la instalación y configuración de la herramienta, la integración de habilidades, la construcción del sitio de documentación, así como las mejores prácticas para la colaboración en equipo.

Sobre HagiCode

La solución compartida en este artículo proviene de nuestra experiencia práctica en el proyecto HagiCode. HagiCode es un proyecto de asistente de código de IA que proporciona dos formas: web y escritorio, ayudando a los desarrolladores a mejorar la eficiencia de codificación. Durante el proceso de desarrollo, necesitamos herramientas de diseño de alta calidad para apoyar la construcción de UI/UX del producto, e impeccable se introdujo en el proyecto exactamente en este contexto.

Análisis de la arquitectura técnica

Diseño impulsado por habilidades de impeccable

impeccable adopta una arquitectura de diseño impulsada por habilidades, definiendo el contexto y el comportamiento de diferentes tareas de diseño a través de archivos de habilidades estandarizados. En el proyecto HagiCode, impeccable se integra en forma de paquete de habilidades npm y se utiliza principalmente de las siguientes maneras:

1. Estructura de archivos de habilidades: /home/newbe36524/.agents/skills/impeccable/SKILL.md define la configuración completa de habilidades, incluidas colecciones de comandos, permisos de herramientas, sugerencias de parámetros e información de licencia.

2. Sistema de clasificación de comandos: impeccable divide las tareas de diseño en seis categorías principales:

   • Build: Comandos de construcción (craft, shape, teach, document, extract)
   • Evaluate: Comandos de evaluación (critique, audit)
   • Refine: Comandos de optimización (polish, bolder, quieter, distill, harden, onboard)
   • Enhance: Comandos de mejora (animate, colorize, typeset, layout, delight, overdrive)
   • Fix: Comandos de corrección (clarify, adapt, optimize)
   • Iterate: Comandos de iteración (live)

Análisis de requisitos del sitio de documentación

Para apoyar el uso de impeccable por parte del equipo, HagiCode estableció un sitio de documentación independiente impeccable-site, que necesita cumplir con los siguientes requisitos:

• Soporte multilingüe: Proporcionar documentación completa en inglés y chino para satisfacer las necesidades del equipo internacionalizado
• Directorio de comandos: Mostrar de manera normalizada todos los comandos, incluidas clasificaciones, descripciones y enlaces de referencia
• Contenido localizado: Mantener guías de uso específicas de HagiCode y mejores prácticas
• Generación estática: Usar Astro para construir el sitio estático, facilitando el despliegue y el acceso

Desafíos de integración

Durante el proceso de integración se enfrentan los siguientes desafíos:

1. Sincronización de código fuente: El repositorio upstream de impeccable contiene el código completo de la herramienta y la documentación, pero se necesita integrar selectivamente la parte de documentación para evitar depender de toda la base de código de la herramienta

2. Mantenimiento de contenido: Es necesario mantener el contenido localizado y las guías de uso mientras se mantiene la sincronización con las actualizaciones upstream

3. Proceso de construcción: Establecer un proceso automatizado de sincronización de contenido, generación de directorios y construcción del sitio

4. Flujo de trabajo multilingüe: Diseñar un flujo de trabajo eficiente de traducción y mantenimiento de localización

Diseño de la solución

Diseño de la estructura del repositorio

Integrar el repositorio upstream de impeccable a través del mecanismo de Git submodule:

[submodule "vendor/impeccable"]
    path = vendor/impeccable
    url = https://github.com/pbakaus/impeccable.git

Las ventajas de este diseño incluyen:

• Control de versiones: Se puede controlar con precisión la versión upstream, evitando problemas causados por actualizaciones accidentales
• Integración ligera: Solo se extrae el código fuente necesario, evitando introducir dependencias innecesarias
• Actualización flexible: Se puede actualizar selectivamente el contenido upstream

Diseño del modelo de contenido

Adoptar un modelo de contenido por capas:

1. Código fuente upstream: vendor/impeccable/ - Proporciona definiciones originales de comandos y documentación de referencia
2. Contenido localizado: src/content/commands/ - Mantiene explicaciones de comandos en chino e inglés
3. Texto de interfaz compartido: src/i18n/locales/ - Administra el texto multilingüe de la interfaz del sitio
4. Directorio generativo: src/lib/generated/command-catalog.json - Directorio de comandos generado en tiempo de construcción

Optimización del proceso de construcción

Diseñar un proceso de construcción automatizado, integrando varios pasos a través de scripts npm:

{
  "scripts": {
    "prepare": "npm run i18n:generate && npm run catalog:generate",
    "i18n:generate": "node scripts/generate-i18n-resources.mjs",
    "catalog:generate": "node scripts/build-command-catalog.mjs",
    "content:sync:vendor": "node scripts/sync-vendor-command-content.mjs",
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

El proceso de construcción se divide en cuatro etapas:

1. Etapa de preparación: Generar recursos multilingües y directorios de comandos
2. Sincronización de contenido: Sincronizar el contenido de los comandos desde upstream al local
3. Etapa de verificación: Verificar la integridad del contenido y la corrección de la construcción
4. Construcción de salida: Generar archivos del sitio estático

Flujo de trabajo multilingüe

Establecer un flujo de trabajo multilingüe estandarizado basado en la cadena de herramientas hagi18n:

localesRoot: src/i18n/locales
repoRoot: .
baseLocale: en-US
targetLocales:
  - zh-CN

Proporcionar scripts de mantenimiento completos:

• i18n:audit - Verificar la integridad de la traducción
• i18n:sync - Sincronizar entradas de traducción
• i18n:prune - Limpiar traducciones obsoletas
• i18n:doctor - Diagnosticar problemas de traducción

Guía de práctica

Configuración inicial

Primero inicialice el submodule e instale las dependencias:

# Ingrese al directorio raíz del monorepo
cd /home/newbe36524/repos/hagicode-mono

# Inicialice el submodule
git submodule update --init --recursive

# Ingrese al directorio impeccable-site
cd repos/impeccable-site

# Instale las dependencias
env -u NPM_CONFIG_PREFIX npm install

Este paso es la base de todo el proceso de integración. Si la inicialización del submodule falla, todos los pasos posteriores no se podrán realizar. HagiCode encontró este problema durante la primera integración, y luego aclaró los pasos de inicialización en la documentación.

Flujo de desarrollo diario

Ejecute comandos de desarrollo diario en el directorio repos/impeccable-site:

# Iniciar el servidor de desarrollo
env -u NPM_CONFIG_PREFIX npm run dev

# Verificación de tipos
env -u NPM_CONFIG_PREFIX npm run typecheck

# Ejecutar pruebas
env -u NPM_CONFIG_PREFIX npm test

# Construir el sitio
env -u NPM_CONFIG_PREFIX npm run build

# Verificación completa
env -u NPM_CONFIG_PREFIX npm run validate

El servidor de desarrollo se ejecuta por defecto en http://localhost:31266, y se puede personalizar el puerto a través de la variable de entorno PORT_IMPECCABLE_SITE. Los miembros del equipo de HagiCode descubrieron durante el proceso de desarrollo que, al cambiar frecuentemente entre diferentes entornos de idioma, el uso de comandos de prefijo unificados puede evitar problemas de contaminación de variables de entorno.

Estrategia de mantenimiento de contenido

Al agregar o actualizar la documentación de comandos, es necesario crear los archivos correspondientes en dos directorios de idioma:

# Documentación de comando en inglés
src/content/commands/en-US/polish.mdx

# Documentación de comando en chino
src/content/commands/zh-CN/polish.mdx

Cada archivo MDX debe contener metadatos frontmatter:

---
title: "Polish"
slug: "polish"
seoTitle: "Polish Command - Impeccable"
seoDescription: "Final quality pass before shipping with impeccable polish command"
routeSlug: "polish"
highlights:
  - "Visual hierarchy review"
  - "Spacing and typography optimization"
  - "Accessibility validation"
related:
  - "audit"
  - "critique"
---

Sincronización de contenido upstream

Cuando upstream impeccable se actualice, es necesario sincronizar el contenido más reciente de los comandos:

# Actualizar el submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# Sincronizar el contenido de los comandos
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# Sincronizar un solo comando
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# Regenerar el directorio
env -u NPM_CONFIG_PREFIX npm run catalog:generate

El script de sincronización leerá el contenido de los comandos upstream desde vendor/impeccable/site/content/skills/ y lo copiará al directorio src/content/commands/en-US/. El equipo de HagiCode descubrió en la práctica que después de cada sincronización es necesario regenerar el directorio de comandos, de lo contrario aparecerán problemas de inconsistencia de contenido.

Mantenimiento multilingüe

Mantener el texto multilingüe de la interfaz del sitio:

# Verificar la integridad de la traducción
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# Sincronizar entradas de traducción
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# Limpiar traducciones obsoletas
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# Diagnosticar problemas de traducción
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

Los archivos de traducción se encuentran en el directorio src/i18n/locales/:

src/i18n/locales/
├── en-US/
│   ├── common.yml
│   └── docs.yml
└── zh-CN/
    ├── common.yml
    └── docs.yml

Ejemplo de archivo YAML:

src/i18n/locales/en-US/docs.yml

commands:
  title: "Commands"
  subtitle: "Explore the complete command surface"
  overview: "Overview"
  related: "Related Commands"

# src/i18n/locales/zh-CN/docs.yml
commands:
  title: "命令"
  subtitle: "探索完整的命令集"
  overview: "概览"
  related: "相关命令"

Uso de comandos impeccable

En el proyecto HagiCode, puede invocar comandos impeccable de las siguientes maneras:

# Diseñar una nueva función
npx impeccable craft "user settings page"

# Planificar UI/UX
npx impeccable shape "checkout flow"

# Establecer el contexto del proyecto
npx impeccable teach

# Generar documentación de diseño
npx impeccable document

# Revisar la calidad del diseño
npx impeccable critique "landing page"

# Verificación de calidad técnica
npx impeccable audit "navigation component"

# Optimización final
npx impeccable polish "onboarding flow"

# Iteración de diseño en tiempo real
npx impeccable live

Cada comando tiene un propósito específico y documentación de referencia. Por ejemplo, el comando craft se usa para construir funciones de extremo a extremo, incluida la planificación UX/UI y la implementación del código; el comando audit se usa para verificaciones de calidad técnica, incluida la accesibilidad, el rendimiento y el diseño responsivo. Durante el proceso de desarrollo, estos comandos se han convertido en parte del flujo de trabajo diario de desarrollo del equipo de HagiCode.

Verificación de despliegue

Realice una verificación completa antes del despliegue:

# Ejecutar el proceso de verificación completo
env -u NPM_CONFIG_PREFIX npm run validate

El proceso de verificación verificará:

• Si la ruta del vendor es correcta
• Si todos los comandos tienen contenido correspondiente en los directorios chino e inglés
• Si los recursos multilingües generados están actualizados
• Si el directorio de comandos está actualizado
• Si las rutas de Astro se compilan correctamente
• Si la construcción de la salida estática tiene éxito

Precauciones y mejores prácticas

Precauciones importantes

1. Actualización del Submodule: Después de actualizar el submodule, es necesario regenerar los recursos derivados y confirmarlos. El equipo de HagiCode se encontró una vez con el caso de olvidarse de regenerar los recursos antes de confirmar directamente, lo que provocó problemas de inconsistencia de contenido en el sitio en línea.

2. Equivalencia de idiomas: Asegúrese de que todos los comandos tengan contenido correspondiente en los directorios chino e inglés, de lo contrario la construcción fallará. Esta verificación ya se ha integrado en el proceso de verificación, lo que permite detectar problemas en las primeras etapas del desarrollo.

3. Proxy frontend: impeccable-site se proxya a través del script de desarrollo del sitio estático en el directorio raíz del monorepo:

# Iniciar desde el directorio raíz del monorepo
npm run dev:static-sites

4. Despliegue en producción: El sitio de producción se despliega en https://impeccable.hagicode.com, con despliegue automatizado a través de GitHub Actions. HagiCode adoptó un proceso CI/CD completamente automatizado, asegurando que cada confirmación se despliegue automáticamente.

5. Enlaces de documentación de comandos: Al seleccionar comandos impeccable en UI Master del frontend web, se mostrará el enlace de documentación correspondiente, con el formato:

https://impeccable.hagicode.com/{lang}/commands/{command-name}

Resumen de mejores prácticas

1. Sincronización regular upstream: Preste atención a las actualizaciones de impeccable upstream y sincronice regularmente los nuevos comandos y mejoras. El equipo de HagiCode adopta una frecuencia de sincronización semanal para asegurarse de no perder actualizaciones importantes.

2. Mantenimiento del contenido localizado: Después de sincronizar el contenido upstream, actualice oportunamente la documentación en chino e inglés para asegurar la precisión y actualidad del contenido.

3. Control de versiones: Después de actualizar el submodule, es necesario verificar el resultado de la construcción antes de enviarlo al sistema de control de versiones.

4. Colaboración en equipo: A través de un flujo de trabajo multilingüe estandarizado, apoyar la colaboración de los miembros del equipo en el mantenimiento del contenido de la documentación.

5. Garantía de calidad: Ejecute el proceso de verificación completo después de cada actualización de contenido para asegurar la corrección del sitio.

6. Uso de clasificación de comandos: Seleccione la categoría de comando apropiada según diferentes etapas de la tarea de diseño:

   • Use craft o shape al diseñar nuevas funciones
   • Use critique o audit al revisar diseños existentes
   • Use polish, bolder o quieter al optimizar la calidad del diseño
   • Use animate, colorize o delight al mejorar los efectos visuales
   • Use clarify, adapt o optimize al corregir problemas
   • Use live al iterar en tiempo real

7. Gestión de contexto: Antes de usar el comando craft, asegúrese de haber establecido los archivos de contexto PRODUCT.md y DESIGN.md del proyecto a través del comando teach.

Resumen

A través de los métodos de integración y uso anteriores, el proyecto HagiCode puede utilizar efectivamente la capacidad de diseño profesional de la herramienta impeccable para mejorar la calidad UI/UX del producto, y al mismo tiempo establecer un proceso estandarizado de mantenimiento de documentación que apoye la colaboración y el desarrollo a largo plazo del equipo.

La solución compartida en este artículo es el resultado de múltiples iteraciones y optimizaciones en el desarrollo real de HagiCode. No solo resuelve el problema de la colaboración entre diseño y desarrollo, sino que también establece un sistema de documentación escalable, proporcionando una referencia para la integración de otras herramientas.

Si también enfrenta problemas de colaboración entre diseño y desarrollo en su equipo, espero que las prácticas de este artículo le sirvan de inspiración. La idea central de esta solución es: establecer procesos estandarizados, mantener la sincronización con upstream, prestar atención al mantenimiento de localización y apoyar la colaboración en equipo.

Resumen

En torno a “cómo integrar y usar impeccable”, una forma más segura de avanzar es poner en funcionamiento gradualmente las configuraciones clave, los límites de dependencias y las rutas de implementación, y luego completar los detalles de optimización.

Cuando los objetivos, los pasos y los puntos de aceptación estén claros, este tipo de soluciones generalmente pueden entrar en la entrega real de manera más fluida.

Tags:

• impeccable
• design
• integration
• workflow

MonoSpecs ¿Qué es y por qué se dice que es una actualización y extensión de OpenSpec

Optimizar la eficacia de cada fase de OpenSpec con diferentes Agentes: Resumen de la práctica de HagiCode