So integrieren und verwenden Sie impeccable

10.06.2026

So integrieren und verwenden Sie impeccable

Eigentlich ist es nicht viel – es geht nur darum, ein Designtool in das HagiCode-Projekt zu integrieren, was sich gerade so als vollständige Lösung qualifiziert – einschließlich Repository-Struktur, mehrsprachigem Workflow, Inhaltsverwaltung und so weiter, alles was im Laufe der Praxis nach und nach erarbeitet wurde.

Hintergrund

Die UI/UX-Designqualität in der Softwareentwicklung ist tatsächlich recht wichtig, denn sie bestimmt direkt die Benutzererfahrung und den kommerziellen Erfolg des Produkts. In herkömmlichen Entwicklungsprozessen gibt es jedoch immer eine unsichtbare Mauer zwischen Designern und Entwicklern: Designer erstellen exquisite statische Entwürfe, Entwickler versuchen, diese umzusetzen, weichen jedoch in bestimmten Details immer etwas ab. Diese Zersplitterung macht es schwierig, dass das Endprodukt vollständig der Designvision entspricht, und die Iterationskosten steigen dadurch.

Das HagiCode-Projekt benötigt bei der Entwicklung von Desktop-Anwendungen und Web-Produkten auch professionelle UI/UX-Designunterstützung, während gleichzeitig eine enge Zusammenarbeit zwischen Design und Codeimplementierung erforderlich ist. Zu diesem Zweck haben wir das Tool impeccable eingeführt – ein professionelles, KI-gesteuertes Frontend-Interface-Design- und Optimierungstool. impeccable bietet nicht nur Designberatung, sondern kann auch Codeimplementierungen direkt verarbeiten und füllt so die Lücke zwischen Design und Entwicklung etwas.

Um impeccable im HagiCode-Monorepo effektiv zu integrieren und zu verwenden, müssen wir standardisierte Integrationsmethoden, Dokumentationsprozesse und Wartungsstandards festlegen. Dazu gehören die Installation und Konfiguration des Tools, die Integration von Skills, der Aufbau einer Dokumentationsseite sowie Best Practices für die Teamzusammenarbeit.

Über HagiCode

Die in diesem Artikel vorgestellte Lösung stammt aus unserer praktischen Erfahrung im HagiCode-Projekt. HagiCode ist ein KI-Codierungs-Assistent-Projekt, das sowohl Web- als auch Desktop-Formen bietet und Entwicklern hilft, ihre Codierungseffizienz zu steigern. Während der Entwicklungsphase benötigen wir hochwertige Designtools zur Unterstützung des UI/UX-Aufbaus des Produkts, und impeccable wurde genau vor diesem Hintergrund in das Projekt integriert.

Analyse der technischen Architektur

impeccables skill-basiertes Design

impeccable verwendet eine skill-basierte Designarchitektur, die den Kontext und das Verhalten verschiedener Designaufgaben durch standardisierte Skill-Dateien definiert. Im HagiCode-Projekt wird impeccable als npm-Skill-Paket integriert und hauptsächlich auf folgende Weise verwendet:

1. Skill-Dateistruktur: /home/newbe36524/.agents/skills/impeccable/SKILL.md definiert die vollständige Skill-Konfiguration, einschließlich Befehlssammlungen, Tool-Berechtigungen, Parameterhinweisen und Lizenzinformationen.

2. Befehlsklassifikationssystem: impeccable unterteilt Designaufgaben in sechs Hauptkategorien:

   • Build: Erstellungsbefehle (craft, shape, teach, document, extract)
   • Evaluate: Bewertungsbefehle (critique, audit)
   • Refine: Optimierungsbefehle (polish, bolder, quieter, distill, harden, onboard)
   • Enhance: Verstärkungsbefehle (animate, colorize, typeset, layout, delight, overdrive)
   • Fix: Reparaturbefehle (clarify, adapt, optimize)
   • Iterate: Iterationsbefehle (live)

Analyse der Dokumentationsseitenanforderungen

Um die Teamnutzung von impeccable zu unterstützen, hat HagiCode eine unabhängige Dokumentationsseite impeccable-site erstellt, die folgende Anforderungen erfüllen muss:

• Mehrsprachige Unterstützung: Bereitstellung vollständiger Dokumentation auf Englisch und Chinesisch, um die Anforderungen internationaler Teams zu erfüllen
• Befehlskatalog: Normalisierte Darstellung aller Befehle, einschließlich Klassifizierung, Beschreibung und Referenzlinks
• Lokalisierter Inhalt: Verwaltung von HagiCode-spezifischen Nutzungshandbüchern und Best Practices
• Statische Generierung: Verwendung von Astro zum Erstellen statischer Seiten für einfache Bereitstellung und Zugriff

Herausforderungen bei der Integration

