extract

extractスキルの概要

extractでできること

extract スキルは、繰り返し登場するUIコードを、再利用可能なデザインシステム資産へ整理するのに役立ちます。具体的には、共通コンポーネント、design token、標準化されたパターンへ落とし込む作業に向いています。すでにプロダクトUIが存在し、重複やばらつきをより体系的な形にまとめたいチーム向けであり、汎用的なブレスト用プロンプトを探している人向けではありません。

extractが特に向いている人

extract は、フロントエンドエンジニア、デザインシステムの運用担当、画面や機能をまたいだズレを整理したいプロダクトチームに特に有効です。とくに、同じ button、card、form pattern、spacing scale、color usage が複数箇所に現れていて、そろそろ統一すべきだと感じている場合にフィットします。

extractスキルが実際に解決する仕事

extractスキルの価値は、単に「重複を見つける」ことではありません。エージェントに対して次の流れを強く促します。

• まず既存の design system や shared UI layer を特定する
• extractすべき価値のあるパターンを見極める
• 早すぎる抽象化を避ける
• 繰り返しコードを、計画を伴って再利用可能な仕組みに移行する

そのため、普通の「このUIをリファクタして」というプロンプトより実務向きです。特に extract for Design Systems の用途では、命名、構造、移行リスクが重要になるため、その差がはっきり出ます。

このextractスキルが違う理由

このスキルには、明確なワークフローがあります。現状の仕組みを把握し、extract候補を見つけ、それが本当にシステム化に値するかを判断し、そのうえで慎重にextractと移行を進めます。とくに強い差別化ポイントは、design system が存在しない場合に、勝手に作り始める前に確認を求めるという明確なガードレールがあることです。これにより、リポジトリに合わない恣意的な component architecture をAIが作ってしまう、よくある失敗を減らせます。

extractを導入すべきタイミング

主な目的が、繰り返し出てくるUIパターンを既存または今後整備したい design system に統合することなら、extract を導入する価値があります。単発の component を素早く1つ作れればよいだけなら、直接プロンプトで十分な場合もあります。extractの導入判断が合理的なのは、速度だけでなく、一貫性・再利用性・移行品質を重視するときです。

extractスキルの使い方

extractスキルをインストールする

実用的なインストールコマンドは次のとおりです。

npx skills add https://github.com/pbakaus/impeccable --skill extract

このスキルは .claude/skills/extract にあるため、使い始める段階でリポジトリ全体をスキャンする必要はありません。

まず読むべきファイル

最初に確認するのは以下です。

• SKILL.md

このケースでは、SKILL.md が source of truth です。リポジトリ上の根拠として追加の script、rule、reference folder は確認されていないため、実際に使えるガイダンスの大半はここに集約されています。

想定されている呼び出し方を把握する

このスキルは user-invocable として定義されており、引数ヒントは次の形です。

[target]

実際には、リクエスト時に対象範囲を具体的に指定する必要があります。たとえば次のような単位です。

• feature folder
• page
• component群
• 繰り返しパターンがあるUI surface

「improve our design system」のような曖昧な依頼よりも、「run extract on src/features/billing and identify reusable form and card patterns.」のように対象を絞った依頼のほうが、はるかに強い結果につながります。

extractには広い理想論ではなく、対象を渡す

extractスキルは、対象が適切に区切られているときに最も力を発揮します。良いターゲットは、たいてい次のいずれかに当てはまります。

• UIの重複がある directory
• 目に見える不整合がある product area
• hard-coded style を token に移す migration
• variant 化すべき、似た component 群

こうした指定が有効なのは、このスキルが抽象化を机上で発明するためではなく、実際に再利用の余地がある箇所を見極める設計になっているからです。

あいまいな目的を、強いextractプロンプトに変える

弱いプロンプト:

• “Use extract on our app.”

より強いプロンプト:

• “Use extract on src/app/settings and src/components/settings. Find repeated controls, hard-coded spacing and color values, and any patterns already close to our shared UI conventions. Propose what should become a shared component or token, what should stay local, and a safe migration order.”

これが機能する理由:

• 対象が明確
• component の抽出と token の抽出を分けて依頼している
• keep-local の判断を求めており、過剰な抽象化を防げる
• 実リポジトリで重要な migration sequence まで求めている

