1仕組みと動作原理

コンパイル式マルチホスト配信：skill/ を唯一のマスターソース（SKILL.src.md + scripts/ + reference/ + agents/）とし、リポジトリ内には常に .claude/.cursor/.agents/.gemini など20のホストディレクトリ向けコンパイル済みコピーが存在。コピー側ではプレースホルダー（{{scripts_path}}/{{command_hint}} 等）をホスト固有のパスへ展開し、ホストフロントマター（version: 4.3.1、user-invocable、allowed-tools 等）を書き込み、 整合性用コメントを除去。

skill/SKILL.src.md

allowed-tools: - Bash(npx impeccable *) - Bash({{scripts_path}}/impeccable *)

.claude/skills/impeccable/SKILL.md の冒頭20行を確認すると、該当箇所が '.claude/skills/impeccable/scripts/impeccable *' かつ 'version: 4.3.1' に展開されていることが確認可能。diff でもプレースホルダー展開と rule コメントの有無を除き一字一句同一であることを検証済み。

セッション起動プロトコル：毎セッション最初に `<skill-base-dir>/scripts/impeccable context`（自己完結型エンジンバイナリを特定する POSIX shell 製ランチャー）を実行し、エンジンが PRODUCT.md/DESIGN.md/一致する surface brief を読み取って指示（CONTEXT_STALE などのディレクティブを含む）をエージェントに返却。ランチャー失敗時の明示的なフォールバックも備え、ユーザーに明示したうえで既存の PRODUCT.md/DESIGN.md を直接読み込んで続行。

.claude/skills/impeccable/SKILL.md

Run `<skill-base-dir>/scripts/impeccable context` once per session, where `<skill-base-dir>` is the directory that contains this SKILL.md (the skill folder, not a plugin root two levels above it); keep cwd at the user's project.

フォールバックプロトコルの原文：'On refusal or failure, send a separate message **before the next tool call**: "Context loading did not run; I'll read the existing project context directly."'——ランチャー障害時でも計画や編集作業をブロックしない設計。

中核機能は付属エンジンバイナリ（Node ランタイム不要）：ランチャーは IMPECCABLE_BIN → 同ディレクトリの bin/<os>-<arch>/ → ~/.impeccable/bin → バージョン固定キャッシュ → PATH 上の impeccable の順でバイナリを探索。最終手段として作者の GitHub リリースから該当バージョンのバイナリをユーザーキャッシュにダウンロードし、sha256 sidecar 検証を実施（フェイルクローズ：検証失敗やチェックサム不在時は実行拒否）。

skill/scripts/impeccable

base="${IMPECCABLE_DOWNLOAD_BASE:-https://github.com/pbakaus/impeccable/releases/download}"

ダウンロード処理の原文：'Last resort: fetch this version's binary for the current platform from the public release channel into the user cache'。検証処理の原文：'Fail closed: a freshly downloaded binary runs only after verifying against its .sha256 sidecar.'。外部ネットワークのないサンドボックスでは PATH への事前インストールが可能（ランチャー内コメントに記載）。

23コマンド + ルーティングの指示体系：SKILL.md の本体はコマンド表（Build/Evaluate/Refine/Enhance/Fix + live 反復）であり、引数なし呼び出し時はコンテキスト対応メニューを表示するのみで自動実行は行わない。各コマンドは reference/ 下の独立した playbook に対応し、リリース時の整合性チェック用としてソースファイル内に  タグを埋め込み済み。

.claude/skills/impeccable/SKILL.md

**No argument:** read [routing.md](reference/routing.md) and present its context-aware menu; never auto-run a command.