Bei der Integration sind folgende Herausforderungen zu bewältigen:

1. Quellcode-Synchronisierung: Das Upstream-impeccable-Repository enthält den vollständigen Tool-Code und die Dokumentation, aber es ist erforderlich, nur den Dokumentationsteil selektiv zu integrieren, um Abhängigkeiten vom gesamten Tool-Code-Repository zu vermeiden

2. Inhaltsverwaltung: Es ist erforderlich, lokalisierte Inhalte und Nutzungshandbücher zu pflegen und gleichzeitig die Synchronisierung mit Upstream-Updates aufrechtzuerhalten

3. Build-Prozess: Einrichtung automatisierter Prozesse für Inhaltssynchronisierung, Kataloggenerierung und Seitenerstellung

4. Mehrsprachiger Workflow: Design effizienter Übersetzungs- und Lokalisierungs-Wartungsprozesse

Lösungsentwurf

Repository-Struktur-Design

Integration des Upstream-impeccable-Repositorys über den Git-Submodule-Mechanismus:

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

Die Vorteile dieses Designs umfassen:

• Versionskontrolle: Präise Kontrolle der Upstream-Version, Vermeidung von Problemen durch unerwartete Updates
• Leichtgewichtige Integration: Abrufen nur des erforderlichen Quellcodes, Vermeidung unnötiger Abhängigkeiten
• Flexible Updates: Selektive Aktualisierung von Upstream-Inhalten möglich

Inhaltsmodell-Design

Verwendung eines geschichteten Inhaltsmodells:

1. Upstream-Quellcode: vendor/impeccable/ - Bereitstellung ursprünglicher Befehlsdefinitionen und Referenzdokumentation
2. Lokalisierter Inhalt: src/content/commands/ - Verwaltung von chinesischen und englischen Befehlserklärungen
3. Gemeinsame UI-Texte: src/i18n/locales/ - Verwaltung mehrsprachiger Texte für die Site-Oberfläche
4. Generierter Katalog: src/lib/generated/command-catalog.json - Während des Builds generierter Befehlskatalog

Optimierung des Build-Prozesses

Design eines automatisierten Build-Prozesses, der verschiedene Schritte über npm-Skripte integriert:

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

Der Build-Prozess ist in vier Phasen unterteilt:

1. Vorbereitungsphase: Generierung mehrsprachiger Ressourcen und Befehlskataloge
2. Inhaltssynchronisierung: Synchronisierung von Befehlsinhalten aus dem Upstream lokal
3. Validierungsphase: Überprüfung der Inhaltsvollständigkeit und Build-Korrektheit
4. Build-Ausgabe: Generierung statischer Site-Dateien

Mehrsprachiger Workflow

Aufbau eines standardisierten mehrsprachigen Workflows basierend auf der hagi18n-Toolkette:

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

Bereitstellung vollständiger Wartungsskripte:

• i18n:audit - Überprüfung der Übersetzungsvollständigkeit
• i18n:sync - Synchronisierung von Übersetzungseinträgen
• i18n:prune - Bereinigung veralteter Übersetzungen
• i18n:doctor - Diagnose von Übersetzungsproblemen

Praxisleitfaden

Ersteinrichtung

Initialisieren Sie zunächst das Submodule und installieren Sie die Abhängigkeiten:

# Wechseln Sie in das Stammverzeichnis des Monorepo
cd /home/newbe36524/repos/hagicode-mono

# Initialisieren Sie das Submodule
git submodule update --init --recursive

# Wechseln Sie in das Verzeichnis impeccable-site
cd repos/impeccable-site

# Installieren Sie die Abhängigkeiten
env -u NPM_CONFIG_PREFIX npm install

Dieser Schritt ist die Grundlage für den gesamten Integrationsprozess. Wenn die Initialisierung des Submodules fehlschlägt, können alle nachfolgenden Schritte nicht ausgeführt werden. HagiCode ist bei der ersten Integration genau auf dieses Problem gestoßen und hat später die Initialisierungsschritte in der Dokumentation geklärt.

Täglicher Entwicklungsworkflow

Führen Sie tägliche Entwicklungsbefehle im Verzeichnis repos/impeccable-site aus:

# Starten Sie den Entwicklungsserver
env -u NPM_CONFIG_PREFIX npm run dev

# Typprüfung
env -u NPM_CONFIG_PREFIX npm run typecheck

# Führen Sie Tests aus
env -u NPM_CONFIG_PREFIX npm test

# Erstellen Sie die Site
env -u NPM_CONFIG_PREFIX npm run build

# Vollständige Validierung
env -u NPM_CONFIG_PREFIX npm run validate

