@aramassa/ai-rules 0.1.1-npmjs.20250910072942 → 0.1.5

package/artifact/instructions/planning.md

@@ -1,19 +1,200 @@
 ---
 type: planning
+category: methodology
+focus: structured-process
 ---
 
-## コミュニケーションのルール
+# プランニング手法とベストプラクティス
 
-### パスの指定について
+## 段階的プランニング手法
 
+### 4段階プランニングプロセス
+
+効果的なプランニングのために、以下の4段階のプロセスを順次実行します：
+
+#### Phase 1: 要件明確化
+**目的**: プロジェクトの目標と制約を明確化
+**手法**: 
+- 5W1H分析（Why, What, Who, When, Where, How）
+- ステークホルダー分析
+- 制約条件の洗い出し
+- 成功基準の定義
+
+**品質チェック**:
+- [ ] 背景と課題が具体的に説明されている
+- [ ] 成功基準が測定可能である
+- [ ] 制約条件が網羅されている
+
+#### Phase 2: 技術調査・分析  
+**目的**: 実装可能性と技術的リスクの評価
+**手法**:
+- システム影響分析（Impact Analysis）
+- 技術スタック調査
+- アーキテクチャ分析
+- 既存パターンの調査
+
+**品質チェック**:
+- [ ] 影響範囲が特定されている
+- [ ] 技術的選択肢が比較検討されている
+- [ ] リスクが定量的に評価されている
+
+#### Phase 3: 実装計画策定
+**目的**: 具体的で実行可能な計画の作成
+**手法**:
+- WBS（Work Breakdown Structure）
+- 依存関係分析
+- リソース見積もり
+- マイルストーン設定
+
+**品質チェック**:
+- [ ] タスクが適切に分解されている
+- [ ] 実装順序が論理的である
+- [ ] 工数見積もりが現実的である
+
+#### Phase 4: 品質保証・レビュー
+**目的**: プランの妥当性と品質の確保
+**手法**:
+- レビューチェックリスト
+- リスクアセスメント
+- 品質ゲート設定
+- 承認プロセス
+
+**品質チェック**:
+- [ ] プラン全体の一貫性が確保されている
+- [ ] リスクが適切に管理されている
+- [ ] レビュー観点が明確である
+
+## プランニング品質チェック項目
+
+### 完全性チェックリスト
+- [ ] **要件定義の完全性**
+  - すべてのステークホルダーが特定されている
+  - 機能要件・非機能要件が明確である
+  - 制約条件が網羅されている
+  - 前提条件が明記されている
+
+- [ ] **実装計画の詳細度**
+  - タスクが実行可能なレベルまで分解されている
+  - 各タスクの成果物が明確である
+  - 依存関係が正確に把握されている
+  - 工数見積もりが根拠とともに示されている
+
+- [ ] **テスト戦略の包括性**
+  - テストケースの方針が明確である
+  - テストデータの準備方法が決まっている
+  - テスト環境の準備が考慮されている
+  - 受け入れ基準が検証可能である
+
+### 実現可能性チェックリスト
+- [ ] **技術的実現可能性**
+  - 選択技術の成熟度と安定性
+  - チームの技術スキルとの適合性
+  - 既存システムとの整合性
+  - パフォーマンス・スケーラビリティ要件への対応
+
+- [ ] **リソース実現可能性**
+  - 必要な人的リソースの確保可能性
+  - 予算・コスト制約への適合
+  - 時間制約との整合性
+  - 外部依存の調整可能性
+
+- [ ] **運用実現可能性**
+  - 運用・保守体制での対応可能性
+  - 既存運用プロセスとの整合性
+  - 監視・アラート体制の確立可能性
+  - 障害対応・復旧手順の明確性
+
+### リスク評価・管理チェックリスト
+- [ ] **リスク特定の網羅性**
+  - 技術リスク（性能、互換性、セキュリティ等）
+  - プロジェクトリスク（スケジュール、リソース、スコープ等）
+  - ビジネスリスク（市場、法規制、競合等）
+  - 運用リスク（障害、保守、スケーラビリティ等）
+
+- [ ] **リスク対策の具体性**
+  - 各リスクの発生確率と影響度の評価
+  - 具体的な予防策・軽減策
+  - 事象発生時の対応策・復旧策
+  - リスク監視の方法・頻度
+
+## プロジェクトパターン別ベストプラクティス
+
+### CLI機能拡張パターン
+**特徴**: コマンドライン引数、オプション、出力フォーマットの拡張
+**重点確認項目**:
+- [ ] 既存オプションとの互換性維持
+- [ ] ヘルプメッセージの一貫性
+- [ ] エラーメッセージの適切性
+- [ ] 出力フォーマットの統一性
+
+### ライブラリ機能追加パターン  
+**特徴**: APIの拡張、新規モジュールの追加
+**重点確認項目**:
+- [ ] API設計の一貫性
+- [ ] 後方互換性の保証
+- [ ] TypeScript型定義の整合性
+- [ ] パッケージ依存関係の管理
+
+### リファクタリングパターン
+**特徴**: コード品質改善、構造最適化
+**重点確認項目**:
+- [ ] 外部インターフェースの不変性
+- [ ] 既存テストの継続実行可能性
+- [ ] パフォーマンスへの影響評価
+- [ ] 段階的移行の安全性
+
+### バグ修正パターン
+**特徴**: 問題解決、品質向上
+**重点確認項目**:
+- [ ] 根本原因の特定と対策
+- [ ] 再現手順と修正検証
+- [ ] 再発防止策の確立
+- [ ] 関連する潜在問題の調査
+
+## ドキュメント作成計画ガイドライン
+
+### 事前に計画すべきドキュメント
+- [ ] **技術仕様書**: システムの設計・アーキテクチャを記録
+- [ ] **ユーザーマニュアル**: エンドユーザー向けの操作ガイド
+- [ ] **API ドキュメント**: 開発者向けのAPIリファレンス  
+- [ ] **運用ドキュメント**: 保守・運用担当者向けの手順書
+- [ ] **テストドキュメント**: テスト仕様・結果・レポート
+
+### ドキュメント更新計画
+- **作成タイミング**: いつ作成・更新するか
+- **責任者**: 誰が作成・レビューするか
+- **フォーマット**: どの形式で作成するか
+- **配布・共有**: どこに配置・共有するか
+- **メンテナンス**: どのように最新性を保つか
+
+## プランニングワークフロー管理
+
+### todo_plans → change_plans → GitHub Issues の流れ
+
+#### 1. todo_plans段階
+- **目的**: アイデアの整理と初期プランニング
+- **期間**: プロジェクト開始前の計画策定期間
+- **成果物**: 詳細な実装計画書
+- **品質基準**: 4段階プランニングプロセスの完了
+
+#### 2. change_plans段階  
+- **目的**: 実装中の進捗管理と計画調整
+- **期間**: 実装開始から完了まで
+- **成果物**: 実装実績と学習内容の記録
+- **品質基準**: 計画の実行状況と乖離の記録
+
+#### 3. GitHub Issues段階
+- **目的**: チーム内での課題管理と進捗共有
+- **期間**: 公式な課題管理が必要な期間
+- **成果物**: Issue、Pull Request、レビュー記録
+- **品質基準**: ステークホルダーとの情報共有
+
+### コミュニケーションのルール
+
+#### パスの指定について
 相対パスはプロジェクトのルートディレクトリを基準に考えること。
 絶対パスはシステムのルートディレクトリを基準に考えること。
 
