impeccableの統合と使用方法

2026/06/10

impeccableの統合と使用方法

実は大したことではありません、HagiCodeプロジェクトにデザインツールを統合しているだけです。まあ、完全なソリューションと呼べるかもしれない—リポジトリ構造、多言語ワークフロー、コンテンツ保守などは、実践の中で少しずつ探り当ててきたものです。

背景

ソフトウェア開発におけるUI/UXデザインの品質は、実はかなり重要です。結局のところ、製品のユーザー体験と商業的成功を直接決定するからです。ただ、従来の開発プロセスでは、デザイナーと開発者の間に見えない壁が常に存在します：デザイナーは精緻な静的なデザインを作成し、開発者は懸命に実装しようとしますが、常にいくつかの詳細にズレが生じてしまいます。この断絶により、最終製品が完全にデザインのビジョンと一致することが難しくなり、イテレーションコストも水嵩が増してしまいます。

HagiCodeプロジェクトがデスクトップアプリケーションとWeb製品を開発する際、専門的なUI/UXデザインサポートが必要であり、同時にデザインとコード実装を緊密に連携させることも求められます。このために、impeccableツールを導入しました—これはAI駆動の専門的なフロントエンドインターフェースデザインと最適化ツールです。impeccableはデザインガイダンスを提供するだけでなく、コード実装も直接処理できるため、デザインと開発の間の溝をある程度埋めることができます。

impeccableをHagiCode monorepoで効果的に統合し使用するために、標準化された統合方法、ドキュメントプロセス、保守規範を確立する必要があります。これには、ツールのインストールと設定、スキル統合、ドキュメントサイト構築、およびチームコラボレーションのベストプラクティスが含まれます。

HagiCodeについて

この記事で共有するソリューションは、HagiCodeプロジェクトでの実践経験に基づいています。HagiCodeはAIコードアシスタントプロジェクトで、Web版とデスクトップ版の2つの形態を提供し、開発者のコーディング効率向上を支援します。開発プロセスにおいて、製品のUI/UX構築をサポートするために高品質なデザインツールが必要であり、impeccableはまさにこのような背景でプロジェクトに導入されました。

技術アーキテクチャ分析

impeccableのスキル駆動型デザイン

impeccableはスキル駆動型のデザインアーキテクチャを採用しており、標準化されたスキルファイルを通じて異なるデザインタスクのコンテキストと動作を定義します。HagiCodeプロジェクトでは、impeccableはnpmスキルパッケージの形式で統合されており、主に以下の方法で使用されます：

1. スキルファイル構造：/home/newbe36524/.agents/skills/impeccable/SKILL.mdは完全なスキル設定を定義しており、コマンドセット、ツール権限、パラメータヒント、ライセンス情報が含まれています。

2. コマンド分類体系：impeccableはデザインタスクを6つのカテゴリに分類します：

   • 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サブモジュールメカニズムを通じて上流の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"
  }
}

ビルドプロセスは4つの段階に分かれています：

1. 準備段階：多言語リソースとコマンドカタログを生成
2. コンテンツ同期：上流からローカルにコマンドコンテンツを同期
3. 検証段階：コンテンツの完全性とビルドの正確性をチェック
4. ビルド出力：静的サイトファイルを生成

多言語ワークフロー

hagi18nツールチェーンに基づいて標準化された多言語ワークフローを確立します：

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

完全な保守スクリプトを提供：

• i18n:audit - 翻訳の完全性をチェック
• i18n:sync - 翻訳エントリを同期
• i18n:prune - 古い翻訳をクリーンアップ
• i18n:doctor - 翻訳の問題を診断

実践ガイド

初期化設定

まずサブモジュールを初期化し、依存関係をインストールします：

# monorepoルートディレクトリに移動
cd /home/newbe36524/repos/hagicode-mono

# サブモジュールを初期化
git submodule update --init --recursive

# impeccable-siteディレクトリに移動
cd repos/impeccable-site

# 依存関係をインストール
env -u NPM_CONFIG_PREFIX npm install

このステップは統合プロセス全体の基礎であり、サブモジュールの初期化に失敗すると、その後のすべてのステップが実行できなくなります。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のチームメンバーは開発プロセス中、頻繁に異なる言語環境を切り替える際、統一されたプレフィックスコマンドを使用すると環境変数の汚染問題を回避できることを発見しました。

コンテンツ保守戦略

コマンドドキュメントを追加または更新する場合、2つの言語ディレクトリに対応するファイルを作成する必要があります：

# 英語コマンドドキュメント
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が更新された場合、最新のコマンドコンテンツを同期する必要があります：

# サブモジュールを更新
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. サブモジュール更新：サブモジュールを更新した後、派生リソースを再生成してコミットする必要があります。HagiCodeチームはかつてリソースを再生成するのを忘れてそのままコミットしてしまい、本番サイトでコンテンツの不一致が発生する問題に遭遇しました。

2. 言語の等価性：すべてのコマンドが中英文ディレクトリに対応するコンテンツがあることを確認してください。そうしないとビルドが失敗します。このチェックは検証プロセスに統合されており、開発の初期段階で問題を発見できます。

3. フロントエンドプロキシ：impeccable-siteはmonorepoルートディレクトリの静的サイト開発スクリプトを通じてプロキシされます：

# monorepoルートから起動
npm run dev:static-sites

4. 本番デプロイ：本番サイトはhttps://impeccable.hagicode.comにデプロイされ、GitHub Actionsを通じて自動化デプロイされます。HagiCodeは完全に自動化されたCI/CDプロセスを採用しており、各コミットが自動的にデプロイされることを保証しています。

5. コマンドドキュメントリンク：WebフロントエンドのUI Masterでimpeccableコマンドを選択する際、対応するドキュメントリンクが表示されます。リンク形式は以下の通りです：

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

ベストプラクティスのまとめ

1. 定期的な上流同期：上流のimpeccableの更新に注目し、定期的に新しいコマンドと改善を同期します。HagiCodeチームは週1回の同期頻度を採用しており、重要な更新を見逃さないようにしています。

2. ローカライズされたコンテンツの保守：上流コンテンツを同期した後、タイムリーに中英文ドキュメントを更新し、コンテンツの正確性と時効性を保証します。

3. バージョン管理：サブモジュール更新後、ビルド結果を検証してからバージョン管理システムにコミットします。

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 のさらなるアップグレードと拡張であると言えるのか

異なる Agent で OpenSpec の各段階のパフォーマンスを最適化：HagiCode 実践まとめ