戯言と技術

技術的なまとめと株などの市場分析をベースに記事化しています。

impeccable の使い方まとめ — init から critique・polish・live まで全コマンドの使い分け

14分で読めます
目次

広告

注意事項

  • 本記事の内容は試験的な実装であり、アイデアベースの検証です
  • 実務での利用を保証するものではありません
  • 実装についての責任は負いかねます。自己責任でご利用ください
  • AIの出力結果は常に検証が必要です

はじめに

前回の記事「impeccable の /impeccable init で既存サイトのデザインを見直してみた」では、init と critique を使って、運営中のサイトの1画面を直しました。

impeccable には、ほかにも20以上のコマンドがあります。名前を見ただけでは使い分けが分かりにくいので、この記事ではどのコマンドを、どの順番で、何のために使うかをまとめます。

この記事の内容は、impeccable の Skill(SKILL.md は v4.10.0、同梱の CLI は v0.1.27)に入っている手順書を読んで整理したものです。

知りたいこと見る章
入れ方1. 導入する
何から始めればいいか3. 最初に作る2つのファイル
コマンドの一覧4. コマンドの一覧
迷ったときの順番8. おすすめの流れ

1. 導入する

プロジェクトのフォルダで、次のコマンドを実行します(Node.js が必要です)。

npx impeccable install

使っているツール(Claude Code、Codex、Cursor など)を自動で見つけ、次の2つを聞いてきます。

  • このプロジェクトだけに入れるか、全体に入れるか
  • デザインの自動チェック(フック)を入れるか

答えたあと、Claude Code を起動し直せば使えます。Claude Code のプラグインとして入れることもできます。

/plugin marketplace add pbakaus/impeccable

このあと /plugin の画面から Impeccable を選びます。

更新は次のコマンドです。

npx impeccable update

ほかのデザイン系 Skill との比べ方は、「デザインに効く Claude の Skills まとめ」にまとめています。


2. 基本の書き方

Claude Code で、次の形で入力します。

/impeccable <コマンド> <対象>

対象には、ファイルのパスやページのルートを書きます。

/impeccable critique src/pages/Pricing.tsx
/impeccable polish /tools/earthquake/

コマンドが分からないときは引数なしで

/impeccable とだけ入力すると、プロジェクトの状態を見て、次にやるとよいコマンドを2〜3個すすめてくれます。

  • PRODUCT.md がない → init をすすめる
  • コードはあるのに DESIGN.md がない → document をすすめる
  • まだ一度も評価していない → critique をすすめる
  • 前回の評価の点数が低い → polish をすすめる
  • 開発サーバーが動いている → live や generate も候補に出す

すすめるだけで、勝手には実行しません。最初はこれを入力して、出てきた候補から選ぶのが一番楽です。

普通の文章でも使える

コマンド名を覚えていなくても、「この料金表をもっと目立たせて」「スマホで崩れているのを直して」のように頼めば、impeccable が合うコマンドの手順を選んで動きます。2つのコマンドのどちらにも当てはまるときは、1回だけ確認してきます。

画面の「モード」を意識している

impeccable は、画面ごとに「その画面で利用者が何をできれば成功か」を4つのモードに分けて考えます。同じ bolder や quieter でも、モードによってやることが変わります。

モード利用者の成功例デザインの方針
Persuade決めて、行動するLP、料金ページ、キャンペーン思い切った、個性のある表現
Operate作業を終える管理画面、ダッシュボード、計算ツール見つけやすさ・一貫性を優先。個性は細部で出す
Read内容を理解するドキュメント、記事、ヘルプ読みやすい構造を優先
Experience作品そのものを味わうポートフォリオ、ギャラリー作品を主役にし、UI は控えめに

モードは製品ではなく画面で決まります。たとえば、ツールの紹介 LP は Persuade、そのツールの画面は Operate です。


3. 最初に作る2つのファイル

impeccable のコマンドは、実行のたびに PRODUCT.md と DESIGN.md を読み込み、判断の基準にします。最初にこの2つを作っておくと、あとのコマンドの結果がプロダクトに合ったものになります。

ファイル作るコマンド書くこと
PRODUCT.md/impeccable init誰が、どんな状況で使うか。ほかとの違い。守る制約
DESIGN.md/impeccable document色、書体、余白、角丸、部品の作り方など、今の見た目のルール

init — プロダクトの前提を書き残す

/impeccable init

リポジトリの中身を読んだうえで、「主な利用者は誰か」「ほかとの違いは何か」「必ず守る制約は何か」を質問してきます。色や書体などの見た目は決めません。 既存のサイトに入れても、今のデザインを壊さずに始められます。

実際の質問と答え方は、前回の記事で詳しく紹介しています。推測が外れていることもあるので、質問には自分の言葉で答え直すのが大事です。

なお、teach は init の別名です。

document — 今の見た目のルールを書き出す

/impeccable document

コードから色・書体・余白・角丸・部品のパターンを読み取り、DESIGN.md に書き出します。雰囲気や色の性格を表す言葉だけは、人に確認してきます。形式は Google の DESIGN.md の仕様に沿っているので、ほかのツールでも読めます。