README には '1 skill, 23 commands' と記載。コマンド表の実行数は23（非推奨の craft を含む）。reference/ ディレクトリには35以上の playbook（init/shape/audit/polish/live/hooks/craft-floor 等）が存在し、さらに degraded/ や agents/*.md サブエージェントプロンプトも同梱。

PRODUCT.md/DESIGN.md 二重ドキュメントによる信頼できる唯一の情報源：init は PRODUCT.md（プロダクトの真実：ユーザー/タスク/制約/プラットフォーム）のみを記述し、ビジュアル要件には触れない。document/extract は完成したコードから DESIGN.md（デザインシステム/トークン/コンポーネント）を逆生成。ビジュアル方針は new-work で決定され DESIGN.md を置き換える（『証拠こそが権威であり、ファイル名ではない』）。

skill/reference/init.md

`init` captures durable product truth in PRODUCT.md. It does not invent a visual world and does not write DESIGN.md; [new-work.md](new-work.md) creates or expands one, and [document.md](document.md) records an incumbent one.

SKILL.md の3原則『How to design』にて上書きセマンティクスを厳格化：'Refinement preserves; redesign replaces.' + 'Visual authority is evidence, not a filename.'。ブリーフ優先：'**The brief wins.** Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning.'

決定論的リンター（61規則）をフック形式でホストに統合：hooks on 実行後、Claude Code/Codex/Copilot では UI ファイル編集ごとに post-tool-use フックでリンターを自動実行して検出結果をコンテキストに再投入。Cursor では preToolUse により不適切な書き込みを反映前に遮断。設定は .impeccable/config.json（ローカルでは .impeccable/config.local.json で上書き）で管理。

skill/reference/hooks.md

The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`).

Cursor の遮断セマンティクス原文：'Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.'。README には61の決定論的ルールについて 'run the deterministic rules with no LLM and no API key' と明記。編集ごとの即時トリガー + セッション Stop 時の網羅的ディープスキャンにより『検出器-フック-コンテキスト』のループを確立。

live ブラウザバリアントモード：ローカル開発サーバー（HMR）上で選択要素を AI に渡し、生成した HTML+CSS バリアントへホットスワップ。ポーリングイベントループ（_instructions フィールドが信頼できる次ステップ）と .impeccable/live/ セッションジャーナルにより切断復旧を保証。本番サイトへのスクリプト注入や CSP の緩和は明示的に禁止。

skill/reference/live.md

Interactive live variant mode: select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR.

制約境界の原文：'Live editing requires a local checkout; injection into deployed production sites (including HTTPS) is unsupported. …Do not disable browser security or weaken production CSP to enable live mode.'

2コア機能

0123コマンドからなるデザイン語彙体系：craft/shape/init/document/extract（Build）、critique/audit（Evaluate）、polish/bolder/quieter/distill/harden/onboard（Refine）、animate/colorize/typeset/layout/delight/overdrive（Enhance）、clarify/adapt/optimize（Fix）、live（Iterate）

02PRODUCT.md によるプロダクトの真実の記録（init：ユーザー/タスク/メカニズム/制約、ビジュアルの好みに関する質問は禁止）+ DESIGN.md によるデザインシステムの記録（document/extract：完成コードからトークン/コンポーネントを逆生成）

0361種類の決定論的リンター（LLMやAPIキーなしでローカル動作し、AI特有の雑な出力パターンや一般的なデザイン品質を網羅）+ 編集ごと/Stop 時の2段階フックによるホスト統合

04craft-floor 編集前必読要件：品質の最低基準、絶対的な禁止事項、自動検出器では拾えない反射的チェック項目

05live ブラウザバリアント反復（HMR ホットスワップ、イベントポーリング、ジャーナル復旧、本番環境への注入禁止）

06パターン分類体系（Persuade/Operate/Read/Experience）+ パターン永続化規律（該当する surface brief 内のみに記録）

07バージョン管理されたエンジンの自己保守：doctor による PRODUCT.md/DESIGN.md/設定/フックのドリフト修復、pin/unpin による独立ショートカットコマンド生成、エンジンの多段探索 + sha256 検証付きダウンロード

08検証バジェットの規律：ライフサイクル全体をカバーする bounded passes 上限設定により、終わりなき自己 QA ループを防止

3外部依存関係

Kind	Dependency / Endpoint
cli	impeccable 引擎（自含二进制，随 skill 的 scripts/impeccable launcher 定位/下载；技能通过 Bash 调用）
network	引擎二进制下载通道（仅首次且缺二进制时）：GitHub Releases，engine-v<version> 资产 + .sha256 sidecar
package	npx impeccable（SKILL 授权 Bash(npx impeccable *) 的发布安装路径；README quick start 亦用 npx impeccable install）
network	文档站/知识引用（非运行时调用）：impeccable.style、github.com/pbakaus/impeccable（README/docs 内链接）、google-labs-code/design.md spec（reference/document.md 内引用）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: skill/scripts/impeccable ランチャー（POSIX sh）→ エンジンバイナリ：context/detect/hooks/live
网络端点: 外部ネットワークアクセスの宣言: 初回エンジンバイナリのダウンロード：https://github.com/pbakaus/impeccable/releases/download/engine-v<
本地工作目录: ファイル読み書きと成果物出力: プロジェクト内：PRODUCT.md、DESIGN.md（+sidecar）、.impeccable/config.json および config.local.json

監査ノート： 影響範囲と動作特性：① 外部ネットワーク通信は単一かつ予測可能——初回実行時に作者の公式 GitHub Releases からエンジンバイナリをダウンロード（sha256 sidecar 検証、バージョン固定、フェイルクローズ設計、IMPECCABLE_BIN やオフライン事前配置による回避が可能）する標準的な公式配布経路。② ローカル変更範囲が広い：PRODUCT.md/DESIGN.md/.impeccable 設定の生成・更新、ホスト設定（.claude/settings.local.json 等）へのフックマニフェスト書き込み、UI 編集ごとの自動リンター実行。③ 認証情報の読み取りやサードパーティへのデータ送信はなし。留意事項：エンジンバイナリのサプライチェーン、フックの自動実行スコープ、live モードの注入動作について理解した上での利用が必要（デフォルトではユーザーによる明示的なインストール/有効化後にのみ機能）。

5二重目の独立検証

[ok] 单一 master 源 + 多宿主编译副本 — diff skill/SKILL.src.md 与 .cursor/.claude 副本：差异仅为占位符展开（{{scripts_path}}→宿主路径）、frontmatter 增删（version/argument-hint/allowed-tools）、 注释剥离；正文结构一致。
[ok] 每会话 context + 降级协议 — 编译副本与 src 均含 Setup 三步与 'Launcher unavailable' 段；引文逐字存在。
[ok] 引擎二进制下载仅首次且 fail-closed — launcher 第 60-200 行精读：候选顺序 IMPECCABLE_BIN→sibling bin→~/.impeccable/bin→version cache→PATH probe→下载；下载后必须 sha256 sidecar 匹配才 chmod+mv+exec，sidecar 不可得/不匹配/空文件均拒绝（exit 127）。
[ok] 61 规则与无 LLM 声明 — README 两处声明一致（'61 deterministic detector rules'、'no LLM and no API key'）；hooks.md 描述 per-edit 与 Stop 深扫两级；规则实体位于引擎二进制内（本仓库 skill 目录不含规则源码，属引擎发布物 [INFERENCE]）。
[ok] 23 命令数 — SKILL.md 命令表逐行计数 = 23（craft 为 deprecated alias 仍列）；与 README '23 commands' 一致。
[ok] hook 安装面与宿主 manifest — hooks.md 列出全部宿主清单路径（.claude/settings.local.json/.cursor/hooks.json/.codex/hooks.json/.github/hooks/impeccable.json/.grok/hooks/impeccable.json）；'reset' 动作会从 on 安装过的 manifest 移除条目。
[ok] live 仅限本地 + journal 恢复 — live.md 明确 'requires a local checkout'、'injection into deployed production sites (including HTTPS) is unsupported'；.impeccable/live/sessions/ journal 与 live-status/resume 流程存在。
[ok] 无凭证读取 — skill 目录（src/scripts/reference/agents + 编译副本）无 API key/token/secret/.env 读取代码；引擎行为以 README『no API key』声明 + 引文为据（引擎二进制内部未逐一审计 [INFERENCE]）。

6結論

単なるプロンプト指示にとどまらず、『デザイン品質』を決定論的リンター + ホストフック（編集時トリガー、不正な書き込みの事前ブロック）として工学的に実装している点。

二重ドキュメント権威モデル + 明確な上書き規律（brief wins / refinement preserves / redesign replaces）により、エージェントが自己の好みでユーザーの既定方針を上書きするのを防ぐ、デザインスキルとしては極めて堅牢な規律を備えている点。

コンパイル式マルチホスト配信により、20種類のホスト間で同一の動作を担保し、rule 注釈によるリリース時の一貫性自動検証など成熟したエンジニアリングガバナンスを実現している点。

ランチャーのダウンロード処理がフェイルクローズ（sha256 sidecar 検証 + バージョン固定 + 事前インストールによる回避可能）であり、通信先が限定され『sandboxes without egress preinstall the binary on PATH』と明記されている点。

障害時セマンティクスの設計：ランチャーのフォールバック、live ジャーナル復旧、CONTEXT_STALE の報告のみによる自動破壊防止、bounded passes による検証バジェットなど、ツール障害やデータ不整合に対する明確なリカバリパスが整備されている点。

最適な用途： 本格的なフロントエンドデザインやリファクタリングに取り組み、品質ゲートとしてエンジンやフックを導入することを受け入れられる AI コーディングユーザー（Claude Code/Cursor/Codex 等）；PRODUCT.md/DESIGN.md の二重ドキュメント運用を行っている、または導入したいチーム；決定論的なアクセシビリティ/品質チェックや『編集時トリガー』による防御を求めるエンジニアリングワークフロー；初回実行時にエンジンダウンロード用のインターネット接続（または事前インストール）が可能な環境。

不向きな用途： 純粋なバックエンド作業や非 UI タスク（説明文に 'Not for backend-only or non-UI tasks.' と明記）；ローカルでの自動フック実行や外部接続が一切禁止された完全閉域サンドボックス（hooks off + 手動 detect + 事前配置で緩和可能だが利便性は低下）；外部エンジンバイナリや作者固有の審美基準を許容できないゼロトラスト/ミニマル環境；制約的なデザイン規律よりも制約のない自由な生成を好むクリエイティブワークフロー。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload impeccable.tar.gz

sha256: 1467f7553455c007…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit cd12f8660e.