Как интегрировать и использовать impeccable

10 июн. 2026 г.

Как интегрировать и использовать impeccable

В целом, ничего особенного — просто интеграция инструмента дизайна в проект HagiCode, можно считать более-менее полным решением — включая структуру репозитория, многоязычный рабочий процесс, поддержку контента — всё это выработано на практике.

Контекст

Говоря о качестве UI/UX-дизайна в разработке программного обеспечения, на самом деле это довольно важно, ведь напрямую определяет пользовательский опыт и коммерческий успех продукта. Однако в традиционных процессах разработки между дизайнерами и разработчиками всегда существует невидимый барьер: дизайнеры создают качественные статичные макеты, разработчики стараются их реализовать, но в некоторых деталях всегда есть расхождения. Такое разделение затрудняет полное соответствие конечного продукта дизайнерскому видению, а стоимость итераций пропорционально возрастает.

Когда HagiCode разрабатывает настольные и веб-приложения, ему также нужна профессиональная поддержка UI/UX-дизайна, при этом требуется тесная координация между дизайном и реализацией кода. Для этого команда внедрила impeccable — профессиональный AI-инструмент для дизайна и оптимизации фронтенд-интерфейсов. Impeccable не только предлагает дизайн-направления, но и напрямую обрабатывает реализацию кода, частично заполняя разрыв между дизайном и разработкой.

Чтобы эффективно интегрировать и использовать impeccable в монорепозитории HagiCode, нужно создать стандартные способы интеграции, документационные процессы и спецификации поддержки. Сюда входят установка и настройка инструментов, интеграция навыков, построение документационных сайтов и лучшие практики командного взаимодействия.

О HagiCode

Решение, представленное в этой статье, основано на нашем практическом опыте в проекте HagiCode. HagiCode — это проект AI-помощника по кодированию, предлагающий веб- и десктопные версии, помогая разработчикам повысить эффективность кодирования. В процессе разработки нам требуются качественные инструменты дизайна для поддержки UI/UX-строительства продукта, и именно в таком контексте был внедрён impeccable.

Анализ технической архитектуры

Направляемый навыками дизайн impeccable

impeccable применяет архитектуру дизайна на основе навыков, определяя контекст и поведение разных дизайн-задач через стандартизованные файлы навыков. В проекте HagiCode impeccable интегрируется как пакет npm-навыков, в основном используемый следующим образом:

1. Структура файлов навыков：/home/newbe36524/.agents/skills/impeccable/SKILL.md определяет полную конфигурацию навыков, включая набор команд, разрешения инструментов, подсказки параметров и информацию о лицензировании.

2. Система классификации команд：impeccable разделяет дизайн-задачи на шесть основных категорий:

   • Build：Команды сборки（craft、shape、teach、document、extract）
   • Evaluate：Команды оценки（critique、audit）
   • Refine：Команды оптимизации（polish、bolder、quieter、distill、harden、onboard）
   • Enhance：Команды усиления（animate、colorize、typeset、layout、delight、overdrive）
   • Fix：Команды исправления（clarify、adapt、optimize）
   • Iterate：Команды итерации（live）

Анализ требований к документационному сайту

Чтобы поддержать командное использование impeccable, HagiCode создал независимый документационный сайт impeccable-site, который должен удовлетворять следующим требованиям:

• Многоязычная поддержка：Предоставляет полную документацию на английском и китайском языках, удовлетворяя потребности интернационализованной команды
• Каталог команд：Унифицированное отображение всех команд, включая классификацию, описания и справочные ссылки
• Локализованный контент：Поддержка руководств по использованию и лучших практик, специфичных для HagiCode
• Статическая генерация：Использует Astro для создания статического сайта, удобного для развертывания и доступа

Вызовы интеграции

В процессе интеграции возникли следующие проблемы:

1. Синхронизация исходного кода：Восходящий репозиторий impeccable содержит полный код инструмента и документацию, но нужно избирательно интегрировать только документацию, избегая зависимости от всего кодового хранилища

2. Поддержка контента：Нужно поддерживать синхронизацию с восходящим репозиторием, одновременно сохраняя локализованный контент и пользовательские руководства

3. Процесс сборки：Создание автоматизированных процессов синхронизации контента, генерации каталогов и сборки сайта

4. Многоязычный рабочий процесс：Эффективный процесс перевода и локализационной поддержки

Проектирование решения

Проектирование структуры репозитория

Через механизм Git submodule интегрировать восходящий репозиторий impeccable:

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

Преимущества этой архитектуры включают:

• Контроль версий：Можно точно контролировать версию восходящего репозитория, избегая проблем, вызванных случайными обновлениями
• Лёгкая интеграция：Извлекается только необходимый исходный код, избегая введения ненужных зависимостей
• Гибкость обновлений：Можно избирательно обновлять контент восходящего репозитория

Проектирование модели контента

