chrome-extension

Chrome 拡張機能のベストプラクティス

Chrome 拡張機能（Manifest V3）の包括的なパフォーマンスおよびコード品質ガイドです。自動リファクタリングとコード生成の指針として、影響度順に優先順位付けされた12カテゴリ、67個のルールが含まれています。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• 新しい Chrome 拡張機能のコードを作成するとき
• Manifest V2 から Manifest V3 に移行するとき
• サービスワーカーのライフサイクルと状態管理を最適化するとき
• ページ操作用のコンテンツスクリプトを実装するとき
• 拡張機能のパフォーマンス問題をデバッグするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	サービスワーカーのライフサイクル	重大	sw-
2	コンテンツスクリプトの最適化	重大	content-
3	メッセージパッシングの効率化	高	msg-
4	ストレージ操作	高	storage-
5	ネットワークと権限	中～高	net-
6	メモリ管理	中	mem-
7	UI パフォーマンス	中	ui-
8	API の使用パターン	低～中	api-
9	コードスタイルと命名	中	style-
10	コンポーネントパターン	中	comp-
11	エラー処理	高	err-
12	テストパターン	中	test-

クイックリファレンス

1. サービスワーカーのライフサイクル（重大）

• sw-persist-state-storage - グローバル変数ではなく chrome.storage を使って状態を永続化する
• sw-avoid-keepalive - 人工的なサービスワーカーのキープアライブパターンを避ける
• sw-use-alarms-api - setTimeout/setInterval ではなく chrome.alarms を使う
• sw-return-true-async - 非同期レスポンスを返す場合、メッセージリスナーから true を返す
• sw-register-listeners-toplevel - イベントリスナーをトップレベルで登録する
• sw-use-offscreen-for-dom - DOM API にはオフスクリーンドキュメントを使う

2. コンテンツスクリプトの最適化（重大）

• content-use-specific-matches - URL マッチパターンを具体的に指定する
• content-use-document-idle - コンテンツスクリプトの挿入には document_idle を使う
• content-programmatic-injection - マニフェストでの宣言よりプログラムによる挿入を優先する
• content-minimize-script-size - コンテンツスクリプトのバンドルサイズを最小限に抑える
• content-batch-dom-operations - リフローを最小限に抑えるため、DOM 操作をまとめて行う
• content-use-mutation-observer - ポーリングではなく MutationObserver を使う

3. メッセージパッシングの効率化（高）

• msg-use-ports-for-frequent - 頻繁なメッセージ交換にはポート接続を使う
• msg-minimize-payload-size - メッセージのペイロードサイズを最小限に抑える
• msg-debounce-frequent-events - メッセージ送信前に高頻度イベントをデバウンスする
• msg-check-lasterror - 常に chrome.runtime.lastError を確認する
• msg-avoid-broadcast-to-all-tabs - すべてのタブへのメッセージのブロードキャストを避ける

4. ストレージ操作（高）

• storage-batch-operations - 個別に呼び出す代わりに、ストレージ操作をまとめて実行する
• storage-choose-correct-type - ユースケースに適したストレージの種類を選ぶ
• storage-cache-frequently-accessed - 頻繁にアクセスするストレージの値をキャッシュする
• storage-use-session-for-temp - 一時的な実行時データにはstorage.sessionを使用する
• storage-avoid-storing-large-blobs - 大きなバイナリデータの保存を避ける

5. ネットワークと権限（中～高）

• net-use-declarativenetrequest - webRequestではなくdeclarativeNetRequestを使用する
• net-request-minimal-permissions - 必要最小限の権限を要求する
• net-use-activetab - 広範なホスト権限ではなくactiveTab権限を使用する
• net-limit-csp-modifications - Content Security Policyヘッダーの変更を避ける

6. メモリ管理（中）

• mem-cleanup-event-listeners - コンテンツスクリプトのアンロード時にイベントリスナーをクリーンアップする
• mem-avoid-detached-dom - デタッチされたDOMノードへの参照を保持しない
• mem-avoid-closure-leaks - クロージャによる意図しないメモリリークを避ける
• mem-clear-intervals-timeouts - クリーンアップ時にインターバルとタイムアウトを解除する
• mem-use-weak-collections - DOM要素への参照にはWeakMapとWeakSetを使用する

7. UIパフォーマンス（中）

• ui-minimize-popup-bundle - 起動を速くするため、ポップアップのバンドルサイズを最小限にする
• ui-render-with-cached-data - まずキャッシュデータを使ってポップアップUIを描画する
• ui-batch-badge-updates - ちらつきを防ぐため、バッジの更新をまとめて行う
• ui-use-options-page-lazy - オプションページのセクションを遅延読み込みする

8. APIの使用パターン（低～中）

• api-use-promises-over-callbacks - コールバックよりもPromiseベースのAPI呼び出しを使用する
• api-query-tabs-efficiently - 特定のフィルターを指定してタブをクエリする
• api-avoid-redundant-api-calls - ループ内での重複したAPI呼び出しを避ける
• api-use-alarms-minperiod - alarms APIの最小期間を守る
• api-handle-context-invalidated - 拡張機能のコンテキストが無効化されたエラーに対処する
• api-use-declarative-content - ページアクションにはdeclarative content APIを使用する

9. コードスタイルと命名規則（MEDIUM）

• style-boolean-naming - 真偽値変数には is/has/should の接頭辞を使用する
• style-cache-naming - キャッシュ変数の命名を統一する
• style-constants - マジックナンバーには定数を定義する
• style-directory-structure - 機能またはレイヤーごとにコードを整理する
• style-file-naming - ファイルの命名規則を統一する
• style-function-naming - 関数には内容がわかる名前を付ける
• style-import-type - 型には型専用のインポートを使用する
• style-index-entry-points - モジュールのエントリーポイントにはインデックスファイルを使用する
• style-message-enums - メッセージの種類には列挙型を使用する
• style-type-naming - 型とインターフェースには PascalCase を使用する

10. コンポーネントのパターン（MEDIUM）

• comp-adapter-interface - ブラウザー API にはアダプターパターンを使用する
• comp-content-script-structure - コンテンツスクリプトの構造を統一する
• comp-css-class-patterns - BEM または接頭辞付きの CSS クラスを使用する
• comp-manager-class - 複雑な状態にはマネージャークラスを使用する
• comp-type-guards - 実行時の検証には型ガードを使用する
• comp-ui-components - 再利用可能な UI コンポーネントを作成する

11. エラー処理（HIGH）

• err-context-invalidation - 拡張機能のコンテキスト無効化に対処する
• err-early-return - エラー処理には早期リターンを使用する
• err-null-coalescing - デフォルト値には null 合体演算子を使用する
• err-promise-barrier - 同期には Promise バリアを使用する
• err-storage-operations - ストレージ操作の失敗に対処する
• err-url-parsing - try/catch を使って URL を安全に解析する
• err-validation-pattern - 境界で入力を検証する

12. テストのパターン（MEDIUM）

• test-browser-api-mocking - テストでは chrome API をモックする
• test-organization - 機能ごとにテストを整理する
• test-validation-functions - 検証関数を徹底的にテストする

使用方法

詳しい説明とコード例については、個々のリファレンスファイルをお読みください。

• セクション定義 - カテゴリー構成と影響度
• ルールテンプレート - 新しいルールを追加するためのテンプレート

完全版のドキュメント

すべてのルールを1つのドキュメントにまとめた完全なガイドについては、AGENTS.mdをご覧ください。

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールをまとめた完全版ガイド
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報