impeccable

本番品質のフロントエンドインターフェースを設計し、反復的に改善します。実際に動作するコード、確かなデザイン上の選択、卓越した仕上がりを実現します。

セットアップ（必須）

デザイン作業やファイル編集を始める前に、以下のゲートを通過してください。これらを省略すると、プロジェクトを無視した画一的な出力になります。

ゲート	必須チェック	不合格の場合
コンテキスト	node {{scripts_path}}/load-context.mjs の実行結果で、PRODUCT.md / DESIGN.md の読み込み結果を確認できていること。	続行する前にローダーを実行します。
プロダクト	PRODUCT.md が存在し、空またはプレースホルダー（[TODO] マーカー、200 文字未満）ではないこと。	{{command_prefix}}impeccable teach を実行してコンテキストを更新し、その後再開します。ユーザーの最初のプロンプトだけをもとに PRODUCT.md を作成してはいけません。
コマンド	サブコマンドを使用する場合、対応するコマンドリファレンスが読み込まれていること。	続行する前にリファレンスを読み込みます。
仕上がり	{{command_prefix}}impeccable craft に、このタスク向けのユーザー確認済みの形状ブリーフがあること。teach / PRODUCT.md は形状ブリーフとして認められません。	{{command_prefix}}impeccable shape を実行し、明示的なブリーフ確認を待ちます。
画像	必要なビジュアルプローブ / モックが生成されているか、理由を示して省略されていること。	コードを書く前に、shape.md または craft.md の画像生成ゲートを解決します。
変更	上記の有効なゲートをすべて通過していること。	まだプロジェクトファイルを編集してはいけません。

Codex スタイルのエージェントは、ファイルを編集する前に次のように述べる必要があります。

IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open

{{command_prefix}}impeccable craft では、別のユーザー応答でデザインブリーフが承認された場合、またはユーザーのリクエストに確認済みのブリーフがすでに含まれている場合に限り、shape=pass が有効です。PRODUCT.md を作成した後、前提を要約した後、または未確認のブリーフを自分で作成した後に、shape=pass としてはいけません。

ほかのハーネスも、この状態を提示できる場合は同じチェックリストに従ってください。

1. コンテキストの収集

大文字と小文字を区別せず、2 つのファイルを確認します。ローダーは既定でプロジェクトのルートを参照し、ルートにファイルがない場合は .agents/context/ と docs/ を順に確認します。IMPECCABLE_CONTEXT_DIR=path/to/dir（絶対パス、または cwd からの相対パス）で参照先を変更できます。

• PRODUCT.md：必須です。ユーザー、ブランド、トーン、反面教師、戦略原則を記載します。
• DESIGN.md：任意ですが、強く推奨されます。色、タイポグラフィ、エレベーション、コンポーネントを記載します。

1 回の呼び出しで両方を読み込みます。

node {{scripts_path}}/load-context.mjs

JSON 出力全体を確認してください。head、tail、grep、jq にパイプしてはいけません。出力の contextDir フィールドに、ファイルの解決元が示されます。

出力がこのセッションの会話履歴にすでに含まれている場合は、再実行しないでください。ただし、{{command_prefix}}impeccable teach または {{command_prefix}}impeccable document を実行した直後（これらのコマンドはファイルを書き換えます）、またはユーザーが手動でファイルを編集した場合は、新たに読み込む必要があります。

{{command_prefix}}impeccable live は live.mjs を通じてコンテキストをあらかじめ読み込みます。live.mjs を実行した場合、このセッションで load-context.mjs も実行しないでください。

PRODUCT.md が存在しない、空、またはプレースホルダー（[TODO] マーカー、200 文字未満）の場合は、{{command_prefix}}impeccable teach を実行してから、新しいコンテキストを使ってユーザーの元のタスクを再開します。元のタスクが {{command_prefix}}impeccable craft の場合は、実装作業に入る前に {{command_prefix}}impeccable shape を実行します。

DESIGN.md が存在しない場合は、セッションごとに一度だけ、「{{command_prefix}}impeccable document を実行すると、ブランドに沿った出力が得られます」と案内してから続行します。

2. レジスター

すべてのデザインタスクは、ブランド（マーケティング、ランディングページ、キャンペーン、長文コンテンツ、ポートフォリオ：デザインそのものが製品）か、プロダクト（アプリの UI、管理画面、ダッシュボード、ツール：デザインが製品を支えるもの）のいずれかです。

デザインを始める前に特定してください。優先順位は、（1）タスク自体にある手がかり（「ランディングページ」と「ダッシュボード」の違いなど）、（2）焦点となっている対象（作業中のページ、ファイル、ルート）、（3）PRODUCT.md の register フィールドです。最初に一致したものを採用してください。

PRODUCT.md に register フィールドがない場合（レガシー）、その「Users」セクションと「Product Purpose」セクションから一度だけ推定し、そのセッション中は推定値をキャッシュしてください。フィールドを明示的に追加するために、ユーザーに {{command_prefix}}impeccable teach の実行を提案してください。

対応するリファレンスを読み込んでください：reference/brand.md または reference/product.md。以下の共通デザイン原則は、どちらにも適用されます。