-例:
-- `docs/README.md` は、プロジェクトのルートディレクトリからの相対パス指定
-- `./docs/README.md` は、プロジェクトのルートディレクトリからの相対パス指定
-- `/docs/README.md` は、システムのルートディレクトリからのパス指定
-
 ### 根源的なルール
 
 - 機能追加のために不明な点があれば、追加で確認する

package/artifact/instructions/rules/development/chrome-extension-general.md

@@ -0,0 +1,121 @@
+---
+type: development-rules
+category: chrome-extension
+focus: architecture-security
+language: javascript
+applyTo: "**/*"
+---
+
+# Chrome Extension Manifest V3 - General Architecture & Security
+
+## 概要
+
+Chrome 拡張機能開発における Manifest V3 (MV3) の全般的なアーキテクチャ原則とセキュリティ指針を定義します。
+MV3 は単なるバージョンアップではなく、セキュリティ、パフォーマンス、プライバシーを根本的に強化する
+アーキテクチャの転換を意味します。
+
+## 1. Manifest V3 アーキテクチャ原則
+
+### 1.1 基本設計思想
+
+- **イベント駆動型アーキテクチャ**: 永続的なバックグラウンドページから短命な Service Worker への移行
+- **宣言的セキュリティモデル**: 動的なコード実行から事前定義されたルールベースへの移行
+- **最小権限の原則**: 必要最小限の権限のみを要求し、明確に宣言する
+- **関心の分離**: 各コンポーネントが明確な役割を持つ構造化されたアーキテクチャ
+
+### 1.2 コアコンポーネント
+
+Chrome Extension MV3 アーキテクチャは4つの主要コンポーネントで構成されます：
+
+- **Service Worker (Background)**: イベント駆動型のバックグラウンド処理を担当し、永続的な状態を持たない短命な実行環境
+- **Content Scripts**: ウェブページの DOM に直接アクセスし、ページコンテンツとの相互作用を処理
+- **Action Popup**: ユーザーインターフェースレイヤーとして、拡張機能アイコンクリック時の UI を提供
+- **Offscreen Documents**: Service Worker から DOM 操作や特殊 API アクセスが必要な場合のヘルパー環境
+
+これらのコンポーネントは明確に分離された実行コンテキストを持ち、メッセージパッシングによって連携します。
+
+## 2. セキュリティベストプラクティス
+
+### 2.1 Content Security Policy (CSP)
+
+Manifest V3 では Content Security Policy の設定が必須であり、拡張機能のセキュリティを大幅に強化します。
+
+**extension_pages**: 拡張機能内のページ（popup、options等）に適用される CSP です。script-src 'self' でパッケージ内のスクリプトのみを許可し、object-src 'self' で安全なオブジェクト読み込みを制限し、img-src には 'self' data: https: で画像ソースを限定します。
+
+**sandbox**: サンドボックス環境での CSP 設定です。sandbox allow-scripts で基本的なスクリプト実行を許可し、必要に応じて 'unsafe-eval' や 'unsafe-inline' を追加しますが、セキュリティリスクを十分に検討します。
+
+manifest.json の content_security_policy セクションで両方の設定を明示的に定義し、拡張機能の実行環境を適切に制限します。
+
+### 2.2 セキュリティ原則
+
+Manifest V3 では厳格なセキュリティ原則の遵守が必須です。
+
+**リモートコードの禁止**: すべての JavaScript コードは拡張機能パッケージに含める必要があり、外部からの動的コード読み込みは許可されません。CDN からのライブラリ読み込みも禁止されているため、必要なライブラリはパッケージにバンドルします。
+
+**eval() の回避**: eval()、Function コンストラクタ、setTimeout/setInterval の文字列実行など、動的コード実行は禁止されています。静的な実装で代替手段を検討します。
+
+**入力検証**: ユーザー入力とウェブページからのデータは信頼せず、適切に検証・サニタイゼーションを実行します。XSS 攻撃や インジェクション攻撃を防ぐため、HTML エスケープや URL 検証を徹底します。
+
+**権限の最小化**: 必要最小限の権限のみを要求し、host_permissions は具体的なドメインに限定します。広範囲な権限（<all_urls> 等）は避け、機能に応じて段階的に権限を要求します。
+
+InputValidator クラスでは URL の妥当性検証（プロトコル確認、URL 形式チェック）、HTML のサニタイゼーション（textContent を使用したエスケープ）、メッセージデータの検証（型チェック、必須フィールド確認）を統一的に実装します。
+
+## 3. 開発ワークフロー
+
+### 3.1 開発環境セットアップ
+
+Chrome 拡張機能開発では適切なビルドツールと依存関係の設定が重要です。
+
+**プロジェクト初期化**: npm init -y でプロジェクトを初期化し、package.json を作成します。
+
+**必須開発依存関係**: webpack と webpack-cli でモジュールバンドリングを設定し、copy-webpack-plugin で静的ファイル（manifest.json、HTML、アイコン等）のコピーを自動化します。eslint でコード品質を管理し、jest でユニットテスト、puppeteer で E2E テストを実行します。
+
+**webpack 設定**: entry ポイントで各コンポーネント（background、content、popup、offscreen）を個別に定義し、output で dist ディレクトリに出力します。CopyPlugin で必要な静的ファイルを適切な場所にコピーし、開発用とプロダクション用の設定を分離します。
+
+webpack.config.js では mode で開発・本番を切り替え、各 JavaScript ファイルの依存関係を解決してバンドルします。プラグイン設定で manifest.json、HTML ファイル、アイコンディレクトリを適切にコピーします。
+
+### 3.2 ビルドスクリプト
+
+package.json の scripts セクションで開発・ビルド・テスト・デプロイのワークフローを定義します。
+
+**build**: webpack でプロダクションモードのビルドを実行し、最適化されたファイルを dist ディレクトリに出力します。
+
+**dev**: webpack の watch モードで開発時の自動リビルドを有効化し、ファイル変更時に即座に再ビルドを実行します。
+
+**test**: jest でユニットテストを実行し、コードの品質と動作を確認します。
+
+**lint**: eslint で src ディレクトリ下の JavaScript ファイルの静的解析を実行し、コーディング規約の遵守を確認します。
+
+**pack**: ビルド後に dist ディレクトリで zip 圧縮を実行し、Chrome Web Store 提出用のパッケージファイル（extension.zip）を作成します。
+
+これらのスクリプトにより、開発からデプロイまでの一連の作業を自動化し、効率的な開発ワークフローを確立します。
+
+## 4. デバッグとトラブルシューティング
+
+### 4.1 一般的な問題と解決策
+
+**Service Worker の非アクティブ化**
+- 問題: Service Worker が予期せず終了する
+- 解決: イベントハンドラーの適切な設定、非同期処理の Promise 管理
+
+**メッセージパッシングエラー**
+- 問題: `Error: Could not establish connection. Receiving end does not exist.`
+- 解決: 送信先の存在確認、エラーハンドリングの実装
+
+**権限エラー**
+- 問題: 必要な権限が不足している
+- 解決: manifest.json の権限設定見直し、動的権限要求の実装
+
+## まとめ
+
+Manifest V3 への移行は、Chrome 拡張機能開発における重要な転換点です。このガイドで示したパターンとベストプラクティスに従うことで、セキュアで高性能、かつ将来性のある拡張機能を開発できます。
+
+### 重要なポイント
+
+1. **イベント駆動型設計**: Service Worker の短命な性質を受け入れ、適切なイベントハンドリングを実装する
+2. **宣言的セキュリティ**: declarativeNetRequest API を活用し、セキュアなネットワーク制御を実現する  
+3. **適切な分離**: 各コンポーネントの役割を明確にし、メッセージパッシングで連携させる
+4. **最小権限**: 必要最小限の権限のみを要求し、透明性を確保する
+5. **テスト駆動**: 包括的なテスト戦略で品質を保証する
+
+これらの原則に従って開発することで、ユーザーに安全で快適な拡張機能体験を提供できます。

