drift-detection

ドリフトの検出

デザインシステムにおけるドリフトを特定し、分類するためのスキルです。ドリフトとは、デザインシステムの意図と、それを利用する製品での実際の実装との間に蓄積した差異です。各検出結果の重要度評価、発生源の分類、推奨される対応を記載したドリフトレポートを生成します。

始める前に：参照先を確認する

このスキルのフロントマターにある references: のすべてのパスが、この SKILL.md からの相対パスとして存在することを確認してください。見つからないパスがある場合は、インストールが不完全です。通常、フラット化インストーラー（例：npx skills install）がリポジトリのルートにある knowledge-notes/ ディレクトリを取り除いたことが原因です。そこで作業を中止し、1-INSTALL.md に記載された方法で再インストールして、インストールルートから verify-install.sh を実行するようユーザーに伝えてください。ユーザーが明示的に続行を指示した場合に限り、参照先なしで作業を進め、その場合は出力にパックの参照資料を使用せずに生成したことを記載してください。

コンテキスト

ドリフトは、利用されているデザインシステムにとって通常の状態です。問題は、システムにドリフトが生じたかどうかではありません。ドリフトはすでに生じています。重要なのは、そのドリフトが意図的か、どの程度深刻か、そして拡大しているかどうかです。

すべてのドリフトが悪いわけではありません。確立されたパターンに対して製品チームが意図的に文書化された例外を設けた場合、それは設計上の判断です。一方、製品チームが気付かないまま、わずかに異なる間隔でデザインシステムのコンポーネントを再実装した場合、それは保守コストを生み出します。この違いは重要です。意図的なドリフトはコントリビューションにつながる可能性がありますが、意図しないドリフトは修正し、根本原因にも対処する必要があるため、対応が異なります。

このスキルはドリフトの種類を見分け、それぞれの検出結果を適切な対応へと導きます。

---

設定

.ds-ops-config.yml がある場合は、設定と定期実行に関するナレッジノート（../../knowledge-notes/configuration-and-recurring.md）に従って、設定の読み込み、連携機能のフォールバック、定期実行を行ってください。このスキルでは、次の設定を読み込みます。

• severity.* — ドリフト検出結果の重要度の上書き設定
• system.styling — トークンドリフトの検出方法（CSS vars、SCSS、Tailwind、CSS-in-JS）を事前に選択します
• integrations.* — ドリフトの比較データ（以下を参照）
• recurring.* — ドリフトの傾向（定期実行ワークフローを参照）

連携機能からの自動取得

Figma MCP（integrations.figma.enabled: true）：

• integrations.figma.file_key にある公開ライブラリからコンポーネントの仕様を読み取ります
• ビジュアルドリフトと API ドリフトの検出における、デザイン側の参照情報として使用します
• Figma のコンポーネントプロパティとコード内のコンポーネントの props を比較し、手動で仕様を記述せずに API ドリフトを検出します

GitHub（integrations.github.enabled: true）：

• integrations.github.repo を検索し、ドリフトを示すコードパターンを探します（ナレッジノートの GitHub に関する注意事項を参照）。
  • デザインシステムのパッケージ外にあるハードコードされた色の値
  • ローカルで再実装されたコンポーネント（システムのソース外で使用されているコンポーネント名）
  • デザイントークンのプロパティに CSS の !important を使用したトークンの上書き
• 最近の PR を取得し、デザインシステムのパッケージ外で変更されたコンポーネントを特定します
• 各利用側が package.json で宣言し、ロックファイルで解決するデザインシステムのバージョンを、最新の公開バージョン（npm view [package] version）と比較して、バージョンの遅れを検出します。コミット履歴からは、利用側がどのバージョンを実行しているかはわかりません

Chromatic（integrations.chromatic.enabled: true）：

• ビジュアル差分データを取得します。DS のリリースサイクル外で視覚的な変更が承認されたコンポーネントは、ビジュアルドリフトの可能性があります
• 変更の承認率が高い場合、チームがドリフトを修正せずに受け入れている可能性があります

