@aramassa/ai-rules 0.3.3 → 0.3.4

package/artifact/prompts/ai-rules/for_recipe.md

@@ -26,16 +26,117 @@ AI-rules プロジェクトにおけるレシピファイル（recipe files）
 
 ### 実行タスク
 
-#### 手順1: 要件分析とファイル調査
+#### 手順1: 事前確認とフィルター属性の検証 ⚠️**必須**
+
+**1-1. 利用可能な属性の事前確認（必須）**
+
+レシピファイル作成前に、必ず以下のコマンドでfrontmatter属性を確認してください：
+
+```bash
+# 全ての利用可能な属性と値を確認
+npx ai-rules stats --src artifact
+
+# 特定の属性値でマッチするファイルを事前確認
+npx ai-rules extract --type coding-rules --src artifact --out /tmp/test.md
+npx ai-rules extract --attr category=configuration --src artifact --out /tmp/test.md
+npx ai-rules extract --language typescript --src artifact --out /tmp/test.md
+```
+
+**1-2. 事前確認チェックリスト**
+- [ ] **属性存在確認**: 指定したい属性（category, focus等）が実際のファイルに存在するか
+- [ ] **属性値確認**: 期待する値（例：category=best-practices）が実際に使われているか  
+- [ ] **対象ファイル数確認**: フィルター適用後に期待するファイル数が抽出されるか
+- [ ] **意図しないファイル混入確認**: 不要なファイルが含まれていないか
+
+**1-3. 実際の利用可能な属性値（2025年1月時点）**
+
+以下は `npx ai-rules stats --src artifact` の結果に基づく実際の値です：
+
+**type属性の値（18種類）**
+- `chatmode` (3) - チャットモード設定
+- `coding-rules` (3) - コーディング規約  
+- `development-rules` (7) - 開発ルール全般
+- `development` (2) - 開発関連
+- `documentation` (3) - ドキュメント作成
+- `documentation-ai` (4) - AI向けドキュメント
+- `git-rules` (1) - Git関連ルール
+- `infrastructure` (1) - インフラ設定
+- `package-management` (1) - パッケージ管理
+- `planning` (2) - プランニング関連
+- `prompt` (3) - プロンプト設定
+- `python-cli` (1) - Python CLI開発
+- `retrospective` (1) - 振り返り分析  
+- `skel` (1) - スケルトン管理
+- `test` (6) - テスト関連
+- `tidying-up` (1) - 整理整頓
+- `workspace-management` (1) - ワークスペース管理
+
+**category属性の値（21種類）**
+- `best-practices` (2) - ベストプラクティス
+- `configuration` (2) - 設定管理
+- `methodology` (1) - 手法・方法論
+- `implementation` (1) - 実装関連
+- `api-usage` (1) - API使用方法
+- `configuration-management` (1) - 設定管理
+- `chrome-extension` (4) - Chrome拡張開発
+- `code-quality` (1) - コード品質
+- `desktop-app` (1) - デスクトップアプリ
+- `github` (1) - GitHub関連  
+- `github-protection` (1) - GitHub保護設定
+- `github-actions` (1) - GitHub Actions
+- `restrictions` (1) - 制約・制限
+- `content-creation` (1) - コンテンツ作成
+- `instruction-generation` (1) - インストラクション生成
+- `todo-planning` (1) - TODO計画
+
+**focus属性の値（17種類）**
+- `structured-process` (1) - 構造化プロセス
+- `timeout` (2) - タイムアウト設定
+- `structure` (1) - 構造設計
+- `uv-workspace` (1) - uvワークスペース
+- `cli-development` (1) - CLI開発
+- `openai` (1) - OpenAI関連
+- `architecture-security` (1) - アーキテクチャセキュリティ
+- `html-structure` (1) - HTML構造
+- `javascript-patterns` (1) - JavaScriptパターン
+- `manifest-configuration` (1) - マニフェスト設定
+- `mandatory-tools` (1) - 必須ツール
+- `electron` (1) - Electron開発
+- `issue-templates` (1) - Issueテンプレート
+- `file-protection` (1) - ファイル保護
+- `environment-independence` (1) - 環境非依存
+- `test-policy` (1) - テストポリシー
+- `workflow-management` (1) - ワークフロー管理
+
+**language属性の値（8種類）**
+- `typescript` (3) - TypeScript
+- `javascript` (3) - JavaScript  
+- `python` (2) - Python
+- `nodejs,typescript` (1) - Node.js + TypeScript組み合わせ
+- `typescript,nodejs` (3) - TypeScript + Node.js組み合わせ
+- `typescript,javascript` (1) - TypeScript + JavaScript組み合わせ
+- `ansible` (1) - Ansible
+- `html` (1) - HTML
+- `json` (1) - JSON
+
+**その他の属性**
+- `applyTo`: ファイルパターン (`"**/*.ts"`, `"**/manifest.json"` など)
+- `chatmode`: チャットモード種別 (`bug-reproduce`, `instruction-improve`, `planning`)
+- `framework`: フレームワーク (`electron`, `npm`, `rollup`, `bdd`)
+- `target`: 対象 (`ai`, `human`)
+- `dir`: ディレクトリ (`docs-ai/external`, `docs-ai/history` など)
+- `tools`: 利用ツール (長いカンマ区切りリスト)
+
+**1-4. 要件分析とファイル調査**
 
 **ファイル構成の調査**