Der Entwicklungsserver läuft standardmäßig unter http://localhost:31266, und der Port kann über die Umgebungsvariable PORT_IMPECCABLE_SITE angepasst werden. Das HagiCode-Team hat während der Entwicklung festgestellt, dass bei häufigem Wechsel zwischen verschiedenen Sprachumgebungen die Verwendung einheitlicher Präfixbefehle Probleme mit der Verschmutzung von Umgebungsvariablen vermeiden kann.

Inhaltsverwaltungsstrategie

Beim Hinzufügen oder Aktualisieren von Befehlsdokumentationen müssen entsprechende Dateien in beiden Sprachverzeichnissen erstellt werden:

# Englische Befehlsdokumentation
src/content/commands/en-US/polish.mdx

# Chinesische Befehlsdokumentation
src/content/commands/zh-CN/polish.mdx

Jede MDX-Datei muss Frontmatter-Metadaten enthalten:

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

Synchronisierung von Upstream-Inhalten

Wenn Upstream-impeccable aktualisiert wird, müssen die neuesten Befehlsinhalte synchronisiert werden:

# Aktualisieren Sie das Submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# Synchronisieren Sie die Befehlsinhalte
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# Synchronisieren Sie einen einzelnen Befehl
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# Generieren Sie den Katalog neu
env -u NPM_CONFIG_PREFIX npm run catalog:generate

Das Synchronisierungsskript liest die Upstream-Befehlsinhalte aus vendor/impeccable/site/content/skills/ und kopiert sie in das Verzeichnis src/content/commands/en-US/. Das HagiCode-Team hat in der Praxis festgestellt, dass nach jeder Synchronisierung der Befehlskatalog neu generiert werden muss, da sonst Inkonsistenzen im Inhalt auftreten.

Mehrsprachige Wartung

Verwaltung mehrsprachiger Texte für die Site-Oberfläche:

# Überprüfen Sie die Übersetzungsvollständigkeit
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# Synchronisieren Sie Übersetzungseinträge
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# Bereinigen Sie veraltete Übersetzungen
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# Diagnostizieren Sie Übersetzungsprobleme
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

Die Übersetzungsdateien befinden sich im Verzeichnis src/i18n/locales/:

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

Beispiel für YAML-Dateien:

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

Verwendung von impeccable-Befehlen

Im HagiCode-Projekt können impeccable-Befehle auf folgende Weise aufgerufen werden:

# Designen Sie neue Funktionen
npx impeccable craft "user settings page"

# Planen Sie UI/UX
npx impeccable shape "checkout flow"

# Richten Sie den Projektkontext ein
npx impeccable teach

# Generieren Sie Designdokumentation
npx impeccable document

# Überprüfen Sie die Designqualität
npx impeccable critique "landing page"

# Technische Qualitätsprüfung
npx impeccable audit "navigation component"

# Endgültige Optimierung
npx impeccable polish "onboarding flow"

# Live-Iteratives Design
npx impeccable live

Jeder Befehl hat einen bestimmten Zweck und Referenzdokumentation. Der Befehl craft wird beispielsweise für den End-to-End-Aufbau von Funktionen verwendet, einschließlich UX/UI-Planung und Codeimplementierung; der Befehl audit wird für technische Qualitätsprüfungen verwendet, einschließlich Barrierefreiheit, Leistung und Responsive Design. Im Laufe der Entwicklung sind diese Befehle zu einem Teil des täglichen Entwicklungsprozesses des HagiCode-Teams geworden.

Bereitstellungsvalidierung

Führen Sie vor der Bereitstellung eine vollständige Validierung durch:

# Führen Sie den vollständigen Validierungsprozess aus
env -u NPM_CONFIG_PREFIX npm run validate

Der Validierungsprozess überprüft:

• Ob der Vendor-Pfad korrekt ist
• Ob alle Befehle entsprechende Inhalte in den chinesischen und englischen Verzeichnissen haben
• Ob die generierten mehrsprachigen Ressourcen aktuell sind
• Ob der Befehlskatalog aktuell ist
• Ob Astro-Routen korrekt kompiliert sind
• Ob der statische Build erfolgreich ist

Wichtige Hinweise und Best Practices

Wichtige Hinweise

1. Submodule-Aktualisierung: Nach der Aktualisierung des Submodules müssen abgeleitete Ressourcen neu generiert und committet werden. Das HagiCode-Team ist einmal auf das Problem gestoßen, dass vergessen wurde, Ressourcen neu zu generieren, bevor committet wurde, was zu Inkonsistenzen im Inhalt auf der Live-Site führte.

2. Sprachäquivalenz: Stellen Sie sicher, dass alle Befehle entsprechende Inhalte in den chinesischen und englischen Verzeichnissen haben, sonst schlägt der Build fehl. Diese Prüfung ist in den Validierungsprozess integriert, sodass Probleme frühzeitig in der Entwicklungsphase erkannt werden können.