定期的なワークフロー

設定と定期実行に関するノートの定期実行手順に従います。このスキル固有の内容は次のとおりです。

• 継続的なドリフト（2 サイクル以上にわたって発生）：重大度を引き上げます。
• **分類の変化：**分類が変わったドリフトにフラグを付けます。たとえば、偶発的なドリフトが意図的な逸脱に変わった場合です。
• レポートに「ドリフトの傾向」セクションを追加します：
  • ドリフトの総数：増加／横ばい／減少
  • ドリフトの発生速度：新たなドリフトの蓄積と解消の速さを比較します。
  • 分類の傾向：システム上の不足（E）と偶発的なドリフト（C）のどちらが増えているかを示します。

ステップ 1：範囲を定義する

次の点を確認するか、質問します（自動取得ですでに回答済みの質問は省略します）：

• 何を評価しますか？（特定の製品、特定のコンポーネント群、特定のトークン範囲、またはシステム全体）
• 比較に利用できるソースは何ですか？（Figma ファイル、コードベース、ドキュメント、Storybook、各種形式のトークンファイル — JSON、CSS カスタムプロパティ、SCSS 変数、Tailwind 設定）
• すでにドリフトが疑われている領域はありますか？
• 問題としてフラグを付けるのではなく、記録しておくべき意図的な逸脱はありますか？

範囲を具体的にするほど、レポートの実用性が高まります。「システム全体」を対象にドリフトを検出すると傾向は明らかになりますが、優先順位付けに役立つ情報が限られた、長い指摘リストが作成されます。特定の製品やコンポーネントのカテゴリに範囲を絞ると、より実用的な結果が得られます。

ドリフトには比較対象が必要です。 手元にあるコードがデザインシステム自体のリポジトリだけなら、そこからドリフトしたものはありません。その場合は作業を中止して、その旨を伝え、該当するスキルを案内します：システム独自のコンポーネント内の生の値には token-compliance、ライブラリ内の重複や不足には component-audit、仕様に照らして単一のコンポーネントを確認するには design-to-code-check を使用します。続行する前に、利用側の製品（パス、リポジトリ、または製品の Figma ファイル）を提示してもらいます。

**小規模システムに関する注意（コンポーネントが 5 個未満の場合）：**この規模のシステムでは、全体を対象にします。サンプリングの必要はありません。小規模システムではドリフトの傾向が異なります。チームは通常、より小規模で足並みもそろっているため、ドリフトは偶発的に発生する可能性が低く、意図的な逸脱（分類 A）またはシステム上の不足（分類 E）である可能性が高くなります。ただし、どちらの場合もステップ 4 で求める証拠が必要です。出力は、完全なドリフトレポートではなく、コンポーネントごとのチェックリストに簡略化します。すべてのコンポーネントでドリフトが見つからない場合は、その結果を明記し、レビューの頻度を提案します。

ステップ 2：参照元を確定する

ドリフトは常に何かを基準とします。参照元として使用する信頼できる情報源を確認します：

• デザインシステムの Figma ライブラリ
• 特定バージョンで公開されたコンポーネントパッケージ
• 各コンポーネントの文書化された仕様
• 上記すべて（これらの間に不整合があれば、それ自体がドリフトの兆候です）

明確な単一の信頼できる情報源がない場合、それ自体が指摘事項となるため、レポートの冒頭に記載します。

ステップ 3：ドリフトの発生箇所を特定する

次の 4 つの観点から評価します：

視覚的なドリフト

デザインシステムの参照元と比べた、コンポーネントまたはパターンの視覚的な扱いの違いです。間隔、色（特にトークンを使用していない値）、タイポグラフィ、角丸、シャドウ、アイコンの使い方が含まれます。

各発生箇所について、コンポーネントまたはパターンの名前を示し、視覚的な違いを説明し、意図的か偶発的かを記します。