Принята слоистая модель контента:

1. Исходный код восходящего репозитория：vendor/impeccable/ - Предоставляет исходные определения команд и справочную документацию
2. Локализованный контент：src/content/commands/ - Поддержка описаний команд на английском и китайском языках
3. Общий текст UI：src/i18n/locales/ - Управление многоязычным текстом интерфейса сайта
4. Генерируемый каталог：src/lib/generated/command-catalog.json - Каталог команд, генерируемый при сборке

Оптимизация процесса сборки

Создать автоматизированный процесс сборки, объединить каждый этап через 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"
  }
}

Процесс сборки состоит из четырёх этапов:

1. Этап подготовки：Генерация многоязычных ресурсов и каталога команд
2. Синхронизация контента：Синхронизация командного контента из восходящего репозитория в локальный
3. Этап проверки：Проверка целостности контента и корректности сборки
4. Вывод сборки：Генерация файлов статического сайта

Многоязычный рабочий процесс

На основе цепочки инструментов hagi18n создаётся стандартизированный многоязычный рабочий процесс:

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

Предоставляется полный набор скриптов поддержки:

• i18n:audit - Проверка целостности перевода
• i18n:sync - Синхронизация записей перевода
• i18n:prune - Очистка устаревших переводов
• i18n:doctor - Диагностика проблем перевода

Практическое руководство

Настройка инициализации

Сначала инициализируйте submodule и установите зависимости:

# Войдите в корневой каталог монорепозитория
cd /home/newbe36524/repos/hagicode-mono

# Инициализируйте submodule
git submodule update --init --recursive

# Войдите в каталог impeccable-site
cd repos/impeccable-site

# Установите зависимости
env -u NPM_CONFIG_PREFIX npm install

Этот шаг — основа всего процесса интеграции. Если инициализация submodule не удаётся, последующие этапы не могут быть выполнены. При первой интеграции HagiCode столкнулся с этой проблемой, поэтому позже в документации были уточнены шаги инициализации.

Повседневный процесс разработки

В каталоге repos/impeccable-site выполняйте команды повседневного разработки:

# Запустите сервер разработки
env -u NPM_CONFIG_PREFIX npm run dev

# Проверка типов
env -u NPM_CONFIG_PREFIX npm run typecheck

# Запустите тесты
env -u NPM_CONFIG_PREFIX npm test

# Соберите сайт
env -u NPM_CONFIG_PREFIX npm run build

# Полная проверка
env -u NPM_CONFIG_PREFIX npm run validate

Сервер разработки по умолчанию работает на http://localhost:31266, порт можно настроить через переменную окружения PORT_IMPECCABLE_SITE. В процессе разработки участники команды HagiCode обнаружили, что при частом переключении между разными языковыми средами использование единых префиксных команд помогает избежать проблем с загрязнением переменных окружения.

Стратегия поддержки контента

При добавлении или обновлении документации команд нужно создать соответствующие файлы в двух языковых директориях:

# Документация команды на английском языке
src/content/commands/en-US/polish.mdx

# Документация команды на китайском языке
src/content/commands/zh-CN/polish.mdx

Каждый MDX файл должен содержать метаданные 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"
---

Синхронизация контента восходящего репозитория

Когда восходящий репозиторий impeccable обновляется, нужно синхронизировать последний командный контент:

# Обновите submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# Синхронизируйте командный контент
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# Синхронизируйте одну команду
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# Снова сгенерируйте каталог
env -u NPM_CONFIG_PREFIX npm run catalog:generate

Скрипт синхронизации считывает восходящий командный контент из vendor/impeccable/site/content/skills/ и копирует его в директорию src/content/commands/en-US/. На практике команда HagiCode обнаружила, что после каждой синхронизации нужно повторно генерировать командный каталог, иначе возникнет проблема несогласованности контента.

Многоязычная поддержка

Поддержка многоязычного текста интерфейса сайта:

# Проверьте целостность перевода
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# Синхронизируйте записи перевода
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# Очистите устаревшие переводы
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# Диагностируйте проблемы перевода
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

Файлы переводов находятся в директории src/i18n/locales/:

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

Пример 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: "相关命令"

Использование команд impeccable

В проекте HagiCode команды impeccable могут вызываться следующими способами:

# Спроектируйте новую функцию
npx impeccable craft "user settings page"

# Планируйте UI/UX
npx impeccable shape "checkout flow"

# Установите контекст проекта
npx impeccable teach

# Сгенерируйте дизайн-документацию
npx impeccable document

# Проверьте качество дизайна
npx impeccable critique "landing page"

# Проверка технического качества
npx impeccable audit "navigation component"

# Финальная оптимизация
npx impeccable polish "onboarding flow"

# Итерация дизайна в реальном времени
npx impeccable live

