Comment nous utilisons impeccable pour optimiser la conception des interfaces frontend et la stabilité de l'implémentation

4 juil. 2026

Comment nous utilisons impeccable pour optimiser la conception des interfaces frontend et la stabilité de l’implémentation

Introduction

Beaucoup d’équipes rencontrent le même problème lorsqu’elles conçoivent une interface : le langage de design repose sur l’expérience, les détails d’interaction reposent sur la mémoire, et le résultat final est souvent « fonctionnel mais instable ».

Dans le monorepo HagiCode, impeccable n’est pas utilisé comme un « outil d’inspiration ». Il est intégré à une chaîne d’ingénierie exécutable, vérifiable et capable de non-régression :

• L’entrée des tâches repose sur des contraintes structurées (commandes, scénarios, périmètre des dépôts)
• Le contenu du site et les définitions des commandes en amont sont alignés automatiquement
• Les ports de développement local, les paramètres d’exécution et le processus de vérification sont fixés

Cet article s’appuie sur l’implémentation existante du dépôt et se découpe en quatre parties : Background, Analysis, Solution et Practice.

Contexte (Background)

Dans l’état actuel du dépôt, les éléments directement liés à impeccable se trouvent principalement à trois endroits :

1. Orchestration d’exécution du site statique : scripts/static-sites-dev.mjs
2. Site de documentation impeccable : repos/impeccable-site
3. Exemple de contrat de preset de tâche UI : designs/task-preset-plugin-examples/ui-master

Le troisième élément est un exemple de conception, et non le code d’exécution backend en production. Il faut le préciser d’emblée pour ne pas confondre « contrat de conception » et « comportement publié ».

Analyse (Analysis)

1) Structurer d’abord l’intention de conception pour réduire les dérives liées à l’« improvisation »

Dans l’exemple de contrat backend de ui-master, les dépendances et les entrées sont fixées avant l’exécution.

designs/task-preset-plugin-examples/ui-master/backend/task-preset.json :

{
  "taskKey": "uiMaster",
  "scriptKey": "autotask.ui-master",
  "requirements": [
    {
      "type": "skills",
      "name": "impeccable"
    },
    {
      "type": "cli",
      "name": "impeccable",
      "command": "npm",
      "args": ["exec", "--offline", "--", "impeccable", "--help"]
    }
  ],
  "inputBindings": [
    {
      "input": "uiMasterDescription",
      "promptParameter": "uiMasterDescription",
      "required": true
    },
    {
      "input": "uiMasterCommandIds",
      "promptParameter": "uiMasterCommandIds",
      "required": true
    },
    {
      "input": "sceneKey",
      "promptParameter": "sceneKey"
    }
  ]
}

Points clés :

• Vérifier skills:impeccable et cli:impeccable en amont, pour ne pas découvrir une rupture de la chaîne en pleine exécution.
• uiMasterCommandIds impose une entrée sous forme de commandes, pour éviter une description longue mais une direction floue.
• sceneKey unifie la clé de scénario, pour que chaque preset n’invente pas son propre jeu de noms d’entrées.

Cette structure apporte une valeur directe à la stabilité : les échecs sont détectés en amont, sont explicables et les entrées peuvent être rejouées.

2) Unifier le catalogue de commandes et le routage de la documentation pour réduire les dérives sémantiques

designs/task-preset-plugin-examples/ui-master/frontend/commands.json définit les groupes de commandes, le modèle de routage de la documentation et le préambule de commande :

{
  "docs": {
    "baseUrl": "https://impeccable.hagicode.com",
    "routeTemplate": "/{lang}/docs/{commandId}",
    "languageResolver": "supported-language"
  },
  "commands": [
    {
      "id": "craft",
      "groupId": "build",
      "skill": "impeccable",
      "docsSlug": "craft",
      "preludeTemplate": "/impeccable {commandId} {uiMasterDescription}"
    }
  ]
}

Cela permet à « l’exécution de la commande, la description dans la documentation et le routage par langue » de partager le même jeu d’identifiants, ce qui réduit les décalages fréquents :

• La documentation nomme une chose A, le panneau la nomme B
• La page en chinois renvoie vers la mauvaise commande en anglais
• Le préambule du prompt et le slug de la documentation ne correspondent pas

3) Faire de la validité du contenu un actif vérifiable du site

Dans repos/impeccable-site/package.json, validate enchaîne toute la barrière de qualité :

{
  "scripts": {
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

Et le script derrière catalog:check (scripts/build-command-catalog.mjs) impose une vérification stricte de la structure du frontmatter :

function parseFrontmatter(sourceText, sourcePath) {
  const match = sourceText.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/u);
  assert(match, `${sourcePath} must include YAML frontmatter`);
  const frontmatter = load(match[1]);
  assert(isPlainObject(frontmatter), `${sourcePath} frontmatter must be a mapping`);
  return {
    frontmatter,
    body: match[2].trim(),
  };
}

Ces assertions sont simples, mais elles sont essentielles pour la stabilité : il vaut mieux échouer immédiatement en local et en CI que découvrir après la mise en ligne qu’un champ de la documentation manque.

4) Fixer les ports et l’environnement de développement pour éviter le « ça marche chez moi, pas chez toi »

Dans le script racine du monorepo scripts/static-sites-dev.mjs, impeccable est explicitement orchestré :