すでに画面があるプロジェクトでは、init → document の順に実行しておくのがおすすめです。新しく画面を作る場合は、init のあとに作業を頼めば、デザインの方向を決める流れ(new-work)に進み、そこで DESIGN.md が作られます。


4. コマンドの一覧

コマンドは、目的ごとに6つのグループに分かれています。

グループコマンドひとことで
作る(Build)shapeコードを書く前に、何を作るかを決める
initPRODUCT.md を作る
documentDESIGN.md を作る
extract繰り返し出てくる部品や値を、デザインシステムにまとめる
評価する(Evaluate)critique使いやすさを採点するデザインレビュー
auditアクセシビリティ・性能などの技術的な点検
仕上げる(Refine)polish出す前の最後の仕上げ
bolder控えめすぎる部分を強める
quieterうるさすぎる部分を落ち着かせる
distillいらないものを削って、要点だけにする
hardenエラー・長い文字・多言語など、現実の入力に強くする
onboard初回の流れや、空の状態を作る
強める(Enhance)animate意味のある動きを付ける
colorize色の少ない画面に、役割のある色を足す
typeset書体と文字の大きさの段差を整える
layout余白・並び・視線の順番を整える
delight記憶に残る小さな工夫を足す
overdrive普通の限界を超えた表現に挑む
直す(Fix)clarify文言・ラベル・エラーメッセージを分かりやすくする
adapt画面サイズや端末に合わせる
optimize表示の速さを測って直す
試す(Iterate)liveブラウザで要素を選び、案をいくつも出して比べる
generate要素と方向と数を指定して、案をまとめて出す

以下、グループごとに使いどころを紹介します。


5. 評価する:critique と audit

どちらも「見つけるだけ」のコマンドです。直すのは別のコマンドに任せます。

critiqueaudit
見るもの使いやすさ・分かりやすさ(デザイン)アクセシビリティ・性能・テーマ・レスポンシブなど(技術)
基準Nielsen の10原則で 40点満点項目ごとに 0〜4点
向いているとき「この画面、何が悪いのか分からない」「出す前に、技術的な抜けがないか確かめたい」

critique

/impeccable critique src/pages/tools/Earthquake.tsx

人の目に近いデザインレビュー(A)と、ルールによる自動検出(B)を、別々のサブエージェントで同時に行います。お互いの結果を見ないので、一方の結論にもう一方が引きずられません。サブエージェントを使えない環境で1つにまとめて実行した場合は、結果の最初に「DEGRADED(簡易実行)」と表示されます。

評価は .impeccable/critique/ に保存され、次に実行すると点数の推移が分かります。polish もこの記録を読み、優先度の高い指摘を作業の一覧として使います。

audit

/impeccable audit src/components/

コントラスト比、キーボード操作、aria 属性、タップできる大きさ、画像の遅延読み込み、ダークモードの崩れなどを、コードから点検してレポートにします。


6. 直す・仕上げる・強める

評価で問題が分かったら、内容に合ったコマンドで直します。どのコマンドも、対象として指定した部分だけを変え、ほかは変えないのが原則です。

迷ったら polish

/impeccable polish src/pages/Pricing.tsx

出す前の最後の仕上げです。今のデザインの雰囲気・文章・動きは保ったまま、ずれや抜けを直します。前回の critique の記録があれば、それも読み込みます。

polish は「こっそり作り直す」ことはしません。そもそもの方向が間違っていると判断したときは、作り直しや bolder をすすめてきます。

見た目の強弱を変える:bolder / quieter / distill

こう感じたらコマンド
地味で、目に留まらないbolder
派手すぎて、疲れるquieter
要素が多すぎて、何が大事か分からないdistill

bolder は「効果を足す」のではなく、ページのほかの部分ですでに使っている強い表現を、その部分にも持ち込むという考え方です。新しい色や書体を勝手に増やさず、足りないときは質問してきます。

/impeccable bolder トップページのヒーロー
/impeccable quieter src/pages/Dashboard.tsx

細かい部分を整える:typeset / layout / colorize / animate / delight

直したいものコマンド
書体、見出しと本文の大きさの差typeset
余白、並び、読む順番layout
色の役割(強調、状態、案内)colorize
状態の変化を伝える動きanimate
完了時などの、記憶に残る一工夫delight

overdrive は、100万行を扱える表や、ボタンから変形して開くダイアログなど、普通の限界を超えた表現を目指すコマンドです。外れやすいので、いきなり作らず、まず案を出して確認してくる決まりになっています。

現実の利用に耐えるようにする:harden / clarify / adapt / onboard / optimize

こんなときコマンド
長い名前、空のデータ、絵文字、大きな数で崩れるharden
ボタンやエラーの文言が分かりにくいclarify
スマホやタブレットで使いにくいadapt
初めて来た人が、何をすればいいか分からないonboard
表示が遅いoptimize

前回の記事では、critique の結果をもとに clarify(文言と流れ)→ harden(入力とエラー)→ adapt・distill(スマホ対応と重複の削除)の順に直しました。

UI を編集する前に必ず読むもの

