/claude-design-parity

明示的に呼び出された場合のみ実行します。 最新のClaude Designセッション出力と現在のプロジェクトを同期させ、実装の配線(状態ストア、ネイティブまたはIPCブリッジ、フック、モーションゲート)を保持します。

現在のリポジトリが.claude/skills/claude-design-parity-<stack>/SKILL.mdにスタック固有の特殊化を持っている場合は、最初のメッセージに表示し、それに従うかどうかを確認してください。この特殊化はリポジトリの不変式を直接認識しています。このジェネリックスキルはCLAUDE.mdとファイルツリーから推測します。

引数

• --first-port。実行を初回移植として扱います。プロジェクト受け入れチェックリストと実装スキャンに対して差分を実施し、不足している部分を移植してからスナップショットを書き込みます。このフラグなしの場合、初回実行はスナップショットのみ(移植なし)です。
• --dry-run。フェーズ0から2のみを実行し、パリティレポートを書き込んでから停止します。編集もコミットも行いません。

運用原則(セッション振り返りから)

これらは収束ループを圧縮します。毎回読んでください。これらをスキップすることは「ラウンド2、ラウンド3、ラウンド4」の再作業の主な原因です。

1. マッピングテーブルは仮説であり、仕様ではありません。 ファイル名推測(topbar.jsx -> ProjectTabs.tsx)は頻繁に間違い、実行を破壊します。移植計画を策定する前に、変更されたデザインソースファイルを全て最後まで読んでください。 各ファイルについて、エクスポート、トップレベルの状態、ハンドラー、レンダリング対象のインベントリを作成します。各エントリを実装対象にマッピングするか「MISSING」とマークします。その後でのみ移植を開始します。

2. サーフェスの唯一許可される仕様は<file>.jsx(または.tsxまたは.html)の行AからBです。 圧縮されたソースは嘘をつきます:

   • 受け入れチェックリストとロードマップ(FRONTEND-PORT.md、IMPLEMENTATION.md)は_選別されたサマリー_です。箇条書きに入らなかった項目は静かに削除されます。
   • スクリーンショットはロスがあります。
   • 散文の変更説明はパラフレーズされます。

   サーフェスを移植する際は、デザインファイルパスと行範囲をコミット本文に引用してください。スクリーンショットやロードマップの箇条書きから作業していることに気づいたら、ソースファイルを読んでください。

3. 視覚的忠実性と機能的忠実性は1パスではなく2パスです。

   • 「配線を保持する」は状態とブリッジ呼び出しを保護します。「視覚的変更を最小化する」という意味ではありません。
   • パスA、リテラル移植: <source>の行AからBのJSXまたはマークアップを実装ファイルにコピーします。マークアップ、構造、スタイル、コピー、サブコンポーネント。
   • パスB、再配線: プロジェクトの実際の状態セレクター、ネイティブまたはIPCブリッジ呼び出し、フック、モーションゲート(フェーズ0が発見したもの)を再度アタッチします。
   • これらをマージすると、デザイン移植ではなく既存実装の_リスタイル_が生成されます。

4. プロンプトとコミット構造はソース構造を反映します。 デザインソースファイルごと(またはファイル内の一貫したブロックごと)に1コミット。「トークン」「シェル」「ポーリッシュ」などのテーマグループを発明しないでください。サーフェスはカテゴリー間に落ちて削除されます。分類法はあなたの思考モデルではなく、デザインソースレイアウトです。

5. 初回通過の完璧さは目標ではありません。低い再作業での高速収束が目標です。 デザインエクスポートには、デモスキャフォルディング(uuidish()、モック状態、ハードコードされたlocalStorage[...])が含まれることが多く、リテラル移植できません。すべてのサーフェスは、リアルとデモの区別について判断が必要です。1から2ラウンドの補正を想定してください。初回で完璧を約束するのではなく、予算を確保してください。

6. 視覚検証は毎回自動化されます。 フェーズ5では、実装開発サーバーとデザインURLまたはHTMLエクスポートに対してscripts/parity-screenshot-diff.mjsを実行します。閾値を上回るピクセルデルタを持つルートは、調査されるまでサインオフをブロックします。オプトアウトはありません。これが、このスキルの「パリティ」の意味です。