{
  id: 'impeccable',
  name: 'Impeccable',
  repoPath: 'repos/impeccable-site',
  productionUrl: 'https://impeccable.hagicode.com/',
  command: 'npm',
  args: ['run', 'dev'],
  env: {
    PORT_IMPECCABLE_SITE: '36296'
  },
  portHint: 36296,
  order: 56
}

Le test scripts/static-sites-dev.test.mjs vérifie également ces valeurs (port, args, env, productionUrl).

Cette approche « valeurs figées + tests » n’a rien de spectaculaire, mais elle est stable :

• Le point d’entrée local est unifié
• Le chemin de diagnostic est fixe
• Les liens du site de documentation ne dérivent pas

Solution (Solution)

Si vous voulez utiliser impeccable pour améliorer à la fois la qualité de l’interface et la stabilité de l’implémentation, la pratique actuelle du dépôt peut se concrétiser en quatre couches.

Première couche : contractualiser l’entrée des tâches

Méthode : réutiliser une structure de preset comme ui-master.

Objectifs :

• Limiter le périmètre de dépôts autorisé (targetRepositories)
• Limiter la source des commandes (uiMasterCommandIds)
• Limiter le point d’entrée du contexte (uiMasterDescription)

Bénéfice : chaque répartition de travail peut être relue, avec la question « quelle était l’entrée et pourquoi ce changement ».

Deuxième couche : unifier la sémantique des commandes

Méthode : lier ensemble l’ID de commande, le slug de la documentation et le modèle de préambule.

Objectifs :

• La commande sélectionnée dans le panneau peut renvoyer vers la documentation ayant le même ID
• /impeccable <command> dans le prompt et l’explication de la documentation sont cohérents

Bénéfice : réduire le risque implicite de « terminologie cohérente, comportement incohérent ».

Troisième couche : vérifier le contenu comme un actif

Méthode : garder npm run validate comme barrière avant chaque commit.

Objectifs :

• Aucune clé i18n manquante
• Le catalogue de commandes et la structure amont ne dérivent pas
• Le typage, les tests et la compilation réussissent en une seule passe

Bénéfice : détecter les problèmes de contenu occasionnels dès l’environnement local.

Quatrième couche : standardiser l’environnement d’exécution

Méthode : démarrer via static-sites-dev de manière uniforme, en fixant PORT_IMPECCABLE_SITE.

Objectifs :

• Minimiser les conflits de ports lors du travail en équipe
• Fixer le chemin de mise au point lorsque plusieurs sites sont utilisés ensemble

Bénéfice : gagner du temps sur la configuration de l’environnement et localiser plus vite les problèmes dans le code lui-même.

Pratique (Practice)

Étape 1 : initialiser impeccable-site

cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --init --recursive
env -u NPM_CONFIG_PREFIX npm install

Étape 2 : développement local et validation globale

env -u NPM_CONFIG_PREFIX npm run dev
env -u NPM_CONFIG_PREFIX npm run validate

validate couvre en une seule fois i18n, catalog, typecheck, test et build.

Étape 3 : exécuter via l’orchestration unifiée du monorepo

Depuis la racine du monorepo, passez par le système scripts/static-sites-dev.mjs et réutilisez PORT_IMPECCABLE_SITE=36296 déjà défini.

À cette étape, l’essentiel n’est pas « que ça tourne », mais « que tout le monde le lance de la même manière ».

Étape 4 : transformer les demandes UI en entrées de commandes

Dans le flux de task preset, faites en sorte que les besoins soient d’abord formulés comme suit :

• uiMasterDescription : l’objectif métier
• uiMasterCommandIds : les commandes de ce passage (par exemple craft, audit, polish)
• sceneKey : le contexte de scénario

Passez ensuite à la phase de modification, ce qui réduit les dérives de direction causées par une modification directe de l’interface.

Étape 5 : clarifier les lacunes du matériel actuel

D’après l’état actuel du dépôt, on peut confirmer que :

• Le site impeccable-site et sa chaîne de validation sont du code opérationnel.
• Le contrat de liaison approfondie entre ui-master et impeccable figure principalement dans designs/task-preset-plugin-examples et dans les documents de conception.

Si vous voulez conclure que « tout est activé en production côté backend », les preuves actuelles ne suffisent pas. Ne portez pas ce jugement pour le moment.

Présentation de HagiCode

HagiCode est une plateforme qui intègre un projet multi-dépôts, l’exécution de tâches IA, un site de documentation et une chaîne d’outils. Son atout principal n’est pas la simple capacité à « générer du code » en un point, mais l’enchaînement stable des contraintes d’entrée des tâches, du contexte d’exécution, des barrières de validation et de la collaboration inter-dépôts. Les scénarios d’usage typiques incluent : l’itération structurée d’interfaces, la mise au point de fonctionnalités entre dépôts, la production de contenus techniques guidée par des normes, et la livraison automatisée assortie de barrières qualité.

Conclusion

La vraie valeur d’impeccable ne réside pas dans le fait de « vous aider à imaginer un bouton plus joli », mais dans le fait de « rendre l’optimisation de l’interface ingénierisable ». Dans la pratique actuelle de HagiCode, cela repose sur quatre actions : contractualiser les tâches, unifier la sémantique des commandes, placer la validation du contenu en amont et standardiser l’environnement d’exécution. Consolidez d’abord ces fondations, puis passez aux améliorations de design plus spectaculaires : le gain sera plus grand et plus durable.

Tags:

• impeccable
• frontend
• stability
• hagicode

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