どんな入力が出力品質を大きく左右するか

extract usage の品質を上げたいなら、次の情報を添えるのが有効です。

• 既存の design system または shared UI folder の場所
• React、Tailwind、CSS Modules、styled-components などの framework / styling stack
• すでに使っている naming convention
• token source、theme file、style dictionary の有無
• proposal-only がよいのか、実際の code edit まで求めるのか

これらがなくても、エージェントは繰り返し自体は見つけられます。ただし、extract計画が既存アーキテクチャと噛み合わない可能性は高くなります。

リポジトリ本来のワークフローに沿って使う

このスキルのワークフローはシンプルですが重要です。

1. design system を見つける
2. 繰り返しパターンと hard-coded values を特定する
3. extractが正当化されるか判断する
4. system を拡張しながら extractする
5. consumer を移行する

この「extract前に価値を判断する」段階が重要です。スキル自体も、すべてをextractすべきではないとはっきり警告しています。1回か2回しか使われていないパターンは、まだ shared system に入れる段階ではないかもしれません。

extractは単なる重複排除ではなく、Design Systemsのために使う

extract for Design Systems の最もよい使い方は、重複コードを機械的に削除することではありません。system layer に置くべきものと、feature-local のままにすべきコードを切り分けることです。調査結果を次の分類で出すよう依頼すると有効です。

• reusable components
• design tokens
• composition patterns
• その場に残すべき local-only code

こうしておくと、実際にレビューして採用できる形になります。

いきなり編集させる前に、まず提案を出してもらう

導入時の実践的な進め方は次のとおりです。

1. extract に findings と candidates を出してもらう
2. naming、ownership、migration scope をレビューする
3. その後で extract の実装を依頼する
4. 小さな単位で移行する

特に現状の design system が未完成な場合、アプリ全体に対して最初から即編集を求めるより、この進め方のほうが安全です。

うまく機能しやすいプロンプトの型

次のような依頼が使いやすいです。

“Use extract on [target]. First locate our existing design system or shared UI directory and summarize its conventions. Then identify repeated components, inconsistent variants, and hard-coded visual values worth turning into tokens. For each candidate, say whether it should be extracted now, deferred, or kept local. After that, propose a migration plan with the lowest-risk order.”

この形はスキル本来のワークフローにかなり忠実で、汎用的な refactor 依頼より高品質な出力になりやすいです。

extract実行前に決めておきたい制約

extractスキルを使う前に、次を決めておくとよいです。

• エージェントは新しい shared component を作ってよいのか、それとも提案だけにするのか
• token 導入まで今やるのか、それとも component の統合だけにするのか
• strict backward compatibility が必要か
• import や file location の変更を許容するか

これらの制約によって推奨内容は大きく変わります。計画なのか、実装なのか、移行なのかをスキルが把握しているほど、実用性は高まります。

extractスキル FAQ

extractは普通のrefactorプロンプトより良い？

多くの場合、問題が単発の整理ではなく systematization なら、答えは yes です。通常のプロンプトは、いきなりコード変更に飛びがちです。extract は、まず既存の design-system structure を確認し、何が本当に再利用可能かを見極め、リポジトリが支えられない抽象化を作らないようにしたいときに強みがあります。

extractは初心者でも使いやすい？

はい、ただし対象を絞ることが前提です。初心者でも、1つの feature area を指定して、まず proposal を出してもらう形なら、extractスキルを十分活用できます。逆に、慣習や境界を何も与えずに、UI architecture 全体を作り変えさせようとすると難易度が上がります。

extractを使うには既存のdesign systemが必要？

いいえ。ただし、意思決定は必要です。このスキルは、design system が存在しない場合、新しく作り始める前に確認するようエージェントへ明示的に指示します。これは導入上プラスに働く特徴で、黙って architecture を発明してしまうのを防げます。

extractを使わないほうがいいのはいつ？

次のケースでは extract は向きません。

• 単発の component だけ欲しい
• UIがまだ抽象化を正当化できる成熟度にない
• そのパターンが1回しか出てこない
• 再利用より pixel polish を優先したい
• shared UI をどこに置くか合意がない

こうした状況では、よりシンプルなプロンプトにするか、先に design decision を済ませたほうが時間を節約できます。

extractはどんなパターンを見つける？