-1. 利用可能なinstructionファイルを確認
-2. 各ファイルのfrontmatter属性（type、language、category、focus等）を分析
+1. 上記の実際の属性値を参考に、必要なファイル群を特定
+2. 各ファイルのfrontmatter属性を `stats` コマンドで分析
 3. 既存のプリセットレシピを参考として確認
 
 **要件の明確化**
 - 生成するドキュメントの目的と対象読者
-- 必要なinstruction種別とフィルタリング条件
+- 必要なinstruction種別とフィルタリング条件（実際の値を使用）
 - 出力ファイル構成と配置場所
 - FrontMatter継承とカスタム属性の必要性
 
@@ -111,29 +212,203 @@ recipe:
     out: "custom-rules.instructions.md"
 ```
 
-#### 手順3: フィルタリング条件の設定
+#### 手順3: フィルタリング条件の設定（実際の属性値使用）
+
+**⚠️ 重要**: 以下の例は実際の `npx ai-rules stats --src artifact` の結果に基づいています。
+
+**標準フィルター（基本）**
+```yaml
+type: coding-rules                    # 実際の値: coding-rules, test, documentation など  
+language: typescript                  # 実際の値: typescript, javascript, python など
+```
+
+**標準フィルター（配列指定）**
+```yaml
+type: [coding-rules, development-rules]  # 複数のタイプを指定（OR条件）
+language: [typescript, javascript]      # 複数の言語を指定（OR条件）  
+```
+
+**高度なフィルター（filters フィールド）**
+```yaml
+filters:
+  category: best-practices          # 実際の値: configuration, best-practices, methodology など
+  focus: timeout                   # 実際の値: timeout, structure, validation など  
+  applyTo: "**/*.ts"              # ファイルパターン指定
+  chatmode: bug-reproduce         # 実際の値: bug-reproduce, instruction-improve, planning
+  framework: electron             # 実際の値: electron, npm, rollup, bdd
+  target: ai                      # 実際の値: ai, human
+```
+
+**実用的な組み合わせ例**
+
+1. **TypeScriptコーディングルール**
+```yaml
+type: coding-rules
+language: typescript 
+filters:
+  category: best-practices
+# 結果: TypeScriptのベストプラクティスに関するコーディングルール
+```
+
+2. **テストに関する設定（タイムアウト関連）**
+```yaml
+type: test
+filters:
+  focus: timeout
+# 結果: テスト関連でタイムアウトにフォーカスした設定
+```
+
+3. **Chrome拡張開発ルール**
+```yaml  
+filters:
+  category: chrome-extension
+  focus: manifest-configuration
+# 結果: Chrome拡張開発のマニフェスト設定関連
+```
 
-**標準フィルター**
+4. **AI向けドキュメント**
 ```yaml
