デザインシステム更新を支援するCLIツール・MCPサーバ開発

ogp

はじめに
本記事の要点
背景と課題
解決アプローチ
eclair-analyzerとは
活用例と効果
技術実装
- 技術スタック
- 実装のポイント
まとめ

この記事は enechain Advent Calendar 2025 の7日目の記事です。

はじめに

enechainに業務委託として参画しているエンジニアの@konatsu_pです。主にデザインシステムの開発・運用を担当しています。

enechainは、日本最大級のエネルギー卸取引マーケットプレイスを運営するスタートアップです。ソフトウェアエンジニアとして、日々プロダクトを通じてエネルギー市場に貢献しています。

社内には10を超えるプロダクトが存在しており、各プロダクト共通で利用されるデザインシステムがあります。このデザインシステムはéClair Design Systemという名前です。

詳細は以下の記事をご覧ください。

https://techblog.enechain.com/entry/design-system-2024

本記事の要点

デザインシステムのアップデートにおいて「影響範囲の調査に時間がかかる」「変更内容が把握しづらい」という課題が存在
これを解決するeclair-analyzer（CLIツール・MCPサーバ）を開発し、アップデート時の影響調査を効率化
バージョン間の変更分析とコンポーネント利用箇所の可視化により、プロダクトへの影響範囲の迅速な把握が可能に
MCPサーバとして提供することで、ClaudeなどのAIと対話しながらの分析が可能に

背景と課題

デザインシステムの現状

éClair Design Systemはスピード感のある開発を重視しており、頻繁にアップデートが行われています。デザインコンポーネントの見た目の変更など、比較的大きな変更が入ることも珍しくありません。

そのため、プロダクト側でデザインシステムをアップデートする際、最新バージョンとの差分が大きくなっている場合があります。リリースノートやセマンティックバージョニングも運用していますが、それでもアップデートにはコストがかかります。

アップデートが面倒で放置されると、さらに上げづらくなるという負のサイクルが発生しがちです。

デザインシステム利用者の多様化

ここ数年で組織が大きくなり、フロントエンドを専門としないエンジニアもプロダクト開発でデザインシステムに触れる機会が増えてきました。

利用者全員がデザインシステムに詳しいわけではないため、アップデートのハードルが上がっています。

アップデートにおける具体的な課題

上記の背景から、具体的には以下のような課題がありました。

プロダクトチーム側の課題：

どのような変更が入ったのかわからない
意図しない挙動の変更が含まれていることがある
自分たちのプロダクトに関係のない変更や軽微な変更のみの場合、優先度が上がらない
- 機能改善のほうが優先されやすい
QAへの影響範囲の調査も必要になる

デザインシステムチーム側の課題：

最新バージョンに追従してもらえない
複数のバージョンをサポートし続けなければならない

デザインシステムの改善がプロダクトチームにとっては「対応コスト」として映り、アップデート自体が歓迎されない状況になっていました。

解決アプローチ

これらの課題を解決するため、以下の方針でツールを開発することにしました。

実現したいこと：

現在のバージョンとの差分がわかる
- どのコンポーネントが変更されたのか
- Breaking Changes（破壊的変更）はあるのか
プロダクトへの影響範囲がわかる
- どのページやコンポーネントにアップデートの影響があるか
- 自分たちのプロダクトに関係のある変更なのか
簡単に、できれば自動でアップデートできる
- 自動修正ツールの作成やAIの活用など、選択肢はいくつか考えられる

このようなツールをデザインシステム側で提供できれば、アップデートのハードルを下げられると考えました。

そこで、eclair-analyzerを開発しました。

eclair-analyzerとは

eclair-analyzerは、éClair Design SystemのアップデートをサポートするCLIツール・MCPサーバです。

デザインシステムの変更管理とコンポーネント利用状況を分析するTypeScript製ツールで、アップデート時の影響調査やプロジェクト（各プロダクトのコードベース）でのコンポーネント利用状況の把握を効率化します。

主な機能

eclair-analyzerは、大きく分けて2つの機能を提供します。

1. Usage Analysis：プロジェクトでのコンポーネント利用状況分析

対象のプロジェクト内で、デザインシステムのコンポーネントがどのように使われているかを分析します。

主なユースケース：

コンポーネントの利用箇所の特定
利用頻度の把握
具体的な利用コードの確認

実行例（CLI）：

usage_list_used_components：利用中のコンポーネント一覧と統計を取得します

$ eclair usage list

