戯言と技術

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

impeccable の /impeccable init で既存サイトのデザインを見直してみた — PRODUCT.md から critique・修正まで

15分で読めます
目次

広告

注意事項

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

はじめに

デザインに効く Claude の Skills まとめ で紹介した impeccable を、運営中のサイトで実際に使ってみました。

対象は 被災とお金のナビ(sonae.keydrop.net) です。災害で家・家財・車・ローンに被害が出たとき(または出る前)に、受け取れる可能性のある額と自己負担の目安を計算する静的サイトです。React + Vite で作り、全ページをプリレンダーしています。

このサイトの見た目は、これまでにも /ui-ux-pro-max:brand や /frontend-design で整えてきました。今回は impeccable の /impeccable init から始めて、「見た目」ではなく「誰のための画面か」から見直しました。

地震保険ツールの区分「全部」の結果。左が改善前(約0万円〜6,000万円という幅だけの結論)、右が改善後(区分ごとの表が結論になっている)。入力した保険金額は左右で異なります

結果を先にまとめます。

項目結果
人がしたこと/impeccable init を実行し、質問に2回答えた(利用者・違い・制約の3問と、直す範囲の2問)
init が作ったものPRODUCT.md(利用者、目的、ほかとの違い、守る制約などの記録)
評価した画面地震保険ツール(/tools/earthquake/)
評価の点数21 / 40(Nielsen の10原則。P1 の問題が3件、P2 が2件)
直したファイル5ファイル(追加230行・削除58行)+ PRODUCT.md
確認型チェック、lint、テスト342件、文言チェック、本番ビルドがすべて通過。自動検出の指摘は1件から0件に

impeccable は v0.1.27、Claude Code は 2.1.330 を使いました。記事中の画面と出力は、すべて2026年11月21日に実際に動かしたときのものです。


1. /impeccable init とは

impeccable には critique(評価)、polish(仕上げ)、layout、typeset など、デザインの作業を表すコマンドがそろっています。init はその最初の一歩で、プロダクトの前提を PRODUCT.md に書き残すコマンドです。

ポイントは、init では色や書体などの見た目を決めないことです。決めるのは次のような「変わりにくい事実」だけです。

  • 誰が、どんな状況で、何をしに来るのか
  • ほかのサービスと何が違うのか
  • 今後のデザイン作業でも守る制約(法律、アクセシビリティなど)

ここで書いた PRODUCT.md は、あとで critique や polish を実行するたびに読み込まれ、判断の基準になります。


2. init を実行する

サイトのリポジトリで、Claude Code から次のように実行しました。

/impeccable init

まず、impeccable がリポジトリの中身(CLAUDE.md の仕様書、docs/brand-guidelines.md、ルート構成など)を読みます。そのうえで「読み取った内容で合っているか」を3つ質問してきました。

質問impeccable の推測私の答え
主な利用者は?被災直後の人(スマホ片手・低速回線)を最優先、被災前の人が二番目被災前の人が主(実際は検索から来る、備えている人が中心)
ほかとの違いは?保険会社・自治体・業者は縦割り。このサイトは災害 × 資産 × お金の出どころを横断し、計算ツールが主役。入力は外に送らない合っている
必ず守る制約は?(複数選択)法的ガードレール/軽さ・オフライン/既存ブランド指針/アクセシビリティ法的ガードレールとアクセシビリティ

1問目がいちばん大事でした。仕様書には「事後モード(被災直後)」の話が多く書かれていたため、impeccable は被災直後の人を主な利用者と推測しました。一方で、実際のアクセスの中心は、地震保険や火災保険を調べている被災前の人です。ここを直せたことが、このあとの評価の結果を大きく変えました。

答えをもとに、PRODUCT.md が書き出されます(抜粋)。

## Users