-type: [instruction-type]        # 単一値または配列
-language: [target-language]     # 単一値または配列
+type: documentation-ai
+filters:
+  target: ai
+  dir: docs-ai/internal
+# 結果: 内部AI向けドキュメント
 ```
 
-**高度なフィルター**
+**配列値サポート（OR条件）**
 ```yaml
 filters:
-  category: [category-value]    # カテゴリによる絞り込み
-  focus: [focus-area]          # フォーカス領域による絞り込み
-  applyTo: [file-pattern]      # ファイルパターンによる絞り込み
-  [custom-attr]: [value]       # カスタム属性による絞り込み
+  focus:
+    - timeout
+    - structure  
+    - validation
+  category:
+    - configuration
+    - best-practices
+# 結果: focus は timeout OR structure OR validation
+#      AND category は configuration OR best-practices
 ```
 
-**配列値サポート**
+**複合条件（AND条件）**
 - フィルター値は単一値または配列を指定可能
-- 配列の場合はOR条件（いずれかにマッチ）
+- 配列内の値はOR条件（いずれかにマッチ）  
 - 複数フィルター間はAND条件（すべてにマッチ）
+- `type`/`language` と `filters` の組み合わせもAND条件
+
+#### 手順4: レシピ作成の推奨ワークフロー ⚠️**必須手順**
+
+**4-1. 属性確認を含む完全なワークフロー**
+
+```markdown
+## レシピ作成ワークフロー（推奨）
+
+### Phase 1: 要件明確化
+1. **目的設定**: どのようなファイル群を対象にしたいかを決定
+2. **対象範囲特定**: 必要なinstruction種別を明確化
+
+### Phase 2: 属性調査（重要）
+3. **利用可能属性確認**: `npx ai-rules stats --src artifact` で現在の属性を調査
+4. **フィルター条件設計**: 対象ファイルを絞り込む条件を設計
+
+### Phase 3: 事前検証（必須）
+5. **個別フィルター検証**: 各フィルター条件を個別にテスト
+6. **組み合わせ検証**: 複数フィルターの組み合わせをテスト
+7. **結果確認**: 期待するファイル数・内容が取得できるか確認
+
+### Phase 4: レシピ作成・実行
+8. **レシピファイル作成**: 検証済みの条件でレシピファイルを作成
+9. **最終実行**: レシピを実行して期待通りの結果になるかを確認
+10. **品質チェック**: 生成されたドキュメントの内容を確認
+```
 
-#### 手順4: 出力設定とモード指定
+**4-2. 属性検証の具体的コマンド例**
+
+```bash
+# Step 1: 全体の属性状況を把握
+npx ai-rules stats --src artifact
+
+# Step 2: 個別条件のテスト（ファイル数を確認）
+npx ai-rules extract --type coding-rules --src artifact --out /tmp/test-type.md
+echo "Coding rules files: $(wc -l < /tmp/test-type.md) lines"
+
+npx ai-rules extract --language typescript --src artifact --out /tmp/test-lang.md  
+echo "TypeScript files: $(wc -l < /tmp/test-lang.md) lines"
+
+npx ai-rules extract --attr category=best-practices --src artifact --out /tmp/test-cat.md
+echo "Best practices files: $(wc -l < /tmp/test-cat.md) lines"
+
+npx ai-rules extract --attr focus=timeout --src artifact --out /tmp/test-focus.md
+echo "Timeout focus files: $(wc -l < /tmp/test-focus.md) lines"
+
+# Step 3: 組み合わせ条件のテスト
+npx ai-rules extract --type test --attr focus=timeout --src artifact --out /tmp/test-combo.md
+echo "Test + timeout files: $(wc -l < /tmp/test-combo.md) lines"
+
+# Step 4: 結果内容の確認
+head -20 /tmp/test-combo.md  # 実際の内容を確認
+```
+
+**4-3. よくある検証パターン**
+
+**パターンA: TypeScript開発ルール**
+```bash
+# 事前検証
+npx ai-rules stats --src artifact | grep -A5 "type:"    # typeの値確認
+npx ai-rules stats --src artifact | grep -A10 "language:" # languageの値確認
+
+# フィルターテスト
+npx ai-rules extract --type coding-rules --language typescript --src artifact --out /tmp/ts-test.md
+echo "Result: $(wc -l < /tmp/ts-test.md) lines matched"
+
+# 期待結果: TypeScriptのコーディングルールファイルが取得される
+```
+
+**パターンB: 設定管理関連**  
+```bash
+# 事前検証
+npx ai-rules stats --src artifact | grep -A15 "category:" # categoryの値確認
+
+# フィルターテスト
+npx ai-rules extract --attr category=configuration --src artifact --out /tmp/config-test.md
+echo "Configuration files: $(wc -l < /tmp/config-test.md) lines"
+
+# 期待結果: 設定管理関連のファイルが取得される
+```
+
+**パターンC: 複合条件テスト**
+```bash
+# 複数条件の検証
+npx ai-rules extract --type test --attr focus=timeout,category=best-practices --src artifact --out /tmp/complex-test.md
+echo "Complex filter result: $(wc -l < /tmp/complex-test.md) lines"
+
+# 期待結果: テスト関連 AND タイムアウトフォーカス AND ベストプラクティスのファイル
+```
+
+**4-4. 検証時のトラブルシューティング**
+
+**空の結果が返される場合**
+```bash
+# 原因調査
+npx ai-rules stats --src artifact | grep "focus:" -A20  # focusの実際の値を確認
+npx ai-rules stats --src artifact | grep "category:" -A20 # categoryの実際の値を確認
+
+# 個別条件で段階的にテスト
+npx ai-rules extract --attr focus=timeout --src artifact --out /tmp/debug1.md
+npx ai-rules extract --attr category=configuration --src artifact --out /tmp/debug2.md
+
+# 結果比較
+ls -la /tmp/debug*.md  # ファイルサイズを比較
+```
+
+**期待と異なるファイルが含まれる場合**
+```bash  
+# 実際にマッチしたファイルの確認
+npx ai-rules extract --type coding-rules --src artifact --out /tmp/check.md
+grep "^#" /tmp/check.md | head -10  # ヘッダーを確認してファイル名を特定
+
+# 特定ファイルのfrontmatterを確認
+head -15 artifact/path/to/specific/file.md  # frontmatter部分を直接確認
+```
 
 **出力ファイル設定**
 ```yaml