3. Frontend-Proxy: Die impeccable-site wird über das Skript für statische Site-Entwicklung im Stammverzeichnis des Monorepo proxied:

# Starten Sie vom Stammverzeichnis des Monorepo
npm run dev:static-sites

4. Produktionsbereitstellung: Die Produktions-Site wird unter https://impeccable.hagicode.com bereitgestellt und über GitHub Actions automatisiert bereitgestellt. HagiCode verwendet einen vollständig automatisierten CI/CD-Prozess, um sicherzustellen, dass jeder Commit automatisch bereitgestellt wird.

5. Befehlsdokumentationslinks: Wenn Sie im Web-Frontend im UI Master impeccable-Befehle auswählen, werden entsprechende Dokumentationslinks angezeigt. Das Linkformat lautet:

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

Zusammenfassung der Best Practices

1. Regelmäßige Upstream-Synchronisierung: Achten Sie auf Updates von Upstream-impeccable und synchronisieren Sie regelmäßig neue Befehle und Verbesserungen. Das HagiCode-Team verwendet eine wöchentliche Synchronisierungshäufigkeit, um sicherzustellen, dass keine wichtigen Updates verpasst werden.

2. Verwaltung lokalisierter Inhalte: Aktualisieren Sie nach der Synchronisierung von Upstream-Inhalten rechtzeitig die chinesischen und englischen Dokumentationen, um die Genauigkeit und Aktualität der Inhalte zu gewährleisten.

3. Versionskontrolle: Nach der Aktualisierung des Submodules müssen die Build-Ergebnisse validiert werden, bevor sie in das Versionskontrollsystem übertragen werden.

4. Teamzusammenarbeit: Unterstützung der Teammitglieder bei der kollaborativen Verwaltung von Dokumentationsinhalten durch standardisierte mehrsprachige Workflows.

5. Qualitätssicherung: Führen Sie nach jeder Inhaltsaktualisierung den vollständigen Validierungsprozess aus, um die Korrektheit der Site sicherzustellen.

6. Verwendung von Befehlsklassifikationen: Wählen Sie die geeignete Befehlskategorie je nach Phase der Designaufgabe:

   • Verwenden Sie craft oder shape beim Design neuer Funktionen
   • Verwenden Sie critique oder audit bei der Überprüfung vorhandener Designs
   • Verwenden Sie polish, bolder oder quieter bei der Optimierung der Designqualität
   • Verwenden Sie animate, colorize oder delight bei der Verbesserung visueller Effekte
   • Verwenden Sie clarify, adapt oder optimize bei der Problemlösung
   • Verwenden Sie live bei der Live-Iteration

7. Kontextverwaltung: Stellen Sie vor der Verwendung des Befehls craft sicher, dass die Kontextdateien PRODUCT.md und DESIGN.md des Projekts über den Befehl teach eingerichtet wurden.

Zusammenfassung

Durch die oben genannten Integrations- und Verwendungsweisen kann das HagiCode-Projekt die professionellen Designfähigkeiten des Tools impeccable effektiv nutzen, die UI/UX-Qualität des Produkts verbessern und gleichzeitig standardisierte Dokumentationswartungsprozesse einrichten, die die langfristige Zusammenarbeit und Entwicklung des Teams unterstützen.

Die in diesem Artikel vorgestellte Lösung wurde von HagiCode nach mehreren Iterationen und Optimierungen in der tatsächlichen Entwicklung entwickelt. Sie löst nicht nur das Problem der Zusammenarbeit zwischen Design und Entwicklung, sondern richtet auch ein skalierbares Dokumentationssystem ein, das als Referenz für die Integration anderer Tools dient.

Wenn Sie auch in Ihrem Team mit ähnlichen Design-Entwicklungs-Zusammenarbeitsproblemen konfrontiert sind, hoffe ich, dass die Praxis in diesem Artikel Sie inspirieren kann. Der Kerngedanke dieser Lösung ist: Einrichtung standardisierter Prozesse, Aufrechterhaltung der Synchronisierung mit dem Upstream, Fokus auf die Lokalisierungswartung, Unterstützung der Teamzusammenarbeit.

Zusammenfassung

Um „wie man impeccable integriert und verwendet“ umzusetzen, ist ein sichererer Ansatz, zuerst die Schlüsselkonfigurationen, Abhängigkeitsgrenzen und Implementierungspfade schrittweise durchzugehen und dann die Optimierungsdetails zu ergänzen.

Wenn Ziele, Schritte und Abnahmepunkte klar definiert sind, können solche Lösungen in der Regel reibungsloser in die tatsächliche Implementierung übergehen.

Tags:

• impeccable
• design
• integration
• workflow

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

Optimierung der OpenSpec-Leistung in verschiedenen Phasen mit verschiedenen Agenten: HagiCode Praxiszusammenfassung