Wie wir impeccable nutzen, um das Frontend-Design zu verbessern und die Implementierung stabil zu halten

04.07.2026

Wie wir impeccable nutzen, um das Frontend-Design zu verbessern und die Implementierung stabil zu halten

Einleitung

Viele Teams kennen beim Arbeiten an UIs dasselbe Problem: Die Designsprache beruht auf Erfahrung, die Interaktionsdetails stecken im Gedächtnis, und das Ergebnis ist oft „funktioniert, aber wackelt“.

Im HagiCode-Monorepo wird impeccable nicht als „Inspirationswerkzeug“ eingesetzt. Stattdessen ist es in eine ausführbare, überprüfbare und regressionssichere Engineering-Kette eingebettet:

• Der Einstieg in Aufgaben ist strukturiert eingeschränkt (Befehle, Szenarien, Repository-Umfang)
• Die Inhalte der Website und die Befehlsdefinitionen des Upstreams werden automatisch abgeglichen
• Lokale Entwicklungsports, Laufzeitparameter und Validierungsabläufe sind festgelegt

Dieser Artikel stützt sich auf die bestehende Implementierung im Repository und gliedert sich in vier Teile: Background, Analysis, Solution und Practice.

Hintergrund (Background)

Im aktuellen Repository-Stand sind die Stellen, die direkt mit impeccable zusammenhängen, vor allem an drei Orten zu finden:

1. Orchestrierung des statischen Sites-Starts: scripts/static-sites-dev.mjs
2. Dokumentationsseite von impeccable: repos/impeccable-site
3. Beispiel für den UI-Task-Preset-Vertrag: designs/task-preset-plugin-examples/ui-master

Der dritte Punkt ist ein Designbeispiel und nicht der eigentliche Code der produktiven Backend-Laufzeit. Das sollte zuerst klargestellt werden, damit der „Designvertrag“ nicht mit einem „veröffentlichten Verhalten“ verwechselt wird.

Analyse (Analysis)

1) Designabsicht zuerst strukturieren, damit weniger „freies Improvisieren“ entsteht

Im Backend-Vertragsbeispiel von ui-master werden Abhängigkeiten und Eingaben zuerst festgelegt, bevor die Ausführung beginnt.

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"
    }
  ]
}

Die wichtigsten Punkte:

• skills:impeccable und cli:impeccable werden vorab geprüft, damit ein unterbrochener Ablauf nicht erst während der Ausführung auffällt.
• uiMasterCommandIds erzwingt eine Eingabe in Form von Befehlen, damit keine „sehr lange Beschreibung mit unklarer Richtung“ entsteht.
• sceneKey vereinheitlicht den Szenenschlüssel, sodass nicht jedes Preset ein eigenes Eingabesystem erfindet.

Für die Stabilität ist dieser Aufbau sehr direkt wertvoll: Fehler treten früh auf, sind erklärbar und Eingaben lassen sich wiederholen.

2) Befehlskatalog und Dokumentationsrouting vereinheitlichen, damit sich die Semantik nicht verschiebt

designs/task-preset-plugin-examples/ui-master/frontend/commands.json definiert Befehlsgruppen, Routing-Vorlagen für die Dokumentation und das Befehls-Prelude:

{
  "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}"
    }
  ]
}

Dadurch nutzen „Befehlsausführung, Dokumentationsbeschreibung und Sprachrouting“ dieselbe ID-Gruppe. Häufige Abweichungen werden so reduziert:

• Die Dokumentation nennt etwas A, das Panel nennt es B
• Eine deutsche Seite verlinkt auf den falschen englischen Befehl
• Das Prompt-Prelude und der Docs-Slug stimmen nicht überein

3) Die Inhaltskorrektheit der Website als überprüfbares Asset umsetzen

In repos/impeccable-site/package.json verknüpft validate die gesamte Qualitätskette:

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

Außerdem prüft das Skript hinter catalog:check (scripts/build-command-catalog.mjs) die Struktur des Frontmatters hart:

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(),
  };
}

Solche assert-Aufrufe sind schlicht, aber für die Stabilität besonders wichtig: Statt nach dem Release festzustellen, dass der Dokumentation ein Feld fehlt, sollte die Prüfung lokal und in der CI direkt fehlschlagen.

4) Feste Ports und Umgebungsvariablen in der Entwicklung, damit es nicht heißt „bei mir läuft es, bei dir nicht“

Im Root-Skript des Monorepos scripts/static-sites-dev.mjs wird impeccable ausdrücklich orchestriert:

{
  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
}

Der Test scripts/static-sites-dev.test.mjs prüft diese Werte ebenfalls (Port, Args, Env, productionUrl).

Diese Art „fest verdrahtet + getestet“ ist unspektakulär, aber stabil:

• Der lokale Einstieg ist einheitlich
• Der Weg zur Fehlersuche ist festgelegt
• Die Links der Dokumentationsseite driften nicht

Lösung (Solution)

Wenn Sie impeccable gleichzeitig für Oberflächenqualität und Implementierungsstabilität einsetzen wollen, lässt sich das in der bestehenden Repository-Praxis in vier Schichten umsetzen.

Schicht 1: Vertragliche Festlegung des Aufgabeneinstiegs

