Comment intégrer et utiliser impeccable

10 juin 2026

Comment intégrer et utiliser impeccable

En fait, ce n’est pas grand-chose : c’est juste intégrer un outil de conception dans le projet HagiCode, ce qui peut à peine être considéré comme une solution complète — y compris la structure du dépôt, le flux de travail multilingue, la maintenance du contenu, tout cela a été progressivement exploré dans la pratique.

Contexte

En ce qui concerne la qualité de la conception UI/UX dans le développement logiciel, c’est en fait assez important, car elle peut directement déterminer l’expérience utilisateur et le succès commercial d’un produit. Cependant, dans les processus de développement traditionnels, il y a toujours un mur invisible entre les concepteurs et les développeurs : les concepteurs créent des maquettes statiques exquises, les développeurs s’efforcent de les implémenter, mais il y a toujours certains écarts dans certains détails. Cette fragmentation rend difficile pour le produit final de correspondre parfaitement à la vision de conception, et les coûts d’itération augmentent en conséquence.

Le projet HagiCode, lors du développement d’applications de bureau et de produits Web, a également besoin d’un support professionnel en conception UI/UX, tout en exigeant une collaboration étroite entre la conception et l’implémentation du code. Pour cela, nous avons introduit l’outil impeccable — un outil professionnel de conception et d’optimisation d’interface frontend propulsé par l’IA. impeccable fournit non seulement des conseils de conception, mais peut également traiter directement l’implémentation du code, ce qui comble en quelque sorte le fossé entre la conception et le développement.

Pour permettre une intégration et une utilisation efficaces d’impeccable dans le monorepo HagiCode, nous devons établir une méthode d’intégration standardisée, un processus de documentation et des normes de maintenance. Cela comprend l’installation et la configuration de l’outil, l’intégration des compétences, la construction du site de documentation, ainsi que les meilleures pratiques pour la collaboration d’équipe.

À propos de HagiCode

La solution partagée dans cet article provient de notre expérience pratique dans le projet HagiCode. HagiCode est un projet d’assistant de code IA qui propose deux formes : une version Web et une version de bureau, aidant les développeurs à améliorer leur efficacité de codage. Au cours du processus de développement, nous avions besoin d’outils de conception de haute qualité pour soutenir la construction de l’UI/UX du produit, et c’est dans ce contexte qu’impeccable a été introduit dans le projet.

Analyse de l’architecture technique

Conception basée sur les compétences d’impeccable

impeccable adopte une architecture de conception basée sur les compétences, définissant le contexte et le comportement de différentes tâches de conception via des fichiers de compétences standardisés. Dans le projet HagiCode, impeccable est intégré sous forme de paquet de compétences npm et principalement utilisé de la manière suivante :

1. Structure des fichiers de compétences : /home/newbe36524/.agents/skills/impeccable/SKILL.md définit la configuration complète des compétences, y compris l’ensemble des commandes, les permissions d’outils, les invites de paramètres et les informations de licence.

2. Système de classification des commandes : impeccable divise les tâches de conception en six catégories principales :

   • Build : commandes de construction (craft, shape, teach, document, extract)
   • Evaluate : commandes d’évaluation (critique, audit)
   • Refine : commandes d’optimisation (polish, bolder, quieter, distill, harden, onboard)
   • Enhance : commandes d’amélioration (animate, colorize, typeset, layout, delight, overdrive)
   • Fix : commandes de correction (clarify, adapt, optimize)
   • Iterate : commandes d’itération (live)

Analyse des besoins du site de documentation

Pour soutenir l’utilisation d’impeccable par l’équipe, HagiCode a établi un site de documentation indépendant impeccable-site, qui doit répondre aux besoins suivants :

• Support multilingue : fournir une documentation complète en anglais et en chinois pour répondre aux besoins d’une équipe internationale
• Catalogue de commandes : afficher normalisé toutes les commandes, y compris la classification, la description et les liens de référence
• Contenu localisé : maintenir des guides d’utilisation et des meilleures pratiques spécifiques à HagiCode
• Génération statique : utiliser Astro pour construire le site statique, facilitant le déploiement et l’accès