@@ -162,7 +437,7 @@ recipe:
 - 同じoutputファイルに複数アイテムが出力される場合、2番目以降は自動的にappendモード
 - 明示的にmodeを指定することで上書き可能
 
-#### 手順5: FrontMatter とメタデータ設計
+#### 手順6: FrontMatter とメタデータ設計
 
 **直接指定方式**
 ```yaml
@@ -185,7 +460,7 @@ frontmatter:
 - 配列: すべての要素を結合
 - オブジェクト: 後の値で上書き
 
-#### 手順6: インポートと拡張性
+#### 手順7: インポートと拡張性
 
 **プリセット活用**
 ```yaml
@@ -310,7 +585,7 @@ recipe:
       applyTo: "**/*"
 ```
 
-#### TypeScriptプロジェクト向け
+#### TypeScriptプロジェクト向け（実際の属性値使用）
 
 ```yaml
 # TypeScript project comprehensive rules
@@ -323,19 +598,18 @@ recipe:
   
   - title: "Custom TypeScript Rules"
     out: "custom-typescript.instructions.md"  # ファイル名のみ
-    type: coding-rules
-    language: typescript
+    type: coding-rules                         # 実際の値を使用
+    language: typescript                       # 実際の値を使用
     filters:
-      focus: 
-        - testing
-        - performance
+      category: best-practices                # 実際の値を使用 
+      focus: timeout                         # 実際の値を使用
     frontmatter:
       "@description": true
       customization: "high"
       applyTo: "**/*.ts"
 ```
 
-#### マルチ出力設定
+#### マルチ出力設定（実際の属性値使用）
 
 ```yaml
 # Generate multiple specialized documents
@@ -345,21 +619,21 @@ config:
 recipe:
   - title: "Development Guidelines"
     out: "development.instructions.md"  # ファイル名のみ
