impeccable を使ってフロントエンド UI の設計と実装の安定性を高めた方法

2026/07/04

impeccable を使ってフロントエンド UI の設計と実装の安定性を高めた方法

はじめに

UI を作るチームの多くは、同じ悩みを抱えています。デザイン言語は経験頼みで、インタラクションの細部は記憶頼みになりがちです。その結果、成果物は「一応動くが不安定」なものになりやすいのです。

HagiCode monorepo では、impeccable を「インスピレーションのためのツール」として使っているわけではありません。実行でき、検証でき、回帰テストもできる工程の流れに組み込んでいます。

• タスクの入口に構造化された制約（コマンド、シーン、リポジトリの範囲）がある
• サイトのコンテンツと上流のコマンド定義が自動的に揃う
• ローカル開発のポート、実行パラメータ、検証フローが固定されている

この記事では、リポジトリの既存の実装をもとに、Background、Analysis、Solution、Practice の4つに分けて説明します。

背景（Background）

現在のリポジトリのスナップショットで、impeccable に直接関係する主な箇所は次の3つです。

1. 静的サイトの実行オーケストレーション：scripts/static-sites-dev.mjs
2. impeccable のドキュメントサイト：repos/impeccable-site
3. UI task preset の契約例：designs/task-preset-plugin-examples/ui-master

このうち3つ目は設計上のサンプルであり、本番のバックエンド実行コードそのものではありません。ここを先に明確にしておかないと、「設計上の契約」を「公開済みの動作」と誤解してしまいます。

分析（Analysis）

1) 設計意図を先に構造化し、「自由な発想」によるブレを減らす

ui-master のバックエンド契約の例では、実行に入る前に依存関係と入力を固定しています。

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

要点は次のとおりです。

• skills:impeccable と cli:impeccable を事前に検証し、実行の途中で連鎖が切れていることに気づく事態を避けます。
• uiMasterCommandIds でコマンド形式の入力を必須にし、「説明は長いのに方向性が不明」という状態を防ぎます。
• sceneKey でシーンのキーを統一し、preset ごとに入力名を別々に発明しないようにします。

この構造が安定性にもたらす効果は明快です。失敗は前段で起こり、失敗の理由は説明でき、入力は再現可能になります。

2) コマンドカタログとドキュメントのルーティングを統一し、意味のずれを減らす

designs/task-preset-plugin-examples/ui-master/frontend/commands.json では、コマンドのグループ、ドキュメントのルーティングテンプレート、コマンドの 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}"
    }
  ]
}

これにより、「コマンドの実行」「ドキュメントの説明」「言語ごとのルーティング」が同じ ID 群を共有します。よくあるずれを防げます。

• ドキュメントでは A と呼んでいるのに、パネルでは B と表示される
• 中国語のページから英語の別のコマンドへリンクされている
• prompt の prelude と docs の slug が一致しない

3) サイトの実装で「コンテンツの正しさ」を検証可能な資産にする

repos/impeccable-site/package.json では、validate が品質ゲート全体をつないでいます。

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

また、catalog:check の背後にあるスクリプト（scripts/build-command-catalog.mjs）は、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(),
  };
}

こうした assert は地味ですが、安定性にとっては非常に重要です。ドキュメントに必須フィールドが欠けていることを公開後に知るより、ローカルや CI で確実に失敗させるほうがずっと良いのです。

4) 開発環境のポートと env を固定し、「自分の環境では動くのに他人の環境では動かない」を防ぐ

monorepo のルートスクリプト scripts/static-sites-dev.mjs では、impeccable が明示的にオーケストレーションされています。

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

テスト scripts/static-sites-dev.test.mjs も、これらの値（ポート、args、env、productionUrl）をアサートしています。

この「値を固定してテストする」やり方は派手さはありませんが、安定しています。

• ローカルの入口が統一される
• 障害調査の経路が固定される
• ドキュメントサイトへのリンクがずれにくくなる

解決（Solution）

impeccable を使って UI の品質 と 実装の安定性 を同時に高めたい場合、既存のリポジトリの実践に沿えば次の4つの層で構成できます。

第1層：タスクの入口を契約化する