- **主:被災前の人(事前モード `/jizen/`・ツール・落とし穴の解説)。** 車の購入前、
  火災保険・地震保険の更新前、引越しの前などに、「もし被災したら、どこからいくら戻り、
  いくら自分で負担することになるか」を知りたい人。多くは検索から個別のツール・解説ページに直接着く。
- **二番目:被災した人(事後モード `/hisai/`)。** ...

## Product Principles

1. 一般論と目安に徹し、個別の判断は専門家と窓口に渡す。
2. 縦割りをまたいで、お金の出どころを一画面で見せる。
3. 結論(受け取れる可能性・自己負担・対象外)を最初に見せ、根拠と出典をすぐそばに置く。
4. 「わからない」を正規の答えとして扱い、次に見る書類を示す。
5. 不安を煽らない。カウントダウンや強い色で急かさない。

利用者の声や実績の数字は手元にないので、「Evidence on Hand」の欄には「ない。作らない」と書かれました。架空の実績を作らないよう、はっきり書き残してくれるのは安心です。


3. critique で地震保険ツールを評価する

init のあと、impeccable は次の一手として、既存の画面に絞ったコマンドをすすめてきます。今回は、検索から多く着く地震保険ツールを critique で評価しました。

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

critique は、2つの評価を別々のサブエージェントで同時に行います。お互いの結果を見ないので、一方の結論にもう一方が引きずられません。

担当今回やったこと
AデザインレビューPRODUCT.md と評価基準を読み、PC・スマホで画面を撮りながら、実際にツールを最後まで操作
B自動検出impeccable detect でソースと表示中のページを検査

点数は 21 / 40

#原則点主な問題
1状態が見える2最初の画面で「1 / 1 問目」と出て、進捗バーが満タン。実際は最大4問
2実世界との一致2被災前の人に「損害の区分の見込み」を選ばせている
3制御と自由3戻る・直す・やり直しがそろっている
4一貫性2上の受取額の計算と、下の保険料の計算で操作の型が違う
5エラーの予防2「1,000」とカンマを入れると、理由も出ずに先へ進めない
6覚えなくて済む2入れた保険金額が保険料の計算に引き継がれない
7効率2早見表への近道がページの下に埋もれている
8簡潔さ2受取額が3回繰り返され、結果がスマホで非常に長い
9エラーからの回復1無効な入力にメッセージが出ない
10ヘルプ3「わからない」→「どこを見れば分かる?」の流れは良い

impeccable の基準では、20〜27点は「Acceptable(使えるが、大きな改善が必要)」です。

いちばん大きな指摘は「時制のずれ」

見た目の指摘より先に出てきたのが、次の指摘でした。

PRODUCT.md の主な利用者は「被災前の人」です。それなのに、設問4「損害の区分の見込みは?」と結果の「次にやること」(片付ける前に写真、損害調査、罹災証明書)は、すでに被災した人向けの文章です。

init で「主な利用者は被災前の人」と答えていなければ、出てこなかった指摘です。PRODUCT.md が評価の基準として効いていることが分かります。

優先度の高い問題として挙がったのは、次の5件です。

優先度問題
P1被災前の人に、被災後の設問と「次にやること」を出している
P1区分を「わからない」にすると、結論が「約0万円〜6,000万円」になる(何も伝えていない)
P1「入っていない」と答えると、保険料の計算への案内がなく行き止まりになる
P2進捗の「1 / 1」、カンマ入りの金額、上限での丸めを黙って処理している
P2スマホでヘッダーが「被災とお金のナ/ビ」と行の途中で折れる。結果に重複が多い

自動検出(B)の指摘は1件だけでした。スマホ幅で h1 と h2 の大きさの比が 1.23 で、基準の 1.25 に少し届かないというものです。B はほかに「検出ツールはレイアウトの良し悪しまでは判断しない」とも報告しており、A の指摘と役割がきちんと分かれています。


4. 範囲を決めて直す

critique の最後に、impeccable が2つ質問してきました。