振る舞いのドリフト

設計・文書化されたコンポーネントの振る舞いと比べた、インタラクティブな動作の違いです。状態遷移、アニメーション、タイミング、キーボード操作、フォーカス管理が含まれます。

振る舞いのドリフトは、直接テストしないと検出が難しいことが多い一方、アクセシビリティの低下を含むため、最も大きなリスクを伴います。

API の乖離

デザインシステムで公開されている API と、異なる props、異なる prop 名、または異なる prop のセマンティクスで実装されたコンポーネントです。チームがシステムから利用するのではなく、コンポーネントをローカルで実装した場合や、システムのコンポーネントが存在する前にローカル版を構築し、その後移行されなかった場合に最もよく見られます。

トークンの乖離

デザイントークンを参照すべき箇所で生の値が使われていること、セマンティックな意図と矛盾するローカルのトークン上書き、実装間で一貫性なく使われているトークン名です。

ファイル単位で生の値を検索するのは token-compliance の役割であり、スタイリング方法に関するルールとポジティブコントロールも備えています。ここで再実装しないでください。そのプロダクトの token-compliance レポートがある場合は、その違反テーブルをトークンの観点として取り込んでください。ない場合は、先に利用側のプロダクトで token-compliance を実行してから続けてください。このスキルで追加されるのは、それぞれの違反を利用側とシステムの関係から読み解くことです。システムトークンの解決後の値と一致する生の値は、通常クラス C または D（名前ではなく数値を入力した）です。システム内のどの値とも一致しない生の値は、クラス A または E であり、ステップ 4 の証拠ルールが必要です。システムトークンのローカル上書き（プロダクト内で再定義された --color-action-primary: #...、トークンによって値が決まるプロパティへの !important）は token-compliance の対象外です。そのため、ポジティブコントロールを使って、ここで検索してください。

ステップ 4：各乖離の事例を分類する

対応を決める前に、すべての指摘事項を分類してください。クラス A、C、D はチームの意図に関する主張であり、コードだけで判明することはほとんどありません。証拠ルールが満たされた場合に限りクラスを割り当ててください。そうでない場合は、指摘事項を 未分類 — チームへの確認が必要 とし、分類に必要な情報を記載してください。

分類 A：意図的な相違 プロダクトチームが、既知の理由からシステムと異なる実装にすることを意図的に決定しました。これは適切な場合もあります（システムがこのコンテキストに対応していない場合）。また、コントリビューション候補となる場合もあります（そのニーズは実在し、システムに取り入れるべき場合）。 必要な証拠： その決定を記録したコードコメント、ADR、PR の説明、またはチームの発言。

分類 B：バージョンの遅れ 実装がデザインシステムの古いバージョンと一致しています。システムは更新されていますが、プロダクトは更新されていません。これは間違いではなく、通常のエントロピーですが、対処しないまま放置すると移行負担が積み上がります。 必要な証拠： 利用側がインストールしているバージョン（ロックファイル）が最新の公開バージョンより古く、乖離している動作がインストール済みバージョンと一致していること。

分類 C：意図しない乖離 意図せず実装がシステムと異なる状態になっています。システムのバージョンがまだ利用できない時点でコンポーネントをローカルに実装し、その後システムのバージョンに移行しなかったことが、最も一般的な原因です。 必要な証拠： 乖離が意図的に選択されたものではないと示す情報。たとえば、ローカル版がシステム版より古いこと（Git の履歴）と、決定を記録したものがないこと、またはチームによる確認です。

分類 D：誤解 実装がドキュメントや仕様の読み違いを反映しています。利用側はシステムを正しく使用していると思っており、実際にはそうでないことを把握していませんでした。 必要な証拠： 使用方法がドキュメントのもっともらしい解釈と一致していること（曖昧な箇所を引用してください）、またはチームによる確認です。