共通デザイン原則

両方のレジスターにおいて、すべてのデザインに適用してください。実装の複雑さを美的ビジョンに合わせます。マキシマリズムには緻密なコードが必要で、ミニマリズムには精密さが必要です。創造的に解釈してください。プロジェクトごとに変化をつけ、同じ選択に収束しないようにしてください。{{model}} は並外れた仕事ができます。遠慮はいりません。

色

• OKLCH を使用してください。明度が 0 または 100 に近づくほど彩度を下げてください。極端な明度で彩度を高くすると、けばけばしく見えます。
• #000 や #fff は使用しないでください。すべてのニュートラルカラーにブランドの色相を加えてください（彩度 0.005〜0.01 で十分です）。
• 色を選ぶ前に、配色戦略を決めてください。主張の強さに応じて、次の 4 段階があります。
  • 控えめ：色味を加えたニュートラルカラー＋アクセントカラー 1 色（10% 以下）。プロダクトでは標準、ブランドではミニマリズムに適します。
  • 明確な主張：彩度の高い 1 色が画面の 30〜60% を占めます。アイデンティティを重視するページでは、ブランドの標準です。
  • フルパレット：名前の付いた 3〜4 色の役割を定め、それぞれを意図的に使用します。ブランドのキャンペーンや、プロダクトのデータビジュアライゼーションに適します。
  • 色で覆い尽くす：画面そのものが色になります。ブランドのヒーローセクションやキャンペーンページに適します。
• 「アクセントカラー 1 色（10% 以下）」というルールは、「控えめ」にのみ適用されます。「明確な主張」／「フルパレット」／「色で覆い尽くす」では、意図的にこの割合を超えます。反射的にすべてのデザインを「控えめ」にしないでください。

テーマ

ダークかライトかは、決してデフォルトで決めないでください。「ツールはダークだとかっこいいから」ダークにするのも、「無難だから」ライトにするのもいけません。

選ぶ前に、物理的な利用場面を 1 文で書いてください。誰が、どこで、どのような環境光の下で、どんな気分で使うのかを記述します。その文だけで答えが決まらないなら、具体性が足りません。決まるまで詳細を加えてください。

「オブザーバビリティダッシュボード」だけでは答えは決まりません。「暗い部屋で午前 2 時に、27 インチモニターでインシデントの重大度を一目で確認する SRE」なら決まります。カテゴリではなく、その一文に従ってください。

タイポグラフィ

• 本文の 1 行の長さは 65〜75ch 以内にしてください。
• サイズと太さのコントラスト（段階間で 1.25 以上の比率）で階層をつけてください。平坦なスケールは避けてください。

レイアウト

• リズムを生むために、間隔に変化をつけてください。すべて同じパディングにすると単調になります。
• カードは安易な答えです。本当に最適な表現である場合にのみ使ってください。カードを入れ子にするのは常に不適切です。
• すべてをコンテナで囲まないでください。ほとんどの要素には不要です。

モーション

• CSS のレイアウトプロパティはアニメーションさせないでください。
• 指数関数的なカーブ（ease-out-quart / quint / expo）でイーズアウトしてください。バウンスや弾性のある動きは使わないでください。

絶対禁止事項

該当したら書き直してください。以下のいずれかを使おうとしている場合は、要素の構造を変えてください。

• 片側だけのアクセントボーダー。 カード、リスト項目、コールアウト、アラートの色付きアクセントとして、1px を超える border-left または border-right を使うこと。意図的であっても禁止です。全面ボーダー、背景色の濃淡、先頭の番号やアイコン、または何も使わない方法に変えてください。
• グラデーションテキスト。 グラデーション背景と組み合わせて background-clip: text を使うこと。装飾にすぎず、意味のある表現にはなりません。単色を使い、太さやサイズで強調してください。
• デフォルトのグラスモーフィズム。 装飾目的でぼかしやガラス風カードを使うこと。まれに、明確な意図がある場合にのみ使ってください。それ以外では使わないでください。
• ヒーロー指標のテンプレート。 大きな数字、小さなラベル、補足の統計、グラデーションのアクセント。SaaS のありきたりなパターンです。
• 同一のカードグリッド。 アイコン＋見出し＋テキストで構成された同じサイズのカードを、延々と繰り返すこと。
• 最初にモーダルを考えること。 モーダルはたいてい手抜きです。まずインライン表示や段階的な代替案を十分に検討してください。

コピー

• すべての言葉に役割を持たせます。見出しを言い換えて繰り返したり、タイトルの内容を繰り返す導入文を置いたりしません。
• em ダッシュは使いません。 コンマ、コロン、セミコロン、ピリオド、または括弧を使います。-- も使いません。

AIっぽさのチェック

このインターフェースを見て、誰もが疑いなく「AIが作った」と言えるなら、失敗です。レジスターをまたぐ失敗は、上記の絶対禁止事項です。レジスター固有の失敗については、それぞれのリファレンスを参照してください。

カテゴリ反射チェック。 2つの段階で実施します。2つ目の段階では、1つ目で見逃したものを見つけます。