質問私の答え
どこまで直すかP1 の3件と P2 をすべて
被災後向けの「次にやること」をどう扱うか畳んで残す(被災後に検索で来る人もいるため)

この答えをもとに、clarify(文言と流れ)→ harden(入力とエラー)→ adapt・distill(スマホ対応と重複の削除)の順に直しました。impeccable は UI を編集する直前に、品質の最低ラインをまとめた craft-floor.md を読み込みます。そこには「角丸の箱の片側だけに太い線を引かない」などの禁止事項も書かれています。

4-1. 区分の設問を「比べる」ための設問に変える

設問を「損害の区分の見込みは?」から「どの損害区分の目安を見ますか?」に変え、最初の選択肢を 「全部の区分を並べて比べる」 にしました。選択肢の補足も、専門用語(「主要構造部の損害が時価の50%以上」)から、被災前の人に役立つ「保険金額の100%」などに変えています。

{
  id: 'eq.damageClass',
  text: 'どの損害区分の目安を見ますか?',
  help: '区分は被災後に保険会社の損害調査で決まります。備えとして調べている場合は、全部の区分を並べて比べられます。',
  type: 'choice',
  options: [
    { value: UNKNOWN, label: '全部の区分を並べて比べる' },
    { value: 'total', label: '全損', note: '保険金額の100%' },
    // ...
  ],
  // 「全部の区分を並べて比べる」が「わからない」の役を兼ねる
  noUnknown: true,
  showIf: has,
},

「全部を比べる」を選んだときは「約0万円〜6,000万円」という幅を出すのをやめ、区分ごとの表そのものを結論にしました(記事の最初の画像の右側)。

4-2. 「入っていない」を行き止まりにしない

改善前は、赤い「対象外」のバッジと、家財のレシートの話など関係の薄い落とし穴が並び、そこで終わっていました。改善後は、結論として「火災保険だけでは原則として補償されない」ことと「途中からでも付けられる」ことを示し、付けた場合の保険料の計算へ進むボタンを置いています。

「地震保険に入っていない」と答えたときの結果。左が改善前(対象外のバッジと長い文章)、右が改善後(結論と保険料の計算へのボタン)

このサイトは保険の勧誘をしないことが法的な前提です。そのため、ボタンの文言は「付けた場合の保険料の目安を計算する」にとどめ、「付けるべき」「おすすめ」とは書いていません。サイトの文言チェック(NG 表現の検出)も通っています。

4-3. 被災後の手順は畳んで残す

「片付ける前に写真を残す」「損害調査を受ける」などの手順は、<details> の「被災したときに次にやること」に畳み、被災された方向けのページへのリンクを添えました。被災前の人の邪魔をせず、被災後に検索で来た人もすぐに開けます。

4-4. 入力とエラーを直す(harden)

1問1画面のウィザードは、ほかのツールでも共通の部品です。そのため、ここを直すとサイト全体のツールが良くなります。

  • 進捗:答えによって設問が増える場合は総数を言い切らず、「1 問目(答えによって設問が続きます)」と表示する
  • 金額の入力:証券の表記どおり「1,500」と入れても通るよう、桁区切りのカンマと空白を取り除く。数字でないときは「数字だけで入れてください(例:1000)」と表示し、aria-describedby で読み上げにも対応する
  • 上限:設問の補足に上限(建物5,000万円・家財1,000万円)を書き、上限を超えて入れた場合は「建物は入力した8,000万円ではなく、上限の5,000万円で計算しています」と結果に表示する
onChange={(e) =>
  setText(
    e.target.value
      // 全角の数字・小数点は半角に、証券の表記どおりの桁区切り(, ,)と空白は取り除く
      .replace(/[0-9.]/g, (c) => String.fromCharCode(c.charCodeAt(0) - 0xfee0))
      .replace(/[,,\s ]/g, ''),
  )
}