分類 E：システムの不足 プロダクトチームが必要とするものをシステムが提供していないために、乖離が生じています。異なる実装は間違いではなく、デザインシステムの不足に対するプロダクトチームの解決策です。 必要な証拠： 利用側が実行しているバージョンに、ニーズを満たすシステムコンポーネントもトークンもないこと。

未分類 — チームへの確認が必要 証拠からは、上記のどのクラスにも分類できません。重要度と、分類につながる質問（「CheckoutCard の 12px のパディングは意図的な選択でしたか？」）を添えて指摘事項を報告してください。推測しないでください。

Step 4a: ドリフトの影響度の重み付け

まず基本の重大度を決めてから、重み付けします。

• 🔴 Critical — 重要な経路でアクセシビリティまたは動作に関するリグレッションが発生している（チェックアウト中にフォーカスが失われる、サインイン時にエラーが通知されない）
• 🟠 High — それ以外の場所でアクセシビリティまたは動作に関するリグレッションが発生している、またはトークンのドリフトによってテーマ設定が崩れている（テーマ設定されたプロダクトで色がハードコードされている）
• 🟡 Medium — ユーザーや開発者が気づく視覚的または API の乖離があるが、機能への影響はない
• ⚪ Low — 単一の箇所における見た目上の乖離、またはユーザーに表示されないユーティリティのドリフト

次に、コンポーネントの重要度に応じて重み付けします。

重要な経路のコンポーネント（コアナビゲーション、認証、チェックアウト、主要なデータ入力） — ここでのドリフトは自動的に重大度が 1 段階上がります。チェックアウトコンポーネントでの Medium の指摘は High になります。

トラフィックの多いコンポーネント（ボタン、フォーム入力、カード、モーダル） — ここでのドリフトは最も多くのユーザーに影響します。重み付けは評価どおりに保ちますが、影響範囲を明記します。

ユーティリティコンポーネント（レイアウトラッパー、スペーシングヘルパー、アイコンコンテナ） — ここでのドリフトはリスクが低くなります。ユーザーに表示されないコンポーネントであれば、Medium の指摘を Low に引き下げることがあります。

分類に応じた推奨対応

各ドリフト事例を分類した後、適切な対応に振り分けます。

分類	主な対応	次に実行するスキル
A — 意図的な乖離	意思決定記録として文書化する	decision-record
B — バージョンの遅れ	リリースの移行ガイドを案内する。差分が機械的に変更可能な場合は、codemod を提案する	codemod-generator、またはトークン名の変更には token-migration コマンド
C — 偶発的なドリフト	実装を修正し、再発防止に失敗したドキュメントを見直す	design-to-code-check
D — 誤解	ドキュメントを更新し、影響を受けるチームに通知する	change-communication
E — システム上の課題	コントリビューションのワークフローに振り分ける	contribution-workflow
未分類	分類に必要な質問をチームに尋ねる	—

Step 4b: バージョンの遅れをグループ化する

B に分類したドリフトは、変更を導入したリリースごとに事例をグループ化します（利用側にインストールされているバージョンから最新バージョンまでの、システムの CHANGELOG または git タグを確認します）。各グループについて、根拠に基づいて次の 3 点を伝えます。利用側で影響を受けるファイルの数（数えてください）、変更が機械的なもの（codemod で変更できる名前の変更または prop の入れ替え）か構造的なものか、そしてリリースに移行ガイドが含まれていたかどうかです。移行ガイドのない破壊的変更を含むリリースは、それ自体がガバナンス上の指摘事項です。別途明記してください。所要時間や T シャツサイズで見積もらないでください。チームが計画を立てるうえで必要なのは、ファイル数と機械的か構造的かの判定です。

Step 4c: システム間のドリフト（複数のシステムが対象の場合のみ）

ユーザーが 2 つ以上のデザインシステム（ブランドシステム、プラットフォームシステム）を対象にしている場合は、それらも相互に比較します。一致しなくなった共通プリミティブ、同じセマンティック名が異なる意図に対応しているケース、同じ名前のコンポーネントで API が異なるケースを確認します。対象が 1 つのシステムのみの場合はこの手順を省略し、Scope に省略したことを記載します。