{
  "projectName": "style_guide",
  "package": "@enechain/ecloud-designsystem",
  "totalComponents": 34,
  "components": [
    { "name": "Accordion", "usageCount": 2, "fileCount": 2 },
    { "name": "AccordionButton", "usageCount": 1, "fileCount": 1 },
    { "name": "Box", "usageCount": 6, "fileCount": 4 },
    { "name": "Button", "usageCount": 1, "fileCount": 1 },
    { "name": "FlexTableHeader", "usageCount": 8, "fileCount": 5 },
    ...
  ]
}

2. History Analysis：バージョン間の変更分析

デザインシステムのGit履歴を解析し、バージョン間でどのような変更があったかを追跡します。

主なユースケース：

マイグレーション前の影響調査
破壊的変更の検出
コンポーネントの変更履歴の追跡

実行例（CLI）：

history_get_affected_components：バージョン間で変更があったコンポーネントと影響範囲を取得します

$ eclair history affected v0.11.14 v0.11.19

{
  "fromVersion": "@enechain/ecloud-designsystem@0.11.14",
  "toVersion": "@enechain/ecloud-designsystem@0.11.19",
  "customComponents": [
    {
      "name": "BaseButton",
      "status": "modified",
      "modificationReason": "direct",
      "usedBy": ["Button", "ButtonProps", "ContractButton", "DangerButton", ...]
    },
    {
      "name": "Button",
      "status": "modified",
      "modificationReason": "re-export",
      "usedBy": ["ArrowButton", "ConfirmModal", "DangerButton", ...]
    },
    {
      "name": "UploadArea",
      "status": "modified",
      "modificationReason": "direct",
      "usedBy": ["UploadAreaProps"]
    }
  ],
  "summary": {
    "custom": { "added": 0, "modified": 5, "deleted": 0 },
    "external": { "added": 0, "modified": 0, "deleted": 0 }
  },
  "totalCount": 5
}

提供しているTools

eclair-analyzerは、CLIツール・MCPサーバのToolsとして、以下の機能を提供しています。

プロジェクト分析（Usage Analysis）

現在のプロジェクトでのコンポーネント利用状況を分析します。

Tool	説明
`usage_list_used_components`	利用中のコンポーネント一覧と統計
`usage_show_component_usage`	単一コンポーネントの詳細な利用箇所
`usage_show_components_usage`	複数コンポーネントの詳細な利用箇所（最大10件）
`usage_get_project_info`	プロジェクトの基本情報

マイグレーション分析（History Analysis）

デザインシステムのバージョン間の変更と影響を分析します。

主要機能

Tool	説明
`history_get_affected_components`	バージョン間で変更があったコンポーネントと影響範囲
`history_get_component_diff`	コンポーネントの詳細な差分
`history_list_versions`	利用可能なバージョン一覧
`history_get_changelog`	バージョン間の変更履歴

詳細情報

Tool	説明
`history_get_design_system_info`	デザインシステムの基本情報
`history_list_components`	特定バージョンのコンポーネント一覧
`history_get_component_history`	コンポーネントのコミット履歴
`history_get_component_snapshot`	特定バージョンでのコンポーネントの状態
`history_get_dependency_changes`	package.jsonの依存関係の変更

活用例と効果

ここでは、eclair-analyzerを使用した実際のバージョンアップ作業の例を紹介します。

実施概要

あるプロダクトにおいて、Claude Codeとeclair-analyzerを利用し、デザインシステムのバージョンアップ（v0.11.14 → v0.11.19）を実施しました。

アップデート実施の流れ

1. バージョン情報と差分の調査

01-work-plan

まず、Claude Codeに「@enechain/ecloud-designsystemのバージョンを最新にしたい。eclair-analyzer-mcpを使って最新との差分を調査して」と依頼しました。すると、以下のような作業計画が自動的に立案されました。

現在のバージョン確認：pnpm listにより現在インストールされているバージョンを確認
最新バージョン確認：history_list_versionsにより利用可能なバージョン一覧を取得
差分調査：history_get_affected_componentsにより現在のバージョンと最新バージョン間の変更を調査
利用状況確認：usage_list_used_componentsによりプロジェクト内で使用しているコンポーネントを確認し、影響範囲を特定

02-version-info

調査の結果、以下の情報が得られました。

現在のバージョン：0.11.14
最新バージョン：0.11.19
使用コンポーネント数：93個

2. 影響範囲の特定

03-component-usage

バージョン間の差分調査により、変更があったコンポーネントとその利用箇所が明らかになりました。

SideMenuLayoutMenuItem（10箇所で使用）
- BottomMenu.tsx：共通設定メニュー、ヘルプセンターメニュー
- TopMenu.tsx：スポット市場入札、時間前市場取引、JEPX設定など
- 変更内容：as propの追加（v0.11.18）→ 既存コードへの影響なし
UploadArea（1箇所で使用）
- CsvUploadField.tsx：CSVファイルアップロード機能
- 変更内容：Invalidパターンの追加（v0.11.17）→ 既存コードへの影響なし
Button（1箇所で使用）
- OrderButton.tsx：注文ボタン
- 変更内容：BaseButtonの内部変更（re-export）→ 既存コードへの影響なし