• 第一段階： カテゴリだけでテーマと配色を推測できるなら（「オブザーバビリティ → ダークブルー」「ヘルスケア → 白とティール」「金融 → ネイビーとゴールド」「暗号資産 → 黒地にネオン」）、それは学習データ由来の最初の反射です。ドメインから答えが明らかでなくなるまで、シーンを表す文と配色の方針を練り直します。
• 第二段階： カテゴリと避けるべき参考例の組み合わせから美的スタイルの系統を推測できるなら（「SaaS風のクリーム色ではないAIワークフローツール → エディトリアルなタイポグラフィ」「ネイビーとゴールドではないフィンテック → ターミナルを基調とするダークモード」）、それはさらに一段深い罠です。最初の反射は避けていますが、2つ目は避けられていません。どちらの答えも明らかでなくなるまで練り直します。ブランドレジスターの反射的に避けるべき美的スタイルの系統には、現在飽和しているスタイルが記載されています。

コマンド

コマンド	カテゴリ	説明	リファレンス
craft [feature]	ビルド	まず形を整え、その後機能をエンドツーエンドで構築します	reference/craft.md
shape [feature]	ビルド	コードを書く前に UX/UI を計画します	reference/shape.md
teach	ビルド	PRODUCT.md と DESIGN.md のコンテキストを設定します	reference/teach.md
document	ビルド	既存のプロジェクトコードから DESIGN.md を生成します	reference/document.md
extract [target]	ビルド	再利用可能なトークンとコンポーネントをデザインシステムに取り込みます	reference/extract.md
critique [target]	評価	ヒューリスティック評価による UX デザインレビューを行います	reference/critique.md
audit [target]	評価	技術品質をチェックします（a11y、パフォーマンス、レスポンシブ対応）	reference/audit.md
polish [target]	洗練	リリース前に最終的な品質チェックを行います	reference/polish.md
bolder [target]	洗練	無難なデザインや平凡なデザインを際立たせます	reference/bolder.md
quieter [target]	洗練	強すぎるデザインや刺激の強いデザインを控えめにします	reference/quieter.md
distill [target]	洗練	本質だけを残し、複雑さを取り除きます	reference/distill.md
harden [target]	洗練	エラー、i18n、エッジケースに対応し、本番環境に備えます	reference/harden.md
onboard [target]	洗練	初回利用時のフロー、空の状態、利用開始時の体験を設計します	reference/onboard.md
animate [target]	強化	目的に沿ったアニメーションと動きを追加します	reference/animate.md
colorize [target]	強化	モノクロの UI に戦略的に色を加えます	reference/colorize.md
typeset [target]	強化	タイポグラフィの階層とフォントを改善します	reference/typeset.md
layout [target]	強化	余白、リズム、視覚的な階層を整えます	reference/layout.md
delight [target]	強化	個性と記憶に残る工夫を加えます	reference/delight.md
overdrive [target]	強化	従来の限界を超えるデザインにします	reference/overdrive.md
clarify [target]	修正	UX コピー、ラベル、エラーメッセージを改善します	reference/clarify.md
adapt [target]	修正	さまざまなデバイスや画面サイズに対応させます	reference/adapt.md
optimize [target]	修正	UI のパフォーマンスを診断して改善します	reference/optimize.md
live	反復	ビジュアルバリアントモード：ブラウザーで要素を選び、代替案を生成します	reference/live.md

このほかに、管理用コマンドが 2 つあります：pin <command> と unpin <command>。詳細は以下をご覧ください。

ルーティングルール

1. 引数なし：上記の表をカテゴリ別にまとめ、ユーザー向けのコマンドメニューとして表示します。何をしたいか尋ねます。
2. 最初の単語がコマンドと一致する場合：対応するリファレンスファイルを読み込み、その指示に従います。コマンド名以降はすべてターゲットとして扱います。
3. 最初の単語がコマンドと一致しない場合：一般的なデザインの実行として扱います。セットアップ手順、共通のデザイン原則、読み込まれたレジスターのリファレンスを適用し、引数全体をコンテキストとして使用します。

セットアップ（コンテキストの収集、レジスター）はすでに読み込まれているため、サブコマンドから {{command_prefix}}impeccable を再度呼び出すことはありません。

最初の単語が craft の場合も、まずセットアップを実行します。ただし、その後のフローは reference/craft.md に従います。セットアップ中にブロッカーとして teach が呼び出された場合は、teach を完了し、コンテキストを更新してから、元のコマンドとターゲットの処理を再開します。

ピン留め／ピン留め解除

ピン留めすると、{{command_prefix}}<command> で {{command_prefix}}impeccable <command> を直接実行できる独立したショートカットが作成されます。ピン留め解除すると、ショートカットが削除されます。このスクリプトは、プロジェクト内に存在するすべてのハーネスディレクトリに書き込みます。

node {{scripts_path}}/pin.mjs <pin|unpin> <command>

有効な <command> は、上記の表に記載されている任意のコマンドです。スクリプトの結果を簡潔に報告してください。成功した場合は新しいショートカットを確認し、エラーの場合は標準エラー出力をそのまま伝えてください。