Défis d’intégration

Au cours du processus d’intégration, les défis suivants ont été rencontrés :

1. Synchronisation du code source : le dépôt amont impeccable contient le code complet de l’outil et la documentation, mais il est nécessaire d’intégrer sélectivement la partie documentation pour éviter de dépendre de tout le dépôt de code de l’outil

2. Maintenance du contenu : il est nécessaire de maintenir le contenu localisé et les guides d’utilisation tout en maintenant la synchronisation avec les mises à jour amont

3. Processus de construction : établir un processus automatisé de synchronisation du contenu, de génération de catalogue et de construction du site

4. Flux de travail multilingue : concevoir un processus efficace de traduction et de maintenance localisée

Conception de la solution

Conception de la structure du dépôt

Intégrer le dépôt amont impeccable via le mécanisme de Git submodule :

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

Les avantages de cette conception incluent :

• Contrôle de version : peut contrôler précisément la version amont, évitant les problèmes causés par des mises à jour accidentelles
• Intégration légère : ne récupère que le code source nécessaire, évitant d’introduire des dépendances inutiles
• Mises à jour flexibles : peut choisir de mettre à jour sélectivement le contenu amont

Conception du modèle de contenu

Adopter un modèle de contenu en couches :

1. Code source amont : vendor/impeccable/ - fournit les définitions de commandes originales et la documentation de référence
2. Contenu localisé : src/content/commands/ - maintient les descriptions de commandes en anglais et en chinois
3. Copie d’interface utilisateur partagée : src/i18n/locales/ - gère le texte multilingue de l’interface du site
4. Catalogue généré : src/lib/generated/command-catalog.json - catalogue de commandes généré lors de la construction

Optimisation du processus de construction

Concevoir un processus de construction automatisé, intégrant chaque étape via des 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"
  }
}

Le processus de construction se divise en quatre étapes :

1. Étape de préparation : générer les ressources multilingues et le catalogue de commandes
2. Synchronisation du contenu : synchroniser le contenu des commandes depuis l’amont vers le local
3. Étape de validation : vérifier l’intégrité du contenu et la correction de la construction
4. Sortie de construction : générer les fichiers de site statique

Flux de travail multilingue

Établir un flux de travail multilingue standardisé basé sur la chaîne d’outils hagi18n :

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

Fournir des scripts de maintenance complets :

• i18n:audit - vérifier la complétude de la traduction
• i18n:sync - synchroniser les entrées de traduction
• i18n:prune - nettoyer les traductions obsolètes
• i18n:doctor - diagnostiquer les problèmes de traduction

Guide de pratique

Configuration initiale

Tout d’abord, initialisez le submodule et installez les dépendances :

# Entrer dans le répertoire racine du monorepo
cd /home/newbe36524/repos/hagicode-mono

# Initialiser le submodule
git submodule update --init --recursive

# Entrer dans le répertoire impeccable-site
cd repos/impeccable-site

# Installer les dépendances
env -u NPM_CONFIG_PREFIX npm install

Cette étape est la base de tout le processus d’intégration. L’échec de l’initialisation du submodule empêchera toutes les étapes ultérieures de se dérouler. HagiCode a rencontré ce problème lors de la première intégration, et les étapes d’initialisation ont ensuite été clarifiées dans la documentation.

Processus de développement quotidien

Exécutez les commandes de développement quotidien dans le répertoire repos/impeccable-site :

# Démarrer le serveur de développement
env -u NPM_CONFIG_PREFIX npm run dev

# Vérification de type
env -u NPM_CONFIG_PREFIX npm run typecheck

# Exécuter les tests
env -u NPM_CONFIG_PREFIX npm test

# Construire le site
env -u NPM_CONFIG_PREFIX npm run build

# Validation complète
env -u NPM_CONFIG_PREFIX npm run validate