-    type: coding-rules
+    type: coding-rules                  # 実際の値を使用
     filters:
-      category: development
+      category: best-practices         # 実際の値を使用
       
   - title: "Testing Guidelines"  
-    out: "testing.instructions.md"  # ファイル名のみ
-    type: test
+    out: "testing.instructions.md"     # ファイル名のみ
+    type: test                         # 実際の値を使用
     filters:
-      category: best-practices
+      focus: timeout                   # 実際の値を使用
       
-  - title: "Deployment Guidelines"
-    out: "deployment.instructions.md"  # ファイル名のみ
+  - title: "Configuration Guidelines"
+    out: "configuration.instructions.md" # ファイル名のみ
     filters:
-      category: configuration
-      focus: deployment
+      category: configuration          # 実際の値を使用
+      focus: structure                 # 実際の値を使用
 ```
 
 ### カスタマイズ指針
@@ -383,38 +657,39 @@ recipe:
 
 #### 技術スタック別設定
 
-**フロントエンド中心**
+**フロントエンド中心（実際の属性値使用）**
 ```yaml
 config:
   baseDir: .github/instructions
 
 recipe:
   - import: :typescript
-  - title: "React Guidelines"
-    out: "react-guidelines.instructions.md"
-    type: coding-rules
-    language: [typescript, javascript]
+  - title: "Chrome Extension Guidelines"
+    out: "chrome-extension-guidelines.instructions.md"
+    type: development-rules                    # 実際の値を使用
+    language: [typescript, javascript]        # 実際の値を使用
     filters:
-      category: frontend
-      focus: react
+      category: chrome-extension              # 実際の値を使用
+      focus: manifest-configuration           # 実際の値を使用
 ```
 
-**バックエンド中心**
+**デスクトップアプリ中心（実際の属性値使用）**
 ```yaml
 config:
   baseDir: .github/instructions
 
 recipe:
   - import: :typescript
-  - title: "API Development"
-    out: "api-development.instructions.md"
-    type: coding-rules
+  - title: "Electron Development"
+    out: "electron-development.instructions.md"
+    type: development-rules                   # 実際の値を使用
     filters:
-      category: backend
-      focus: [api, database, security]
+      category: desktop-app                  # 実際の値を使用
+      framework: electron                    # 実際の値を使用
+      focus: electron                        # 実際の値を使用
 ```
 
-**フルスタック**
+**フルスタック（実際の属性値使用）**
 ```yaml
 config:
   baseDir: .github/instructions
@@ -424,9 +699,9 @@ recipe:
   - import: :typescript
   - title: "Full Stack Guidelines"
     out: "fullstack-guidelines.instructions.md"
-    type: coding-rules
+    type: development-rules                  # 実際の値を使用
     filters:
-      category: [frontend, backend]
+      category: [best-practices, configuration]  # 実際の値を使用（OR条件）
 ```
 
 ### トラブルシューティング
@@ -467,10 +742,85 @@ recipe:
 
 #### 一般的な問題と解決法
 
-**フィルタリング結果が空**
-- frontmatter属性の確認
-- 大文字小文字の一致確認
-- 配列形式での指定確認
+#### 一般的な問題と解決法（属性検証強化版）
+
+**フィルタリング結果が空の場合**
+
+**Step 1: 属性の実在確認**
+```bash
+# 指定した属性が実際に存在するかチェック
+npx ai-rules stats --src artifact | grep "category:" -A20
+npx ai-rules stats --src artifact | grep "focus:" -A20  
+npx ai-rules stats --src artifact | grep "type:" -A20
+```
+
+**Step 2: 段階的なデバッグ**
+```bash
+# 個別条件で確認
+npx ai-rules extract --attr category=best-practices --src artifact --out /tmp/debug-cat.md
+npx ai-rules extract --attr focus=timeout --src artifact --out /tmp/debug-focus.md
+npx ai-rules extract --type test --src artifact --out /tmp/debug-type.md
+
+# ファイルサイズで結果を確認
+ls -la /tmp/debug-*.md
+```
+
+**Step 3: よくある間違いパターン**
+- ❌ `category=best_practices` (アンダースコアは使わない)
+- ✅ `category=best-practices` (ハイフンを使用)
+- ❌ `type=coding_rules` (アンダースコアは使わない)  
+- ✅ `type=coding-rules` (ハイフンを使用)
+- ❌ `focus=Time-out` (大文字小文字が違う)
+- ✅ `focus=timeout` (すべて小文字)
+
+**属性値の正確な確認方法**
+```bash
+# 実際のファイルから属性値を直接確認
+find artifact -name "*.md" -exec head -10 {} \; | grep -E "^(type|category|focus|language):" | sort | uniq
+```
+
+**フィルター条件の組み合わせが適切でない場合**
+
+**問題**: 複数条件でAND検索すると該当ファイルがない
+```yaml
+# 問題例: 存在しない組み合わせ
+filters:
+  category: chrome-extension
+  focus: timeout  # chrome-extensionでtimeoutはない可能性
+```
+
+**解決方法**:
+```bash
+# 実際の組み合わせを事前に確認
+npx ai-rules extract --attr category=chrome-extension --src artifact --out /tmp/chrome-files.md
+grep -E "^(focus|type|language):" /tmp/chrome-files.md | sort | uniq
+
+# 結果から適切な組み合わせを選択
+# 例: chrome-extension + manifest-configuration が適切な組み合わせ
+```
+
+**frontmatter属性の記述ミス**
+- 大文字小文字の一致確認: `best-practices` vs `Best-Practices`  
+- 配列形式での指定確認: `language: [typescript, javascript]`
+- カンマ区切り vs 配列記法の確認: `typescript,javascript` vs `[typescript, javascript]`
+
+**実際のファイル内容と期待の相違**
+
+**問題**: 期待するファイルが抽出されない
+```bash
+# 特定ファイルのfrontmatter直接確認
+head -15 artifact/instructions/specific-file.md
+
+# そのファイルの属性値を確認
+grep -E "^(type|category|focus|language|applyTo):" artifact/instructions/specific-file.md
+```
+
+**解決方法**:  
+```bash
+# より広い条件で検索してから絞り込み
+npx ai-rules extract --type coding-rules --src artifact --out /tmp/broad-search.md
+grep "typescript" /tmp/broad-search.md -A5 -B5  # 関連内容を確認
+```
 
 **FrontMatter継承が機能しない**
 - @ syntax の正確な記述確認
@@ -498,9 +848,24 @@ recipe:
 
 #### 活用ツール
 
-- `npx ai-rules stats --src artifact` - 利用可能属性の確認
+**必須の事前確認コマンド**
+- `npx ai-rules stats --src artifact` - 利用可能属性と値の完全な確認（レシピ作成前に必須）
 - `npx ai-rules presets` - プリセット一覧の表示
-- `npx ai-rules extract --recipe [file]` - レシピ実行
+
+**フィルター検証用コマンド**
+- `npx ai-rules extract --type [type-value] --src artifact --out /tmp/test.md` - タイプ別フィルター検証
+- `npx ai-rules extract --language [lang-value] --src artifact --out /tmp/test.md` - 言語別フィルター検証
+- `npx ai-rules extract --attr category=[cat-value] --src artifact --out /tmp/test.md` - カテゴリ別フィルター検証
+- `npx ai-rules extract --attr focus=[focus-value] --src artifact --out /tmp/test.md` - フォーカス別フィルター検証
+
+**レシピ実行コマンド**
+- `npx ai-rules extract --recipe [file]` - レシピファイル実行
+- `npx ai-rules extract --recipe :preset-name` - プリセット実行
+
+**デバッグ用コマンド**
+- `npx ai-rules extract --recipe [file] --debug` - デバッグ情報付き実行
+- `wc -l /tmp/test-output.md` - 抽出されたファイル数の確認
+- `head -20 /tmp/test-output.md` - 抽出内容の部分確認
 
 #### コミュニティリソース
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aramassa/ai-rules",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "This repository collects guidelines and instructions for developing AI agents. It contains documents covering communication rules, coding standards, testing strategies, and general operational practices.",
   "workspaces": [
     "packages/extract",