impeccable は、UI を編集する直前に craft-floor.md という手順書を必ず読み込みます。品質の最低ラインと、「角丸の箱の片側だけに太い線を引かない」のような禁止事項がまとめられています。自分で指示しなくても、編集のたびにこの基準が効きます。


7. ブラウザで案を比べる:live と generate

開発サーバー(Vite、Next.js など)が動いていれば、ブラウザ上で案を出して比べられます。Web 専用で、iOS・Android のネイティブアプリでは使えません。

live

/impeccable live

ブラウザで要素をクリックして選び、「もっと強く」などの方向を選ぶと、HTML と CSS の案がいくつか作られ、ホットリロードでその場に差し替わります。案を切り替えて見比べ、気に入ったものを選ぶと、それがソースに反映されます。

ローカルの開発環境で使うもので、本番のサイトに対しては使えません。

generate

/impeccable generate 3 bold variants of the pricing cards

live の近道です。要素・方向・数を一文で伝えると、その要素までスクロールして選び、指定した数の案をまとめて出してくれます。要素を自分でクリックする手間がありません。


8. おすすめの流れ

既存のサイトを見直すとき

/impeccable init                    # 1. PRODUCT.md を作る
/impeccable document                # 2. DESIGN.md を作る
/impeccable critique <画面>          # 3. 1画面に絞って評価する
(指摘に合わせて clarify / harden / adapt / layout など)  # 4. 直す
/impeccable audit <画面>             # 5. 技術的な抜けを点検する
/impeccable polish <画面>            # 6. 仕上げる

critique は時間とトークンを使うので、最初は検索からよく来る画面など、1画面に絞るのがおすすめです。

新しい画面を作るとき

/impeccable init                    # 1. PRODUCT.md を作る
/impeccable shape <作りたいもの>      # 2. 何を作るかを決める(コードは書かない)
(できた方針で作成を依頼)              # 3. 作る
/impeccable critique <画面>          # 4. 評価する
/impeccable polish <画面>            # 5. 仕上げる

shape は、目的・利用者・成功の条件・扱うデータ・状態(空、読み込み中、エラーなど)を2〜3問ずつ質問し、短い設計メモにまとめて確認を取ります。コードは書かずに止まるので、作り始める前に方向をそろえられます。


9. 管理用のコマンド

コマンドできること
/impeccable hooks on / off / statusUI のファイルを編集するたびに自動検出を走らせるフックを、プロジェクトごとに切り替える
/impeccable doctorPRODUCT.md・DESIGN.md・設定ファイルが、今のバージョンの形式とずれていないかを調べて直す
/impeccable foundations404 ページ、アイコン、CI、秘密情報の扱いなど、公開前にそろえたい基本項目を一覧で確認する
/impeccable pin <コマンド>/polish のように、よく使うコマンドを単独のショートカットにする(unpin で外す)

フックについて

フックを有効にすると、.tsx・.html・.css などのファイルを Claude が編集するたびに検出が走り、切れた画像、はみ出し、コントラスト不足、グラデーションの文字、光る影などの機械的に分かる問題だけを、その場で知らせてくれます。文章のリズムや配色の好みなど判断が分かれるものは、編集のたびには知らせず、まとめての検査に回します。

設定は .impeccable/config.json に保存されます。Blade や Twig などのテンプレートを使っている場合は、detector.extensions に拡張子を書けば対象にできます。

CLI で検出だけ使う

Claude を使わずに、検出だけを実行することもできます。LLM を使わないルールベースの検査なので、CI に組み込むこともできます。

npx impeccable detect src/          # フォルダをスキャン
npx impeccable detect index.html    # ファイルを指定
npx impeccable check                # 更新があるか確認

10. 使うときに気をつけたいこと

  • 推測をそのまま受け入れない。 init の質問には、impeccable の推測が選択肢として出てきます。もっともらしくても実際と違うことがあるので、自分の言葉で答え直します
  • 範囲をはっきり指定する。 「全部いい感じに」ではなく、ファイルや部分を指定したほうが、関係ないところが変わりません
  • 検出ツールの0件は「問題なし」ではない。 impeccable 自身も、検出の結果は「欠陥の証拠」であって「品質の証明」ではないとしています。必ず実際の画面を見て確かめます
  • AI が書き換えた文言は人が読む。 前回は、書き換えの中で法的に大事な一文が抜けていました。特に注意書きや条件の文は、最後に人が確認します
  • 同梱のスクリプトの中身を確認する。 コミュニティ製の Skill で、CLI のバイナリも含まれます。導入前に SKILL.md と同梱ファイルを確認しておくと安心です

まとめ

impeccable は、デザインの指示をコマンドの語彙として渡せる Skill です。使い方の要点は次の3つです。

  1. 最初に init(と、既存の画面があれば document)で前提を書き残す
  2. critique や audit で問題を見つけ、内容に合ったコマンドで部分ごとに直す
  3. 迷ったら /impeccable とだけ入力して、すすめられたコマンドから選ぶ

コマンドの数は多いですが、全部覚える必要はありません。まずは init → critique → polish の3つから始めて、指摘の内容に合わせてほかのコマンドを足していくのがおすすめです。

参考

広告

関連する記事