Le serveur de développement fonctionne par défaut sur http://localhost:31266 et le port peut être personnalisé via la variable d’environnement PORT_IMPECCABLE_SITE. Les membres de l’équipe HagiCode ont découvert lors du processus de développement que l’utilisation d’une commande de préfixe unifiée pouvait éviter les problèmes de pollution des variables d’environnement lors de fréquents changements d’environnement linguistique.

Stratégie de maintenance du contenu

Lors de l’ajout ou de la mise à jour de la documentation des commandes, il est nécessaire de créer des fichiers correspondants dans deux répertoires linguistiques :

# Documentation de commande en anglais
src/content/commands/en-US/polish.mdx

# Documentation de commande en chinois
src/content/commands/zh-CN/polish.mdx

Chaque fichier MDX doit contenir les métadonnées 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"
---

Synchronisation du contenu amont

Lorsque l’amont impeccable est mis à jour, il est nécessaire de synchroniser le contenu de commande le plus récent :

# Mettre à jour le submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# Synchroniser le contenu des commandes
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# Synchroniser une seule commande
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# Régénérer le catalogue
env -u NPM_CONFIG_PREFIX npm run catalog:generate

Le script de synchronisation lit le contenu des commandes amont depuis vendor/impeccable/site/content/skills/ et le copie dans le répertoire src/content/commands/en-US/. L’équipe HagiCode a découvert dans la pratique qu’après chaque synchronisation, il est nécessaire de régénérer le catalogue de commandes, sinon des incohérences de contenu se produiront.

Maintenance multilingue

Maintenir le texte multilingue de l’interface du site :

# Vérifier la complétude de la traduction
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# Synchroniser les entrées de traduction
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# Nettoyer les traductions obsolètes
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# Diagnostiquer les problèmes de traduction
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

Les fichiers de traduction sont situés dans le répertoire src/i18n/locales/ :

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

Exemple de fichier 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: "相关命令"

Utilisation des commandes impeccable

Dans le projet HagiCode, les commandes impeccable peuvent être appelées des manières suivantes :

# Concevoir de nouvelles fonctionnalités
npx impeccable craft "user settings page"

# Planifier l'UI/UX
npx impeccable shape "checkout flow"

# Configurer le contexte du projet
npx impeccable teach

# Générer la documentation de conception
npx impeccable document

# Réviser la qualité de conception
npx impeccable critique "landing page"

# Vérification de la qualité technique
npx impeccable audit "navigation component"

# Optimisation finale
npx impeccable polish "onboarding flow"

# Itération de conception en temps réel
npx impeccable live

Chaque commande a un usage spécifique et une documentation de référence. Par exemple, la commande craft est utilisée pour construire des fonctionnalités de bout en bout, y compris la planification UX/UI et l’implémentation du code ; la commande audit est utilisée pour la vérification de la qualité technique, y compris l’accessibilité, les performances et la conception responsive. Dans le processus de développement de l’équipe HagiCode, ces commandes sont devenues une partie du flux de travail quotidien de développement.

Validation de déploiement

Effectuer une validation complète avant déploiement :

# Exécuter le processus de validation complet
env -u NPM_CONFIG_PREFIX npm run validate

Le processus de validation vérifiera :

• Si le chemin vendor est correct
• Si toutes les commandes ont un contenu correspondant dans les répertoires anglais et chinois
• Si les ressources multilingues générées sont à jour
• Si le catalogue de commandes est à jour
• Si les routes Astro sont compilées correctement
• Si la sortie statique est construite avec succès

Précautions et meilleures pratiques

Précautions importantes

1. Mise à jour du submodule : après avoir mis à jour le submodule, il est nécessaire de régénérer les ressources dérivées et de les valider. L’équipe HagiCode a une fois rencontré une situation où elle avait oublié de régénérer les ressources avant de valider directement, ce qui avait provoqué des incohérences de contenu sur le site en ligne.

2. Équivalence linguistique : assurez-vous que toutes les commandes ont un contenu correspondant dans les répertoires anglais et chinois, sinon la construction échouera. Cette vérification a été intégrée dans le processus de validation, permettant de détecter les problèmes dès le début du développement.