Каждая команда имеет своё назначение и справочную документацию. Например, команда craft используется для построения функций сквозным способом, включая UX/UI-планирование и реализацию кода; команда audit применяется для проверки технического качества, включая доступность, производительность и адаптивный дизайн. В процессе разработки команды HagiCode эти команды стали частью повседневного рабочего процесса разработки.

Проверка развертывания

Перед развертыванием выполните полную проверку:

# Запустите полный процесс проверки
env -u NPM_CONFIG_PREFIX npm run validate

Процесс проверки проверяет:

• верность пути vendor
• все команды имеют соответствующий контент в директориях на китайском и английском языках
• сгенерированные многоязычные ресурсы актуальны
• командный каталог актуален
• Astro маршруты компилируются корректно
• статический вывод успешно собирается

Важные замечания и лучшие практики

Важные замечания

1. Обновление submodule：После обновления submodule нужно повторно генерировать производные ресурсы и зафиксировать изменения. Команда HagiCode однажды столкнулась с ситуацией, когда забыли повторно генерировать ресурсы и сразу отправили коммит, что привело к несогласованности контента на онлайн-сайте.

2. Языковая эквивалентность：Убедитесь, что все команды имеют соответствующий контент в директориях на китайском и английском языках, иначе сборка не удастся. Эта проверка уже интегрирована в процесс проверки, что позволяет выявить проблемы на ранних этапах разработки.

3. Фронтенд-прокси：impeccable-site проксируется через скрипт разработки статических сайтов в корне монорепозитория:

# Запустите из корневого каталога монорепозитория
npm run dev:static-sites

4. Производственное развертывание：Производственный сайт развертывается на https://impeccable.hagicode.com и автоматически разворачивается через GitHub Actions. HagiCode использует полностью автоматизированный CI/CD процесс, обеспечивая автоматическое развертывание каждого коммита.

5. Ссылки на документацию команд：При выборе impeccable команды в UI Master веб-фронта отображается соответствующая документационная ссылка в формате:

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

Итог лучших практик

1. Регулярная синхронизация восходящего репозитория：Следите за обновлениями восходящего репозитория impeccable, регулярно синхронизируйте новые команды и улучшения. Команда HagiCode использует еженедельную частоту синхронизации, чтобы не пропустить важные обновления.

2. Поддержка локализованного контента：После синхронизации контента восходящего репозитория своевременно обновляйте документацию на китайском и английском языках, обеспечивая точность и актуальность контента.

3. Контроль версий：После обновления submodule нужно проверить результаты сборки и затем отправить в систему контроля версий.

4. Командное сотрудничество：Через стандартизированный многоязычный рабочий процесс поддерживать командное сотрудничество по обслуживанию контента документации.

5. Обеспечение качества：После каждого обновления контента запустить полный процесс проверки, чтобы убедиться в корректности сайта.

6. Классифицированное использование команд：В зависимости от этапа дизайн-задачи выбирать подходящую категорию команд:

   • При проектировании новых функций использовать craft или shape
   • При проверке существующего дизайна использовать critique или audit
   • При оптимизации дизайна использовать polish, bolder или quieter
   • При усилении визуальных эффектов использовать animate, colorize или delight
   • При исправлении проблем использовать clarify, adapt или optimize
   • При итерации в реальном времени использовать live

7. Управление контекстом：Перед использованием команды craft убедитесь, что через команду teach были установлены контекстные файлы проекта PRODUCT.md и DESIGN.md.

Заключение

Благодаря вышеуказанным способам интеграции и использования проект HagiCode может эффективно использовать профессиональные возможности дизайна инструмента impeccable, улучшать качество UI/UX продукта, а также создавать стандартизированный процесс поддержки документации, поддерживать долгосрочное командное сотрудничество и развитие.

Решение, представленное в этой статье, выработано проектом HagiCode в ходе фактической разработки через несколько итераций оптимизации. Оно не только решает проблемы сотрудничества между дизайном и разработкой, но и создаёт масштабируемую систему документации, предоставляя справочник для интеграции других инструментов.

Если вы также сталкиваетесь с похожими проблемами сотрудничества дизайн-разработка в команде, надеюсь, практический опыт этой статьи принесёт вам вдохновение. Основная идея этого решения: создавать стандартизированные процессы, сохранять синхронизацию с восходящим репозиторием, уделять внимание поддержке локализации, поддерживать командное сотрудничество.

Заключение

Относительно “как интегрировать и использовать impeccable”, более надёжный подход продвижения — сначала постепенно отработать ключевые конфигурации, границы зависимостей и пути внедрения, затем дополнить оптимизированные детали.

Когда цели, шаги и точки приёма чётко определены, такие решения обычно могут более плавно перейти к фактической поставке.

Tags:

• impeccable
• design
• integration
• workflow

MonoSpecs: что это и почему это является дальнейшим обновлением и расширением OpenSpec

Оптимизация эффективности каждого этапа OpenSpec с помощью разных агентов: практическое резюме HagiCode