このスキルが主に見るのは次のようなものです。

• 繰り返し使われている components
• 同じ概念なのに実装がぶれている箇所
• hard-coded の color、spacing、typography、shadow
• 再利用できる layout / interaction pattern

そのため、単なる JSX の重複排除だけでなく、token 抽出や shared component 整備にも実践的です。

extractはフロントエンドのスタックごとにどう適応する？

中核のロジックは、再利用性と system boundary を見極めることにあるため、stack-agnostic です。ただし、出力品質は、使っている stack や慣習を明示するかどうかでかなり変わります。アプリが Tailwind、CSS variables、component library wrapper を使っているなら、最初に伝えておくと、実際のコードベースに合ったextract計画になりやすくなります。

extractスキルを改善する方法

最初のextractは、思っているより狭い対象から始める

最もよくある失敗は、対象を広げすぎることです。extract は、まず1つの feature、1つの route group、あるいは1つの component family に対して実行したほうが良い結果になりやすいです。十分な繰り返しを分析できる一方で、時期尚早な system-wide architecture を押しつけずに済みます。

design systemの場所をextractに伝える

shared UI の場所がわかっているなら、明示しましょう。

• src/components/ui
• packages/design-system
• app/shared/components

これだけで推測の余地が減り、既存の import、命名、ownership pattern を尊重した提案になりやすくなります。

extract候補だけでなく、extract基準も聞く

改善に効くプロンプト例は次のとおりです。

• “Use extract, but explain why each candidate should be shared now, later, or never.”

これにより、再利用判断のしきい値や根拠が見えるようになります。弱い抽象化だらけの肥大化した design system を避ける助けになります。

依頼ではtokenとcomponentを分ける

再利用の話を全部ひとまとめにしてしまうケースは多いですが、次のように分けたほうが出力が良くなります。

• token opportunities: color、spacing、type、shadow
• component opportunities: button、card、input、banner
• composition opportunities: layout、form section、繰り返しの assembly

こうしておくと、結果が実装・レビューの両面で扱いやすくなります。

移行リスクと影響範囲を聞く

導入を止める大きな要因の1つが、「広範囲に壊れそう」という不安です。extract usage を改善するには、次を明示的に聞くのが有効です。

• 影響を受ける file や area
• 起こりうる breaking changes
• easy win と risky extraction の切り分け
• migration order

これにより、最初の出力がそのまま maintainer の承認材料になりやすくなります。

ローカルのまま残すべき例を伝える

次の一文を加えると有効です。

• “Keep product-specific or one-off logic local unless reuse is clearly justified.”

これは、AIの典型的な失敗――見た目が似ているものを何でもextractしてしまい、意味上は異なるのに保守性を悪化させる――を抑えるのに役立ちます。

最初のpassの後に調整する

最初の extract guide 出力のあとで、次のように追記すると精度が上がります。

• “Narrow this to only token extraction.”
• “Rework the plan to fit our existing component naming.”
• “Only include patterns used 3+ times.”
• “Convert this proposal into a phased migration checklist.”

初回の findings を見たあとで extract のしきい値を締め直すと、このスキルの有効性はかなり上がります。

過剰な抽象化に注意する

よくある失敗は、もっとシンプルな shared primitive や token で済むのに、高度に設定可能な component を発明してしまうことです。props や variant が多すぎる提案が出てきたら、エージェントに次を優先するよう伝えるとよいです。

• shared component は少なめにする
• tokenization を増やす
• composition unit を小さくする
• product ごとに意味が異なる場合は local wrapper を使う

この方向のほうが、健全な design system になりやすいです。

実装前の意思決定支援としてextractを使う

多くのチームにとって、extractスキルの最適な使い方は、最初に診断、次に実装です。コードを書く前に、機会とトレードオフを整理させる用途で使ってください。これは特に legacy codebase で有効で、間違った抽象化は、削減できるはずの作業よりも多くの migration work を生むことがあります。

リポジトリ固有の言葉を入れてextractの出力を改善する

チーム内で “primitives”, “recipes”, “slots”, “tokens”, “foundations” のような用語を使っているなら、そのままプロンプトに含めるとよいです。extractスキルは、maintainer が普段使っている語彙や構造を反映できるほど有用になります。提案がマージしやすく、継続的に保ちやすくなるためです。