フェーズ0: プロジェクト検出

何をする前に、プロジェクトを読んでその規約を学んでください。仮定しないでください。

1. リポジトリルートのCLAUDE.mdがある場合は読んでください。注記:

   • 記録の状態ストア(Zustand、Redux、Jotai、signals等)
   • 状態イディオム規則(例:新しい参照セレクター用のZustand useShallow)
   • ネイティブまたはIPCブリッジモジュール(Tauri、Electron、Capacitor、Expo、web)
   • モーションゲーティングヘルパー(useReducedMotion、CSS prefers-reduced-motion等)
   • スタイリングイディオム(Tailwinde ユーティリティ対インラインCSS変数対CSSモジュール)
   • コンポーネントレイアウト(例:src/panes/対src/pages/対src/routes/)
   • 禁止パターン(no any、no エラーバウンダリー、no 特定ライブラリ等)
   • 起動およびチェックコマンド

2. package.json scriptsを読んで以下を見つけてください:

   • 開発ランチャー(例:npm run dev、npm run tauri:dev、npm start、expo start)
   • 型チェック(例:npm run typecheck、tsc --noEmit)
   • ネイティブビルドチェック(該当する場合)(例:Tauri用cargo check、ネイティブ用xcodebuild)

3. docs/design/をリストして、プロジェクトのインテーク規約を探してください:

   • README.md。プロトコルドキュメント。
   • CHANGELOG.md。パイプ区切りのインポートログ。
   • CURRENT.md。最新仕様へのポインター。
   • specs/。スタンドアロンHTMLエクスポート。
   • handoffs/YYYY-MM-DD/。マルチファイルハンドオフバンドル。
   • scripts/import-design.shまたは類似。インテーク自動化。

   docs/design/が存在しない場合は、初回実行時に作成することにフォールバックし、上記の構造をミラーリングしてください。

4. 発見された規約を1段落でユーザーに言い直してください。フェーズ1に進む前に、何か間違っていないか訂正させます。

フェーズ1: 摂取

ユーザーに聞かずに新しいデザイン出力を見つけてください。

1. ~/Desktop(過去7日間)をスキャンして:

   • 正規のデザインソースフォルダー(例:lib_v*/、library/、design-system/)
   • プロジェクト名またはデザインに一致する*.html
   • FRONTEND-PORT.md、IMPLEMENTATION.md、STATUS.md、CHANGELOG-DESIGN.md
   • 上記のいずれかを含むフォルダー

   find ~/Desktop -maxdepth 3 -mtime -7 \( -name 'lib_v*' -o -name 'library' -o -iname '*design*.html' -o -name 'FRONTEND-PORT.md' -o -name 'IMPLEMENTATION.md' -o -name 'STATUS.md' -o -name 'CHANGELOG-DESIGN.md' \) 2>/dev/null
   

2. 複数の候補がある場合: mtimeと共にリストして、複数選択肢を提示します。

3. Desktopにゼロの場合: ~/Downloads(同じパターン、過去7日間)もチェックしてください。プロジェクトがオフリポアーカイブを持っている場合(docs/design/README.md参照、例:~/Documents/<project>-design-archive/)、そこの最新サブフォルダーをチェックしてください。それでも空の場合は、ユーザーに聞いてください。

4. 選択したバンドルをdocs/design/handoffs/YYYY-MM-DD/に移動またはコピーしてください。今日のフォルダーが既に存在する場合は、-2、-3等を付け加えます。

5. プロジェクトのオフリポアーカイブ(設定されている場合)にミラーリングしてください(docs/design/README.md参照)。

6. スタンドアロンHTMLエクスポートの場合、プロジェクトのインテークスクリプトがあれば優先してください(例:scripts/import-design.sh <path> --label "..." --summary "...")。フォルダーバンドルの場合は、手動移動と手動CHANGELOG.md行追加とCURRENT.md更新を行ってください。

フェーズ2: 差分