package/artifact/instructions/rules/development/chrome-extension-html.md

@@ -0,0 +1,157 @@
+---
+type: development-rules
+category: chrome-extension
+focus: html-structure
+language: html
+applyTo: "**/*.html"
+---
+
+# Chrome Extension Manifest V3 - HTML Structure Guidelines
+
+## Popup HTML 構造
+
+### 基本構造
+
+Chrome 拡張機能の popup.html は軽量で高速な UI 体験を提供する必要があります。
+
+**HTML5 基本構造**: 
+```html
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>拡張機能名</title>
+  <link rel="stylesheet" href="popup.css">
+</head>
+<body>
+  <div class="container">
+    <!-- UI コンテンツ -->
+  </div>
+  <script src="popup.js"></script>
+</body>
+</html>
+```
+
+**寸法制限**: ポップアップは最大 800px × 600px のサイズ制限があり、適切なレスポンシブデザインが必要です。
+
+**読み込み最適化**: CSS と JavaScript は外部ファイルとして分離し、インライン記述は避けます。CSP の制約により、インラインスクリプトとスタイルは許可されません。
+
+### UI/UX 設計原則
+
+**シンプルな構造**: 複雑なレイアウトは避け、ユーザーが直感的に操作できるシンプルな構造にします。
+
+**高速レンダリング**: 重いアニメーションや大量の DOM 要素は避け、ポップアップの表示速度を優先します。
+
+**アクセシビリティ**: 適切な semantic HTML、ARIA 属性、キーボードナビゲーションをサポートします。
+
+## Options Page 構造
+
+### 設定ページの実装
+
+Options Page は拡張機能の詳細設定を提供する専用ページです。
+
+**manifest.json 設定**:
+```json
+{
+  "options_page": "options.html",
+  "options_ui": {
+    "page": "options.html",
+    "open_in_tab": true
+  }
+}
+```
+
+**HTML 構造**:
+```html
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>拡張機能設定</title>
+  <link rel="stylesheet" href="options.css">
+</head>
+<body>
+  <div class="settings-container">
+    <h1>設定</h1>
+    <form id="settingsForm">
+      <!-- 設定項目 -->
+    </form>
+  </div>
+  <script src="options.js"></script>
+</body>
+</html>
+```
+
+**設定の永続化**: フォームデータは chrome.storage.sync を使用してデバイス間で同期し、設定の一貫性を保ちます。
+
+## Offscreen Document 構造
+
+### HTML 実装
+
+Offscreen ドキュメントは通常の HTML ファイルとして実装され、DOM API や特殊ブラウザ API にアクセスします。
+
+**HTML 構造**: 基本的な HTML5 ドキュメント構造で、必要な JavaScript ファイルを読み込みます。UI は不要なため、視覚的要素は最小限に抑えます。
+
+```html
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Offscreen Document</title>
+</head>
+<body>
+  <!-- 視覚的要素は最小限 -->
+  <div id="workspace" style="display: none;"></div>
+  <script src="offscreen.js"></script>
+</body>
+</html>
+```
+
+**メッセージ受信**: chrome.runtime.onMessage.addListener でメッセージを受信し、target フィールドが 'offscreen' の場合のみ処理します。非同期処理では return true を設定して適切なレスポンス管理を行います。
+
+**DOM 操作**: DOMParser を使用した HTML パース、Document インターフェースでの要素抽出、各種 DOM API の活用が可能です。Service Worker では実行できない DOM 操作をここで実行します。
+
+**特殊 API**: navigator.clipboard でクリップボード操作、Audio API で音声再生、その他ブラウザ固有 API の実行が可能です。
+
+**エラーハンドリング**: すべての操作は try-catch でラップし、エラー発生時は適切なエラーレスポンスを Service Worker に返します。
+
+OffscreenDocument クラスでは各種操作（HTML パース、クリップボード、音声再生等）を統一的なインターフェースで提供し、Service Worker からの要求に応じて適切な処理を実行します。
+
+## HTML セキュリティベストプラクティス
+
+### Content Security Policy (CSP) 遵守
+
+**インラインスクリプト禁止**: `<script>` タグ内でのインラインコードは CSP により禁止されているため、すべての JavaScript は外部ファイルに記述します。
+
+**インラインスタイル禁止**: `style` 属性でのインラインスタイルも禁止されているため、すべての CSS は外部ファイルに記述します。
+
+**外部リソース制限**: 外部サイトからの画像、スクリプト、スタイルシートの読み込みは制限されているため、必要なリソースは拡張機能パッケージに含めます。
+
+### XSS 対策
+
+**動的コンテンツの安全な挿入**: ユーザー入力や外部データを HTML に挿入する際は、textContent や innerText を使用してエスケープし、innerHTML の使用は避けます。
+
+**URL 検証**: 外部リンクや画像 URL は適切に検証し、信頼できるドメインのみを許可します。
+
+**データ検証**: フォーム入力やメッセージデータは適切に検証・サニタイゼーションを実行します。
+
+## パフォーマンス最適化
+
+### 軽量化
+
+**最小限の DOM**: 不要な HTML 要素は削除し、シンプルな構造を保ちます。
+
+**CSS 最適化**: 使用していない CSS ルールを削除し、ファイルサイズを最小化します。
+
+**JavaScript 分離**: 機能ごとに JavaScript ファイルを分離し、必要な部分のみを読み込みます。
+
+### 読み込み最適化
+
+**リソース並列読み込み**: CSS と JavaScript の読み込みを並列化し、ページ表示速度を向上させます。
+
+**画像最適化**: アイコンや画像は適切なサイズと形式で最適化し、読み込み時間を短縮します。
+
+**キャッシュ活用**: 静的リソースは適切にキャッシュされるよう設定し、再読み込み時間を短縮します。