3. アップデート可否の判断

04-impact-analysis

分析結果から、以下のことがわかりました。

破壊的変更なし：すべて後方互換性のある変更（機能追加・バグ修正）
影響を受ける可能性があるコンポーネント：
- SideMenuLayoutMenuItem（10箇所で使用）→ as prop追加は後方互換
- UploadArea（1箇所で使用）→ Invalidパターン追加は後方互換
推奨事項：アイコンも同時に更新を推奨（@enechain/ecloud-iconsを0.3.13へ）

すべて後方互換性のある変更のため、コード修正なしでアップデート可能と判断しました。

4. アップデートの実行と検証

05-verification-result

package.jsonの更新、依存関係のインストール、Lint・TypeScriptの型チェックを経て、アップデートが完了しました。

Lint（ESLint、Prettier、tsc）：成功
TypeScript型チェック：成功（turbo経由で実行済み）
アップデート完了：@enechain/ecloud-designsystem 0.11.14 → 0.11.19

効果と改善点

このツールの導入により、以下のような効果がありました。

作業時間の大幅な削減

従来は、リリースノートを確認し、各コンポーネントの変更を手動で追跡し、プロジェクト内の利用箇所を検索する必要がありました。eclair-analyzerを使用することで、これらの調査が数分で完了するようになりました。

影響範囲の可視化

変更のあったコンポーネントについて、実際にプロジェクトで使用されているか、どこで使われているかを一目で把握できるため、QA範囲の特定が容易になりました。

安心感のあるアップデート判断

破壊的変更の有無や後方互換性について、コードレベルでの確認が自動化されたため、アップデートの可否を自信を持って判断できるようになりました。

AIとの協調による効率化

MCPサーバとして提供しているため、Claude Codeが自律的に必要な情報を取得し、分析・判断まで行えるようになりました。

技術実装

技術スタック

言語：TypeScript
実行環境：Node.js
主要ライブラリ：
- Model Context Protocol SDK：MCPサーバー開発用の公式SDK
- ts-morph：TypeScript Compiler APIのラッパー
- tar-stream：ストリーミングtarパーサー／ジェネレーター
- Commander.js：Node.js CLIフレームワーク

実装のポイント

Usage Analysis

TypeScript Compiler APIによるAST解析と正規表現を組み合わせて、プロジェクト内のコンポーネント利用状況を正確に検出します。JSXコンポーネントの使用、関数呼び出し、型参照など、さまざまなパターンに対応しています。

History Analysis

デザインシステムのGit履歴を解析してバージョン間の変更を追跡します。

当初の実装では、すべてのファイルをAST解析し、Git操作もファイル単位で行っていました。そのため、バージョン間の差分が大きいと分析に時間がかかるという課題がありました。以下の最適化により、高速な分析を実現しました。

Smart AST Analysis：ファイル内容を正規表現で事前チェックし、複雑なパターン（export * from、動的インポートなど）が検出された場合のみASTで解析。シンプルなファイルは正規表現で高速処理
Git Batch Processing：git archiveを使用して複数ファイルを一括取得し、ファイルごとのGit操作を削減

MCPサーバ対応

CLIだけでなく、MCPサーバとしても提供しています。これにより、ClaudeなどのAIアシスタントと対話しながら、バージョン間の差分確認や影響範囲の調査が可能になります。

まとめ

デザインシステムのアップデートにおける「影響範囲の調査に時間がかかる」「変更内容が把握しづらい」という課題に対し、eclair-analyzerというCLIツール・MCPサーバを開発しました。

バージョン間の変更分析とコンポーネント利用箇所の可視化により、プロダクトへの影響範囲を迅速に把握できるようになりました。また、MCPサーバとして提供することで、AIと対話しながらマイグレーション計画を立案することも可能になりました。

現在は実際のプロダクトで試用を進めており、得られたフィードバックをもとに継続的な改善をしています。このツールを通じて、各プロダクトチームがより安心してデザインシステムをバージョンアップできる環境を提供し、アップデートにおける負のサイクルを解消することを目指しています。

明日は @okpさんによる「Tech×Bizの言語ギャップを漫画で埋めた話」です。ご期待ください！

enechainでは、日本のエネルギー業界をテクノロジーの力で変革する仲間を募集しています。まずは気軽にカジュアル面談で話を聞いていただくだけで構いません。ご興味ある方はぜひTech Recruit Portalからご応募ください！

tech.enechain.com herp.careers