最後の同期以降に何が変更されたかを検出します。順序が重要です。スナップショット差分はファイルセットを狭め、その後それらのファイルを最後まで読んでください(運用原則#1)。受け入れチェックリストと変更ログは_クロスチェック_であり、仕様ではありません。

1. スナップショット差分。 リポジトリルートの.design-snapshot/を保守します(gitignore)。

   • 初回実行、--first-portなし: 受信した正規デザインソースフォルダーを.design-snapshot/にリテラルコピーし、「ベースラインが確立され、移植は実行されていない」という短いparity-report.mdを書き、フェーズ5ステップ1に進んで停止します。
   • --first-portでの初回実行: スナップショットをコピーして続行します。
   • 後続実行: diff -r .design-snapshot/<source>/ <handoff>/<source>/。追加、修正、削除されたすべてのファイルは候補です。

2. 変更されたすべてのデザインソースファイルを最後まで読んでください。 交渉の余地はありません。変更されたファイルごとに、パリティレポートに以下を書き込んでください:

   • インベントリ: すべてのエクスポートされたコンポーネント、すべての状態フック、すべてのハンドラー、すべてのレンダリング対象サーフェス(条件付きおよびサブツリーを含む)。
   • 各サーフェスの行範囲(コミットが<source>:A-Bを引用できるよう)。
   • デモスキャフォルディングフラグ: すべてのuuidish()、setTimeout、ハードコードされたlocalStorage[...]、モック配列をマークしてください。これらはリテラル移植できず、パスBで判断が必要です。
   • 各インベントリエントリの実装対象。 プロジェクトのコンポーネントレイアウト下のファイルパス、または現在の所有者がない場合はMISSING。

   このステップをスキップすることは、ドロップされたサーフェスの#1原因です。変更されたファイルが小さく見えても、スキップしないでください。

3. クロスチェック(仕様ではなく、確認する仮説):

   • CHANGELOG-DESIGN.md 新しいバンドル内。最後の同期以降のエントリ。
   • 受け入れチェックリスト(存在する場合)(FRONTEND-PORT.md §11、IMPLEMENTATION.md、STATUS.md)。
   • これらはステップ2のインベントリと相互参照されます。箇条書きがソースより少ないことを示す場合、ソースが勝ちます。ソースが箇条書きが言及していないサーフェスを持つ場合、とにかく移植してください。

4. クロスリファレンス インベントリをプロジェクトのコンポーネントレイアウトと比較してください。ステップ2で行ったファイル名ベースのマッピングは開始仮説です。インベントリはそれを確認するか、修正します。

CHANGE REPORTをdocs/design/handoffs/YYYY-MM-DD/parity-report.mdに書き込んでください:

# Parity Report、YYYY-MM-DD

## ファイルごとのインベントリ(運用原則#1)

### <source path>

- 行1-40: エクスポート(各々をリスト)
- 行A-B: <Surface name>。実装対象: <path>(またはMISSING)
- 行C-D: <Surface name>。実装対象: ...
- パスBで置き換えるデモスキャフォルディング: ...

(変更されたソースファイルごとに繰り返し)

## デザインで追加されたファイル(新しい実装が必要)

## デザインで修正されたファイル(実装パッチが必要、行範囲を含める)

## デザインで削除されたファイル(実装がクリーンアップが必要かもしれません)

## ソース内のサーフェスがチェックリスト箇条書きに表示されなかった

## 実装ギャップにマッピングされる受け入れチェックリストのチェックされていない項目

## 未処理の質問/曖昧性

フェーズ3: 明確化

レポートに任意の曖昧性がある場合(新しい機能、デザインと実装間の矛盾信号、複数の妥当な解釈)、コード記述前に複数選択肢の質問をしてください。

デザインと実装が不一致の場合の紛争ポリシー: 紛争ごとに一時停止と質問をしてください。自動解決しないでください。デザインが勝つと仮定しないでください。実装が勝つと仮定しないでください。紛争をリストし、2から4のオプションを提示し、待ってください。

レポートが曖昧でなく、小さい場合(コピー調整、色更新、ボタン1つ追加)、フェーズ4にスキップしてください。

--dry-runの場合: ここで停止します。パリティレポートが納品物です。

フェーズ4: 移植(ファイルごと2パス、決して1パスではない)

変更されたデザインソースファイルごと(運用原則#3と#4):

パスA: リテラル移植(視覚的忠実性)

<source>の行AからBのJSXまたはマークアップを実装ファイルにコピーしてください。ゴールは、ダミー状態が与えられたときに、レンダリングされたツリーがデザインと一致することです。

• マークアップ、構造、スタイル、コピー、サブコンポーネント。 記述されたとおりに移植します。フェーズ0で発見されたプロジェクトのスタイリングイディオムを保持してください(CSS変数からTailwindへ切り替えたり、その逆をしたりしないでください。明示的な要求でない限り)。
• デザインが先に進んだ場合、実装の過去のレイアウトを保持しないでください。 それはリスタイルであり、移植ではありません。レイアウトは仕様の一部です。
• ソースを引用してください。 コミット本文の<source>:A-Bをキャプチャしてください。

パスB: 再配線(機能的忠実性)

これでフェーズ0で記録された実際の配線を再度アタッチしてください:

• 状態ストア呼び出しと、イディオム規則(例:Zustand useShallow)
• ネイティブまたはIPCブリッジ呼び出し
• プロジェクト固有のフック(音声、地理位置情報、プッシュ等)
• モーションゲート(useReducedMotion()、prefers-reduced-motion)
• CLAUDE.mdの他の不変式

パスAではなく、ここでインベントリからのデモスキャフォルディングを置き換えてください。 フェーズ2ステップ2のインベントリがすでにそれをフラグしています:

• モックデータ用useState: 実際の状態セレクター
• 偽イベント用setTimeoutまたはsetInterval: 実際のイベント購読
• uuidish(): バックエンドからの実際のID
• ハードコードされたlocalStorage[...]: 実際の設定ストア
• モック配列: 実際のセレクターまたは空状態

対応するバックエンドがまだ存在しない場合:

• // TODO(parity): 実装されたときに<name>にワイヤーを残してください
• ギャップを、フェーズ5のヒューマンチェックリストに追加してください

デザインの新しいサーフェス

デザインソースが現在の実装所有者を持たないサーフェスを持つ場合(MISSINGインベントリ内)、プロジェクトのレイアウトに従って正しいフォルダーにスキャフォルドし、新しいファイルでパスA+パスBを実行してください。

コミット規律

• デザインソースファイルごと、またはファイル内の一貫したサブコンポーネントブロックごとに1コミット。 テーマグループを発明しないでください。

• [parity]プリフィックスの簡潔なメッセージ。

• コミット本文内の行引用。交渉の余地なし。 フォーマット:

  [parity] settings: port Appearance card
  
  Source: <design-source-path>:142-218
  Pass A: literal port of card markup plus accent swatches
  Pass B: theme plus accent -> useSettingsStore (useShallow); reduced-motion gate
  TODO(parity): transparency slider needs <command_name>
  

• コンセプトごと1コミット。マルチエリアの巨大コミットなし。

フェーズ5: スナップショット、検証、起動

1. .design-snapshot/を更新してください。 受信した正規デザインソースフォルダーを既存スナップショットの上にコピーしてください。

2. docs/design/CHANGELOG.mdを更新してください。着地したものをまとめた1行を追加します。

3. 静的ゲート フェーズ0での検出に基づいて:

   • 型チェック(例:npm run typecheck、tsc --noEmit)。
   • ネイティブチェック(該当する場合)(例:cargo check)。
   • プロジェクトに設定されている場合のLintとフォーマット。
   • いずれかが失敗した場合: 進む前に修正してください。

4. ブートテスト。 フェーズ0で検出された開発ランチャーを実行してください(例:npm run dev、npm run tauri:dev、expo start)。コンソールエラーなしで起動することを確認してください。

5. 視覚検証(必須)。 scripts/parity-screenshot-diff.mjsを実行してください:

   node <path-to>/scripts/parity-screenshot-diff.mjs \
     --design <path-or-url-to-design-source> \
     --impl http://localhost:<dev-port> \
     --viewports 375,768,1440 \
     --routes <comma-separated-list-of-routes> \
     --out docs/design/handoffs/YYYY-MM-DD/visual-diff/ \
     --threshold 0.005
   

   • スクリプトはreport.md、report.json、ルートごとの差分PNG、ルートごとのariaスナップショットを書き込みます。
   • report.mdを読んでください。status: regression(ミスマッチ比が閾値を超える)のルートはサインオフをブロックします。
   • 各リグレッション: 差分PNGを開き、デルタが意図的か(デザインが先に進み、実装が追いつく必要がある)、または意図しないか(移植ミス)を判断してください。意図しない場合は、修正して再実行してください。意図的な場合は、ヒューマンチェックリストに「予想されるデルタ、このサーフェスではデザインが実装より先」と根拠を記録してください。
   • スクリプトの終了コード: 0はパリティ検証、1はリグレッション調査、2または3はスクリプトレベルの失敗をCI機能フィード。

6. HUMAN VERIFICATION CHECKLIST を出力してください。 docs/design/handoffs/YYYY-MM-DD/human-check.mdに保存およびターミナルに出力します。導出元:

   • 変更されたサーフェスに触れた受け入れチェックリスト項目。
   • このラウンドからの新しい項目。
   • 視覚差分でリグレッションとしてフラグされたルート(差分PNGパス付き)。
   • Ariaスナップショットデルタの目を価値のあるもの(v0.1で手動レビュー)。
   • エリアでグループ化(Shell、Navigation、Pages、Components等)。
   • チェックボックス形式[ ]。
   • 末尾の**TODO(parity)**セクション。このラウンドで残されたすべての// TODO(parity)コメントをリスト。

7. 停止してください。 成功を宣言しないでください。ユーザーがチェックリストを実行するのを待ってください。

常に適用される規則

• 仕様はサマリーではなく、ソースファイルです。 コミット本文で<source>:A-Bを引用してください。受け入れチェックリスト箇条書き、スクリーンショット、散文変更説明に対してパッチしないでください。それらはクロスチェックです。
• 移植を策定する前に、変更されたデザインソースファイルを最後まで読んでください。スキップすることはドロップされたサーフェスの#1原因です。
• ファイルごと2パス: リテラル移植、次に再配線。 マージしないでください。デザインが先に進んだときに既存実装をリスタイルしないでください。
• デザインソースファイルごと1コミット。 テーマグループなし。
• ファイル名推測は仮説です。 マッピングにコミットする前にインベントリで確認してください。
• 初回通過の完璧さは目標ではありません。 低い再作業での高速収束が目標です。1から2ラウンドの補正を予算化してください。
• 自動視覚検証は毎回パリティ実行で実行されます。scripts/parity-screenshot-diff.mjs経由。ピクセルデルタが閾値を超えるルートは、調査されて修正されるか、記録されるまでヒューマンチェックリストサインオフをブロックします。
• 困ったときは複数選択肢の質問をしてください。ユーザーが呼び出すとき「とにかく続ける」と言わない限り。
• 紛争ポリシーは常に紛争ごとに一時停止と質問です。 決して自動解決しないでください。
• フェーズ0で発見されたプロジェクト規約を保持してください。 スタイリングイディオムをドリフトしないでください、プロジェクトが使用しないエラーバウンダリーを追加しないでください、プロジェクトがまだ採用していないライブラリを導入しないでください。
• すべての実行は、開発ランチャーがクリーンに起動し、parity-screenshot-diffが終了コード0または1(2または3ではない)で終了する状態でリポジトリを残します。
• コミット、コメント、出力に暴力的な言語はありません。

実行終了サマリー

1から2文のサマリーを出力: 何が着地したか、何が保留中か、完全なレポートはどこで読むか。その後停止します。

スタック固有の特殊化に従う時期

現在のリポジトリが`.claude/skills/claude-design-parity-<stack>/SKILL