Vorgehen: Die Struktur eines Presets wie ui-master wiederverwenden.

Ziele:

• Den erlaubten Repository-Umfang begrenzen (targetRepositories)
• Die Befehlsquelle begrenzen (uiMasterCommandIds)
• Den Kontexteinstieg begrenzen (uiMasterDescription)

Nutzen: Bei jeder Zuweisung lässt sich nachvollziehen, „welche Eingabe vorlag und warum so geändert wurde“.

Schicht 2: Vereinheitlichung der Befehlssemantik

Vorgehen: Befehls-ID, Docs-Slug und Prelude-Template fest miteinander verbinden.

Ziele:

• Ein im Panel ausgewählter Befehl führt zur Dokumentation mit derselben ID
• /impeccable <command> im Prompt und die Dokumentation erklären dasselbe

Nutzen: Das versteckte Risiko „einheitliche Begriffe, aber unterschiedliches Verhalten“ wird verringert.

Schicht 3: Validierung der Inhaltsressourcen

Vorgehen: npm run validate als Gate vor jedem Commit verwenden.

Ziele:

• Keine fehlenden i18n-Schlüssel
• Befehlskatalog und Upstream-Struktur driften nicht auseinander
• Typen, Tests und Build laufen in einem Durchgang durch

Nutzen: Gelegentliche Inhaltsprobleme werden lokal vorverlagert.

Schicht 4: Standardisierung der Laufzeitumgebung für die Entwicklung

Vorgehen: Über static-sites-dev einheitlich starten und PORT_IMPECCABLE_SITE festlegen.

Ziele:

• Port-Konflikte bei der Zusammenarbeit im Team minimieren
• Den Weg für das gemeinsame Testen mehrerer Sites festlegen

Nutzen: Zeit beim Einrichten der Umgebung sparen, Probleme schneller im eigentlichen Code finden.

Praxis (Practice)

Schritt 1: impeccable-site initialisieren

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

Schritt 2: Lokale Entwicklung und Gesamtvalidierung

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

validate deckt i18n, catalog, typecheck, test und build in einem Durchgang ab.

Schritt 3: Ausführung in der einheitlichen Orchestrierung des Monorepos

Starten Sie vom Root-Verzeichnis des Monorepos aus über das System scripts/static-sites-dev.mjs und verwenden Sie das bereits definierte PORT_IMPECCABLE_SITE=36296.

Entscheidend ist in diesem Schritt nicht, dass es „irgendwie läuft“, sondern dass „alle es auf dieselbe Weise starten“.

Schritt 4: UI-Anfragen in befehlsbasierte Eingaben überführen

Im Task-Preset-Ablauf sollten Anforderungen vorzugsweise in diese Felder übersetzt werden:

• uiMasterDescription: Geschäftsziel
• uiMasterCommandIds: Befehle für diesen Durchlauf (z. B. craft, audit, polish)
• sceneKey: Szenenkontext

Erst danach beginnt die Änderungsphase. So wird verhindert, dass ein direktes Ändern der UI die Richtung verfehlt.

Schritt 5: Bestehende Lücken im Material klar benennen

Auf Grundlage des aktuellen Repository-Stands lässt sich Folgendes bestätigen:

• Die Site und die Validierungskette von impeccable-site sind umgesetzter Code.
• Die tiefe Verknüpfung von ui-master mit impeccable zeigt sich hauptsächlich in designs/task-preset-plugin-examples und in den Designdokumenten.

Wenn Sie die Aussage „im produktiven Backend vollständig aktiviert“ treffen wollen, reichen die aktuellen Belege nicht aus. Treffen Sie dieses Urteil also noch nicht.

HagiCode-Überblick

HagiCode ist eine Plattform, die Multi-Repository-Engineering, die Ausführung von KI-Aufgaben, Dokumentationsseiten und Werkzeugketten miteinander verbindet. Ihre Kernfähigkeit liegt nicht darin, dass sie einzelne Code „generieren kann“, sondern darin, Eingabebeschränkungen für Aufgaben, Ausführungskontext, Validierungsgates und die repositoryübergreifende Zusammenarbeit zu einer stabilen Pipeline zu verbinden. Typische Einsatzszenarien sind: strukturierte UI-Iterationen, repositoryübergreifende Funktionsabstimmung, spezifikationsgesteuerte Erstellung technischer Inhalte sowie automatisierte Auslieferung mit Qualitätsgates.

Fazit

Der eigentliche Wert von impeccable liegt nicht darin, dass es „einen schöneren Button vorschlägt“, sondern darin, dass die Optimierung der Oberfläche ingenieurmäßig betrieben wird. In der bestehenden Praxis von HagiCode geschieht das über vier Schritte: vertragliche Festlegung der Aufgaben, Vereinheitlichung der Befehlssemantik, Vorverlagerung der Inhaltsvalidierung und Standardisierung der Laufzeitumgebung. Wer diese Grundlagen zuerst stabil aufstellt, profitiert anschließend mehr und nachhaltiger von weiteren gestalterischen Verbesserungen.

Tags:

• impeccable
• frontend
• stability
• hagicode

Was ist MonoSpecs: Warum es eine Weiterentwicklung und Erweiterung von OpenSpec ist