4-5. スマホのヘッダーと重複を直す(adapt・distill)

  • ヘッダーのサイト名とナビに white-space: nowrap を付け、余白と字間を詰めて、390px 幅でも1行に収めた
  • 受取額の計算で入れた保険金額を、ボタンを押したときに保険料の計算へ引き継ぐ(CustomEvent で渡す。再訪時は保存済みの回答から読む)
  • 結論・表と同じ数字を繰り返していた判定カードを出さないようにし、落とし穴は題名だけのリンクの一覧にした
  • 結論の箱の「左だけ4pxの太線」をやめ、全周の細い線と面の色にした(craft-floor.md の禁止事項)
  • スマホの h1 を 27px → 28px にし、自動検出の「見出しの段差」の指摘を解消した

スマホの最初の画面。左が改善前(サイト名とナビが行の途中で折れ、「1 / 1 問目」と表示)、右が改善後

PC では、区分ごとの表と保険料の計算へのボタンが、最初の画面で結論として見えるようになりました。

PC での改善後の結果画面。区分ごとの受取額の表と、保険料の計算へのボタン


5. 確認したこと

直したあと、次の確認をしました。

確認結果
型チェック・lint通過
テスト(Vitest)342件すべて通過
文言チェック(断定・推奨などの NG 表現)通過
本番ビルド(プリレンダー・リンク確認・ページサイズ)通過。/tools/earthquake/ は 148.2KB(基準は150KB 以内)
impeccable detect(スマホ幅のページ)指摘1件 → 0件
画面Playwright で、カンマ入り入力・無効な入力・上限超え・「入っていない」・保険料への引き継ぎを、PC とスマホで操作して撮影

画面を自分で見直す中で、AI の修正の抜けにも1つ気づきました。「入っていない」の結論を書き直したとき、元のルールにあった 「すでに起きた地震の損害は対象になりません」 という一文が抜けていたのです。被災後に「今から付ければ出る」と誤解させかねない大事な一文なので、戻しました。文言チェックや自動検出では見つからない種類の抜けで、AI の修正は最後に人が読む必要があることを改めて感じました。

なお、今回は直したあとに critique をもう一度実行して点数を取り直すところまでは、まだやっていません。impeccable は評価を .impeccable/critique/ に保存しており、次に実行すると点数の推移も表示されます。


6. 使ってみて分かったこと

良かった点

  • PRODUCT.md が評価の基準になる。 「主な利用者は被災前の人」と1回答えただけで、critique がそれを基準に「時制のずれ」という一番大きな問題を見つけた。見た目のチェックだけでは出てこない指摘でした
  • init が見た目を決めない。 色や書体の好みを聞かれないので、既存のブランドを壊さずに使い始められる
  • 評価が2つに分かれている。 人の目に近いレビューと機械的な検出が別々に動くので、「検出ツールで0件=問題なし」と思い込まずに済む
  • 質問が具体的。 「どこまで直すか」「被災後の手順をどう扱うか」など、見つかった問題に結びついた選択肢で聞いてくる

気をつけたい点

  • 推測をそのまま受け入れない。 init の最初の推測(被災直後の人が主)は、仕様書から見ればもっともでしたが、実際の利用とは違いました。質問には自分の言葉で答え直すのが大事です
  • critique は重い。 サブエージェント2つが画面を撮りながら動くため、時間とトークンを使います。今回は1画面に絞りました
  • 修正の文言は人が読む。 上に書いた「すでに起きた地震の損害は対象になりません」の抜けのように、法的に大事な一文が書き換えで落ちることがあります

まとめ

/impeccable init は、デザインの見直しを「見た目」ではなく「誰のための画面か」から始めるためのコマンドでした。3つの質問に答えて PRODUCT.md を作るだけで、そのあとの critique の評価がプロダクトに合ったものになります。

今回は地震保険ツール1画面だけでしたが、同じ PRODUCT.md を使って、火災保険(水災)や支援金のツールにも同じ見直しを広げていく予定です。

参考

広告

関連する記事