Step 5: ドリフトレポートを作成する

見出しとなる一文から始めます。例：「ドリフトは中程度で、その大半は偶発的です。3 つのコンポーネントがシステムから乖離しており、そのうち 2 つはチームがシステムのバージョンの存在を知らなかったようです。全体像を以下に示します。」

---

ドリフト検出レポート

日付： [date] 対象： [what was assessed] 参照元： [what the assessment was compared against] 評価方法： [direct inspection / reported / mixed]

---

概要

ドリフトの全体像はどうなっていますか？システムのドリフトは管理された形で進んでいますか、それとも積み重なっていますか？最も重要な指摘事項は何ですか？コンプライアンスレポートを書くのではなく、同僚に報告するような形で記述してください。

---

ドリフトの指摘事項

各指摘事項について：

ID	場所	寸法	分類	重大度	説明	推奨アクション
DF-01	[リポジトリのパスと行番号、または Figma のノード ID、およびコンポーネント]	[視覚／動作／API／トークン]	[A～E／未分類]	🔴／🟠／🟡／⚪	[具体的な説明：システムの値と利用側の値]	[具体的なアクション]

場所はラベルではなく、根拠です。読者が開けるファイルと行番号、または Figma のノードを記載してください。場所の記載がない指摘事項は疑いにすぎないため、分類を確認する質問とともに「未分類」リストに記載します。

重大度の基準： 🔴 致命的 · 🟠 高 · 🟡 中 · ⚪ 低（ステップ 4a の基準を参照）

---

分類別の指摘事項

意図的な相違（A） 指摘事項を列挙してください。それぞれについて、コントリビューション候補か、承認済みの例外かを記載してください。承認済みの例外の場合は、決定記録として文書化してください。

バージョンの遅れ（B） 指摘事項を列挙してください。コンポーネントまたはトークンセットごとにまとめてください。移行スプリントで大半に対処できるか、それとも対象が分散しすぎていて、一斉移行には適さないかを明らかにしてください。

偶発的なドリフト（C） 指摘事項を列挙してください。意図しないものであるため、修正の優先度は最も高くなります。プロダクトチームが把握すべき事項です。

誤解（D） 指摘事項を列挙してください。これらは、ドキュメントまたはコミュニケーションの不足を示しています。指摘事項を修正し、誤解を防げなかったドキュメントやオンボーディングを見直してください。

システムの不足（E） 指摘事項を列挙してください。これらはコントリビューション候補です。同じ不足が複数のプロダクトで見られる場合、システムへの追加を提案する根拠が強まります。コントリビューションのワークフローを相互参照してください。

未分類 — チームへの確認が必要 分類を確認する質問とともに指摘事項を列挙してください。

---

根本原因のパターン

個々の指摘事項から一歩引いて、パターンを特定してください。

• システム上の問題を示唆する、繰り返し発生するドリフトの種類はありますか？
• 指摘事項に一貫して登場する特定のチームやプロダクトはありますか？
• 他よりもドリフトしやすい特定のコンポーネントやトークンはありますか？

根本原因のパターンは、個々の指摘事項よりも実行可能な対応につながります。根本原因に対処すれば将来のドリフトを防げますが、個々の指摘事項への対処では現状の修正にとどまります。

---

推奨アクション

優先順位順のリスト：

1. 重大度が「致命的」および「高」の指摘事項：分類にかかわらず、最初に対処します
2. システムの不足に関する指摘事項：コントリビューションのワークフローに回します
3. バージョンの遅れに関する指摘事項：移行スプリントを予定するか、次のリリースサイクルに組み込みます
4. 誤解に関する指摘事項：ドキュメントを更新し、影響を受けるチームに通知します
5. 意図的な相違：まだ記録されていない例外を文書化します
6. 未分類の指摘事項：未解決の質問を担当チームに提示します