進め方：ui-master のような preset の構造を再利用します。

目的：

• 変更を許可するリポジトリの範囲（targetRepositories）を限定する
• コマンドの供給元（uiMasterCommandIds）を限定する
• コンテキストの入口（uiMasterDescription）を限定する

効果：どの依頼でも、「入力が何で、なぜそのように変更したのか」を後から振り返れます。

第2層：コマンドの意味を統一する

進め方：コマンド ID、docs slug、prelude template の3点を結びつけます。

目的：

• パネルで選んだコマンドから、同じ ID のドキュメントへ移動できる
• prompt 内の /impeccable <command> とドキュメントの説明が一致する

効果：「用語は一致しているのに、動作は一致しない」という潜在的なリスクを減らせます。

第3層：コンテンツの検証を仕組み化する

進め方：npm run validate をコミット前のゲートとして徹底します。

目的：

• i18n のキーが欠けていない
• コマンドカタログと上流の構造がずれていない
• 型チェック、テスト、ビルドが一度に通る

効果：「たまに起きるコンテンツの問題」をローカルの段階で発見できます。

第4層：開発の実行環境を標準化する

進め方：static-sites-dev で一括起動し、PORT_IMPECCABLE_SITE を固定します。

目的：

• 複数人での協業時のポート競合を最小限にする
• 複数サイトを連携させて確認する経路を固定する

効果：環境の調整に費やす時間を減らし、問題をより速くコードそのものに絞り込めます。

実践（Practice）

Step 1：impeccable-site を初期化する

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

Step 2：ローカル開発と全体の検証

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

validate は i18n、catalog、typecheck、test、build をまとめて実行します。

Step 3：monorepo の統一オーケストレーションで実行する

monorepo のルートから scripts/static-sites-dev.mjs の仕組みを使い、定義済みの PORT_IMPECCABLE_SITE=36296 を再利用します。

このステップで重要なのは「起動できること」ではなく、「全員が同じ方法で起動すること」です。

Step 4：UI の依頼をコマンド形式の入力に変換する

task preset のフローでは、要件を次の形で確定させることを優先します。

• uiMasterDescription：ビジネス上の目標
• uiMasterCommandIds：今回使うコマンド（例：craft、audit、polish）
• sceneKey：シーンのコンテキスト

そのうえで変更の段階に進みます。こうすると、「UI を直接いじった結果、方向性がずれる」ことを減らせます。

Step 5：現時点の資料の不足を明確にする

現在のリポジトリのスナップショットから確認できるのは次のことです。

• impeccable-site のサイトと検証の仕組みは実装されたコードである。
• ui-master と impeccable の深い連携の契約は、主に designs/task-preset-plugin-examples と設計ドキュメントに記述されている。

「本番のバックエンドですべて有効化されている」と結論するには、現時点の証拠は不十分です。その判断はまだ下さないほうがよいでしょう。

HagiCode の紹介

HagiCode は、複数リポジトリのエンジニアリング、AI によるタスク実行、ドキュメントサイト、ツールチェーンを統合するプラットフォーム型のプロジェクトです。その核心は、単に「コードを生成できる」ことではありません。タスクの入力制約、実行コンテキスト、検証ゲート、リポジトリ横断の連携を一本の安定したパイプラインにまとめている点にあります。典型的な利用シーンは、構造化された UI の改善、複数リポジトリにまたがる機能の連携確認、規範に沿った技術コンテンツの制作、品質ゲート付きの自動化された納品などです。

まとめ

impeccable の本当の価値は、「より良いボタンを考えてくれること」ではなく、「UI の改善を工程として管理できるようにすること」にあります。HagiCode の現在の実践では、この取り組みを4つの動作で実現しています。タスクの契約化、コマンドの意味の統一、コンテンツ検証の前倒し、実行環境の標準化です。まずこれらの基盤を固めてから、より派手なデザインの強化に取り組むほうが、効果が大きく、長く続けられます。

Tags:

• impeccable
• frontend
• stability
• hagicode

MonoSpecs とは何か：なぜそれは OpenSpec のさらなるアップグレードと拡張であると言えるのか