3. Proxy frontend : impeccable-site est proxifié via le script de développement de site statique dans le répertoire racine du monorepo :

# Démarrer depuis le répertoire racine du monorepo
npm run dev:static-sites

4. Déploiement en production : le site de production est déployé sur https://impeccable.hagicode.com, avec un déploiement automatisé via GitHub Actions. HagiCode a adopté un processus CI/CD entièrement automatisé, garantissant que chaque commit peut être automatiquement déployé.

5. Liens de documentation des commandes : lors de la sélection d’une commande impeccable dans UI Master du frontend Web, le lien de documentation correspondant s’affiche, avec le format suivant :

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

Résumé des meilleures pratiques

1. Synchroniser régulièrement l’amont : surveillez les mises à jour de l’amont impeccable et synchronisez régulièrement les nouvelles commandes et améliorations. L’équipe HagiCode adopte une fréquence de synchronisation hebdomadaire pour garantir de ne pas manquer les mises à jour importantes.

2. Maintenir le contenu localisé : après avoir synchronisé le contenu amont, mettez à jour rapidement la documentation en anglais et en chinois pour garantir l’exactitude et l’actualité du contenu.

3. Contrôle de version : après la mise à jour du submodule, vérifiez les résultats de construction avant de valider dans le système de contrôle de version.

4. Collaboration d’équipe : via un flux de travail multilingue standardisé, soutenir la collaboration des membres de l’équipe pour maintenir le contenu de la documentation.

5. Assurance qualité : après chaque mise à jour de contenu, exécutez le processus de validation complet pour garantir la correction du site.

6. Utilisation par catégorie de commandes : choisissez la catégorie de commandes appropriée selon les différentes étapes des tâches de conception :

   • Utilisez craft ou shape lors de la conception de nouvelles fonctionnalités
   • Utilisez critique ou audit lors de la révision de conceptions existantes
   • Utilisez polish, bolder ou quieter lors de l’optimisation de la qualité de conception
   • Utilisez animate, colorize ou delight lors de l’amélioration des effets visuels
   • Utilisez clarify, adapt ou optimize lors de la résolution de problèmes
   • Utilisez live lors de l’itération en temps réel

7. Gestion du contexte : avant d’utiliser la commande craft, assurez-vous d’avoir configuré les fichiers de contexte PRODUCT.md et DESIGN.md du projet via la commande teach.

Résumé

Grâce aux méthodes d’intégration et d’utilisation ci-dessus, le projet HagiCode peut efficacement utiliser les capacités de conception professionnelle de l’outil impeccable pour améliorer la qualité UI/UX du produit, tout en établissant un processus de maintenance de documentation standardisé, soutenant la collaboration et le développement à long terme de l’équipe.

La solution partagée dans cet article est le résultat de multiples itérations et optimisations du projet HagiCode dans le développement réel. Elle résout non seulement le problème de collaboration conception-développement, mais établit également un système de documentation évolutif, fournissant une référence pour l’intégration d’autres outils.

Si vous êtes également confronté à des problèmes similaires de collaboration conception-développement dans votre équipe, j’espère que les pratiques de cet article vous inspireront. L’idée centrale de cette solution est : établir des processus standardisés, maintenir la synchronisation avec l’amont, se concentrer sur la maintenance localisée, soutenir la collaboration d’équipe.

Résumé

Autour de « Comment intégrer et utiliser impeccable », une approche plus sûre pour progresser consiste d’abord à faire fonctionner progressivement les configurations clés, les limites de dépendances et les chemins de mise en œuvre, puis à combler les détails d’optimisation.

Lorsque les objectifs, les étapes et les points de validation sont clairs, ce type de solution peut généralement entrer plus facilement dans la livraison réelle.

Tags:

• impeccable
• design
• integration
• workflow

MonoSpecs qu'est-ce que c'est : pourquoi c'est une évolution et une extension supplémentaire d'OpenSpec

Optimiser l'efficacité des différentes phases d'OpenSpec avec différents agents : Résumé des pratiques HagiCode