---

対象範囲

• 調査対象： [実際に確認したリポジトリ、パッケージ、Figma ファイル、バージョン]
• 未調査： [アクセスできず、したがってコメント対象外としたプロダクトや情報源]
• 「該当なし」の確認方法： [例：トークンドリフト検索の陽性対照 — レポートに不在の主張がない場合は省略]
• 前提： [検証せず、前提として扱った事項]

最後に、以下の締めくくりの注記を記載してください。

---

ステップ 6：ビジュアルの差異比較（Figma Console MCP が利用できる場合）

Southleft の Figma Console MCP が接続されている場合（figma_capture_screenshot と figma_get_component_for_development のツールが利用可能か確認してください）、デザイン側の視覚的な証拠を追加して差異レポートを充実させます。

デザインの参照画像を取得する： figma_capture_screenshot を使用して、差異がある各コンポーネントの Figma 上での現在の状態をキャプチャします。これはプラグインの exportAsync API を使用してライブ状態をキャプチャするもので、キャッシュされたクラウドレンダーではありません。視覚的な比較において、これがデザイン側の正確な状態を示します。

デザイン仕様を取得する： figma_get_component_for_development を使用して、レンダリング画像とともに開発向けに最適化されたデザインデータを取得します。これは引き続きデザイン側の情報であり、実装そのものではなく、実装プロパティに対応する形式の仕様を提供します。実装側については、存在する場合は Storybook または Chromatic のスナップショットを使用するか、コードがレンダリングする内容を説明してください。

レポート内のビジュアル差分： ビジュアルまたは API の差異に関する各指摘（分類を問わず）には、実装のスナップショット、またはコードがレンダリングする内容の説明とともに Figma のスクリーンショットを含めてください。これにより、プロパティの不一致を文章で説明するだけでなく、読者が差異を視覚的に把握できます。

標準の Figma MCP が接続されている場合（読み取り専用）： REST API 経由でスクリーンショットを取得できますが、現在のライブ状態ではなく、最後に公開されたクラウド上の状態が反映されます。この制限を明記してください。Figma ファイルに未公開の変更がある場合、スクリーンショットに最新のデザイン意図が反映されていない可能性があります。

---

締めくくりの注記（すべてのレポートに含める）

レポートの最後に次の内容を記載してください。

コンテキストに関する注記： この分析では、実装がシステムと異なる箇所を特定しますが、その理由までは常に判断できるとは限りません。分類システム（意図的、偶発的、バージョンの遅れ、誤解、システムの不足）は出発点です。分類に誤りがあればお知らせください。修正内容を反映することで、今後の差異チェックの精度が高まります。目標は、修正が必要な差異と、記録しておくべき差異を見分けることです。

---

品質チェック

• 各指摘に、説明だけでなく分類と推奨アクションがある
• 各指摘に、読者が開ける場所（ファイルと行、または Figma ノード）が記載されている
• トークンの次元に関する指摘は、別途検索するのではなく、token-compliance の表に基づいており、レポートにはその ID が記載されている
• 対象となるプロダクトが範囲に含まれていない場合、リダイレクトを示して処理が停止されている
• 重大度の評価は一律に割り当てず、具体的な影響に基づいて根拠が示されている
• 根本原因のパターンに関するセクションがあり、個別の指摘リストを超える情報が含まれている
• システムの不足に関する指摘はミスと区別されている。真に存在するシステムの不足を埋めるために逸脱したプロダクトチームを、誤ったことをしたかのように扱ってはならない
• 修正すべき差異と、許容された逸脱として記録すべき差異が区別されている
• ビジュアル比較をキャプチャした場合、各指摘に Figma の参照スクリーンショットが含まれている
• A、C、D の分類にはすべて、それぞれのルールで求められる証拠が記載されている。それ以外は未分類とする
• Scope ブロックと、意図的な逸脱に関する締めくくりの注記が含まれている