@aramassa/ai-rules 0.2.1 → 0.3.0

package/artifact/instructions/rules/test/github-actions-no-tests.md

@@ -0,0 +1,100 @@
+---
+type: test
+category: github-actions
+focus: test-policy
+---
+
+# GitHub Actions Testing Policy
+
+## 概要
+
+GitHub Actions workflow files should not have dedicated test files. Workflow configuration is verified through alternative methods that are more effective and practical.
+
+## 基本方針
+
+### Workflow テストの禁止
+
+GitHub Actions の workflow 定義ファイル（`.github/workflows/*.yml`, `.github/workflows/*.yaml`）に対する専用のテストファイルは作成しないでください。
+
+## 理由・背景
+
+### 実効性のない検証
+
+- **YAML シンタックス検証**: GitHub Actions には組み込みの YAML バリデーション機能があるため、独自のテストは冗長
+- **想定ベースの検証**: 実際の GitHub Actions 環境で実行されないため、実際の動作との乖離が発生する可能性
+- **環境依存の問題**: ローカル環境での想定テストは、実際のCI環境での動作を保証できない
+
+### テストの可読性・保守性への悪影響
+
+- **複雑性の増加**: workflow 設定のテストは通常複雑になりがちで、メンテナンスコストが高い
+- **false positive/negative**: モックやスタブを使った検証では、実際の問題を見逃したり、存在しない問題を検出する可能性
+- **開発効率の低下**: 実効性の低いテストの作成・保守に時間を費やすことになる
+
+## 推奨される検証方法
+
+### 1. GitHub Actions 組み込み検証
+
+- **YAML 構文バリデーション**: GitHub Actions が自動的に実行
+- **Action 存在確認**: 使用している Action の存在性と互換性をプラットフォーム側で検証
+- **権限チェック**: 必要な権限の設定が適切かどうかをプラットフォーム側で確認
+
+### 2. Pull Request レビューでの手動確認
+
+- **設定の妥当性**: トリガー条件、ジョブ間の依存関係、環境変数の設定を目視確認
+- **セキュリティ観点**: 権限設定、secret の使用方法、外部 Action の安全性をレビュー
+- **業務ロジック**: ワークフローが想定された業務プロセスに沿っているかを確認
+
+### 3. 実際の実行による検証
+
+- **実環境での動作確認**: 実際に workflow を動作させることで、真の動作を検証
+- **段階的デプロイメント**: テスト用ブランチやタグを使用した安全な動作確認
+- **監視とログ**: workflow の実行ログとメトリクスによる継続的な動作確認
+
+## 実装ガイドライン
+
+### 適用範囲
+
+以下のファイルには専用のテストファイルを作成しないでください：
+
+- `.github/workflows/*.yml`
+- `.github/workflows/*.yaml`
+- その他の GitHub Actions 関連設定ファイル
+
+### 代替検証手順
+
+1. **事前検証**
+   - YAML 構文チェックツール（yq, yamllint 等）での基本的な構文確認
+   - 使用する Action の公式ドキュメント確認
+   - 必要な権限と secret の設定確認
+
+2. **段階的テスト**
+   - テスト専用のブランチまたはタグでの小規模実行
+   - 本格的なデプロイ前の dry-run 相当の確認
+   - エラー時の適切なログ出力の確認
+
+3. **継続的監視**
+   - workflow 実行の成功率監視
+   - 実行時間とリソース使用量の監視
+   - 失敗時の迅速な原因特定と対処
+
+## 例外的な状況
+
+### 許可される場合
+
+以下の場合においても、workflow 自体のテストではなく、関連するスクリプトやツールのテストに留めてください：
+
+- **カスタムスクリプトのテスト**: workflow 内で実行するシェルスクリプトや Node.js スクリプト等のテスト
+- **設定生成ツールのテスト**: workflow ファイルを動的生成するツールがある場合、そのツール自体のテスト
+- **ヘルパー関数のテスト**: workflow で使用する共通ロジックを含むライブラリのテスト
+
+### 注意事項
+
+これらの場合でも、workflow ファイル自体の設定や構造をテストするのではなく、その中で使用される個別のコンポーネントをテストすることが重要です。
+
+## 関連情報
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [YAML Syntax Validation Tools](https://yamllint.readthedocs.io/)
+- [Workflow Security Best Practices](https://docs.github.com/en/actions/security-guides)
+
+この方針により、実効性のある検証に集中し、開発効率と品質の両立を図ることができます。

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

@@ -0,0 +1,509 @@
+---
+type: prompt
+category: instruction-generation
+---
+
+## Recipe ファイル作成ルール
+
+### 目的
+
+AI-rules プロジェクトにおけるレシピファイル（recipe files）を効率的に作成するための包括的なガイドライン。複数のinstructionファイルを組み合わせて、特定の目的に応じたドキュメントを自動生成するための設定ファイル作成を支援する。
+
+### 前提条件
+
+#### 必要な知識
+
+- YAML形式の基本構文
+- ai-rules CLIの基本的な使用方法
+- instructionファイルの構造とfrontmatter属性
+- ファイルパスとディレクトリ構造の理解
+
+#### 準備事項
+
+- `artifact/instructions/` または `artifact/prompts/` ディレクトリに対象となるinstructionファイルが存在する
+- 出力先ディレクトリの権限設定が適切である
+- プロジェクトの要件とファイル構成を把握している
+
+### 実行タスク
+
+#### 手順1: 要件分析とファイル調査
+
+**ファイル構成の調査**
+1. 利用可能なinstructionファイルを確認
+2. 各ファイルのfrontmatter属性（type、language、category、focus等）を分析
+3. 既存のプリセットレシピを参考として確認
+
+**要件の明確化**
+- 生成するドキュメントの目的と対象読者
+- 必要なinstruction種別とフィルタリング条件
+- 出力ファイル構成と配置場所
+- FrontMatter継承とカスタム属性の必要性
+
+#### 手順2: レシピ構造設計
+
+**基本構造の決定**
+```yaml
+config:
+  baseDir: [出力先ディレクトリ] # オプション - 出力ファイルの配置場所を指定
+recipe:
+  - title: "[レシピアイテムのタイトル]"
+    out: "[ファイル名のみ]"  # baseDirが設定されている場合はファイル名のみ推奨
+    # フィルタリング条件
+    # 出力設定
+    # FrontMatter設定
+```
+
+**設定項目の選択**
+- **config section**: 共通設定（baseDir等）
+- **import**: 既存プリセットの活用
+- **filtering**: 対象ファイルの絞り込み
+- **output**: 出力先とモード設定
+- **frontmatter**: メタデータの管理
+
+### ファイル命名規則とbaseDir活用のベストプラクティス
+
+#### ファイル命名規則
+
+**拡張子ルール**
+- **instructionファイル**: `.instructions.md` 
+- **promptファイル**: `.prompt.md`
+- **一般的なドキュメント**: `.md`
+
+#### baseDir活用の正しい方法
+
+**✅ 推奨: baseDirを出力先ディレクトリに設定**
+```yaml
+config:
+  baseDir: .github/instructions  # 出力先ディレクトリを指定
+
+recipe:
+  - title: "TypeScript Guidelines"
+    out: "typescript-rules.instructions.md"  # ファイル名のみ
+    type: coding-rules
+    language: typescript
+```
+
+**❌ 避けるべき: baseDirをソースディレクトリに設定して複雑なパス指定**
+```yaml
+config:
+  baseDir: artifact/instructions  # ソースディレクトリ指定は混乱の原因
+
+recipe:
+  - title: "TypeScript Guidelines"
+    out: "./.github/instructions/typescript-rules.md"  # 複雑なパス指定
+    type: coding-rules
+```
+
+#### 出力パス設定のベストプラクティス
+
+**シンプルなパス管理**
+- `baseDir`: 出力先ディレクトリを指定
+- `out`: ファイル名のみ（拡張子含む）を指定
+- パスの複雑な指定は避ける
+
+**環境変数展開の活用**
+```yaml
+config:
+  baseDir: ~/.config/vscode-prompts  # チルダ展開や環境変数展開に対応
+
+recipe:
+  - title: "Custom Rules"
+    out: "custom-rules.instructions.md"
+```
+
+#### 手順3: フィルタリング条件の設定
+
+**標準フィルター**
+```yaml
+type: [instruction-type]        # 単一値または配列
+language: [target-language]     # 単一値または配列
+```
+
+**高度なフィルター**
+```yaml
+filters:
+  category: [category-value]    # カテゴリによる絞り込み
+  focus: [focus-area]          # フォーカス領域による絞り込み
+  applyTo: [file-pattern]      # ファイルパターンによる絞り込み
+  [custom-attr]: [value]       # カスタム属性による絞り込み
+```
+
+**配列値サポート**
+- フィルター値は単一値または配列を指定可能
+- 配列の場合はOR条件（いずれかにマッチ）
+- 複数フィルター間はAND条件（すべてにマッチ）
+
+#### 手順4: 出力設定とモード指定
+
+**出力ファイル設定**
+```yaml
+out: "filename.instructions.md"  # ファイル名のみ（baseDirが設定されている場合）
+mode: overwrite                  # overwrite（デフォルト）、append、prepend
+```
+
+**パス指定のパターン**
+```yaml
+# パターン1: baseDir + ファイル名のみ（推奨）
+config:
+  baseDir: .github/instructions
+recipe:
+  - out: "typescript.instructions.md"
+
+# パターン2: 絶対パスまたは相対パス（baseDirを無視）
+recipe:
+  - out: "./docs/typescript.md"
+
+# パターン3: 環境変数展開
+recipe:
+  - out: "$HOME/.vscode/prompts/typescript.instructions.md"
+```
+
+**複数アイテムでの同一ファイル出力**
+- 同じoutputファイルに複数アイテムが出力される場合、2番目以降は自動的にappendモード
+- 明示的にmodeを指定することで上書き可能
+
+#### 手順5: FrontMatter とメタデータ設計
+
+**直接指定方式**
+```yaml
+frontmatter:
+  description: "ドキュメントの説明"
+  applyTo: "**/*.ts"
+  customField: "カスタム値"
+```
+
+**継承方式（@ syntax）**
+```yaml
+frontmatter:
+  "@description": true          # テンプレートから説明を継承
+  "@tools": true               # ツール配列を継承
+  customField: "上書き値"       # カスタムフィールド追加
+```
+
+**継承のマージルール**
+- 文字列: 改行で連結（重複除去）
+- 配列: すべての要素を結合
+- オブジェクト: 後の値で上書き
+
+#### 手順6: インポートと拡張性
+
+**プリセット活用**
+```yaml
+recipe:
+  - import: :basic             # パッケージプリセット
+  - import: :typescript        # 言語固有プリセット
+  - title: "追加設定"          # カスタムアイテム
+    # ...
+```
+
+**インポートレベルbaseDir**
+```yaml
+recipe:
+  - import: 
+      recipe: :custom-preset
+      baseDir: ./custom/path   # インポート固有のベースディレクトリ
+```
+
+### 出力フォーマット
+
+#### 基本レシピテンプレート
+
+```yaml
+# Recipe file for [PURPOSE]
+# Generated by ai-rules prompt system
+
+config:
+  baseDir: [OUTPUT_DIRECTORY]  # 出力先ディレクトリを指定
+
+recipe:
+  - title: "[DOCUMENT_TITLE]"
+    out: "[FILENAME].instructions.md"  # instructionファイルの場合
+    type: [INSTRUCTION_TYPE]
+    language: [TARGET_LANGUAGE]
+    frontmatter:
+      description: |
+        [DOCUMENT_DESCRIPTION]
+      applyTo: "[FILE_PATTERN]"
+      
+  # Additional recipe items as needed
+```
+
+#### 複合型レシピテンプレート
+
+```yaml
+# Advanced recipe with multiple filtering and inheritance
+recipe:
+  # Import base configurations
+  - import: :basic
+  
+  # Main content with advanced filtering
+  - title: "[PRIMARY_CONTENT]"
+    out: "[PRIMARY_OUTPUT]"
+    type: [TYPE]
+    filters:
+      category: [CATEGORY]
+      focus: 
+        - [FOCUS1]
+        - [FOCUS2]
+    frontmatter:
+      "@description": true
+      "@tools": true
+      customization: "[CUSTOM_VALUE]"
+      
+  # Appendix or additional sections
+  - title: "[SECONDARY_CONTENT]"
+    out: "[PRIMARY_OUTPUT]"
+    mode: append
+    type: [SECONDARY_TYPE]
+    frontmatter:
+      section: "appendix"
+```
+
+### 品質基準
+
+#### 構造の健全性
+
+- [ ] **YAML構文**: 正しいYAML形式で記述されている
+- [ ] **必須フィールド**: title、outが全アイテムに指定されている
+- [ ] **フィルター整合性**: 指定したフィルターに対応するファイルが存在する
+- [ ] **パス有効性**: 出力先パスが適切で、ディレクトリが存在または作成可能
+
+#### ファイル出力の品質チェック
+
+- [ ] **baseDir設定**: 出力先ディレクトリが正しく設定されている
+- [ ] **出力パス**: outフィールドがファイル名のみになっている（baseDirを活用する場合）
+- [ ] **拡張子**: ファイルタイプに応じた適切な拡張子を使用
+  - instructionファイル: `.instructions.md`
+  - promptファイル: `.prompt.md`
+  - 一般ドキュメント: `.md`
+- [ ] **パス複雑性**: 不要な相対パス指定を避けている
+
+#### 機能性の検証
+
+- [ ] **フィルタリング**: 期待するファイル群が正しく抽出される
+- [ ] **出力制御**: 指定したモード（append/prepend/overwrite）で正しく動作
+- [ ] **FrontMatter**: 継承と直接指定が適切に機能する
+- [ ] **インポート**: プリセット活用が正しく展開される
+
+#### 保守性の確保
+
+- [ ] **コメント**: レシピの目的と使用方法が明記されている
+- [ ] **命名規則**: ファイル名とタイトルが分かりやすい
+- [ ] **バージョニング**: 変更履歴と更新理由が追跡可能
+- [ ] **ドキュメント**: 関連するREADMEやドキュメントが整備されている
+
+### 使用例
+
+#### シンプルなプロジェクト向け
+
+```yaml
+# Basic project setup
+config:
+  baseDir: .github/instructions  # 出力先ディレクトリ
+
+recipe:
+  - title: "Project Guidelines"
+    out: "project-guidelines.instructions.md"  # ファイル名のみ
+    type: planning
+    frontmatter:
+      description: "Basic project development guidelines"
+      applyTo: "**/*"
+```
+
+#### TypeScriptプロジェクト向け
+
+```yaml
+# TypeScript project comprehensive rules
+config:
+  baseDir: .github/instructions
+
+recipe:
+  - import: :basic
+  - import: :typescript
+  
+  - title: "Custom TypeScript Rules"
+    out: "custom-typescript.instructions.md"  # ファイル名のみ
+    type: coding-rules
+    language: typescript
+    filters:
+      focus: 
+        - testing
+        - performance
+    frontmatter:
+      "@description": true
+      customization: "high"
+      applyTo: "**/*.ts"
+```
+
+#### マルチ出力設定
+
+```yaml
+# Generate multiple specialized documents
+config:
+  baseDir: ./docs
+
+recipe:
+  - title: "Development Guidelines"
+    out: "development.instructions.md"  # ファイル名のみ
+    type: coding-rules
+    filters:
+      category: development
+      
+  - title: "Testing Guidelines"  
+    out: "testing.instructions.md"  # ファイル名のみ
+    type: test
+    filters:
+      category: best-practices
+      
+  - title: "Deployment Guidelines"
+    out: "deployment.instructions.md"  # ファイル名のみ
+    filters:
+      category: configuration
+      focus: deployment
+```
+
+### カスタマイズ指針
+
+#### プロジェクト規模による調整
+
+**小規模プロジェクト**
+- 単一レシピファイルでの包括的な設定
+- プリセット（:basic）の積極活用
+- シンプルなフィルタリング条件
+
+**中規模プロジェクト**
+- 機能別・技術別の複数レシピファイル
+- カスタムfrontmatterによる詳細管理
+- 高度なフィルタリングとインポート活用
+
+**大規模プロジェクト**
+- ドメイン別の階層化されたレシピ構成
+- 継承とテンプレート機能の最大活用
+- 自動化ワークフローとの統合
+
+#### 技術スタック別設定
+
+**フロントエンド中心**
+```yaml
+config:
+  baseDir: .github/instructions
+
+recipe:
+  - import: :typescript
+  - title: "React Guidelines"
+    out: "react-guidelines.instructions.md"
+    type: coding-rules
+    language: [typescript, javascript]
+    filters:
+      category: frontend
+      focus: react
+```
+
+**バックエンド中心**
+```yaml
+config:
+  baseDir: .github/instructions
+
+recipe:
+  - import: :typescript
+  - title: "API Development"
+    out: "api-development.instructions.md"
+    type: coding-rules
+    filters:
+      category: backend
+      focus: [api, database, security]
+```
+
+**フルスタック**
+```yaml
+config:
+  baseDir: .github/instructions
+
+recipe:
+  - import: :basic
+  - import: :typescript
+  - title: "Full Stack Guidelines"
+    out: "fullstack-guidelines.instructions.md"
+    type: coding-rules
+    filters:
+      category: [frontend, backend]
+```
+
+### トラブルシューティング
+
+#### baseDir設定に関する一般的な問題
+
+**問題1: 意図しない場所にファイルが出力される**
+```yaml
+# ❌ 問題のある例
+config:
+  baseDir: instructions  # ソースディレクトリを指定
+
+recipe:
+  - out: "./.github/instructions/file.md"  # 複雑なパス指定
+    # 結果: instructions/.github/instructions/file.md に出力
+```
+
+```yaml
+# ✅ 修正例
+config:
+  baseDir: .github/instructions  # 出力先ディレクトリを指定
+
+recipe:
+  - out: "file.instructions.md"  # ファイル名のみ
+    # 結果: .github/instructions/file.instructions.md に出力
+```
+
+**問題2: ファイル拡張子の規則が統一されていない**
+```yaml
+# ❌ 問題のある例
+recipe:
+  - out: "typescript-rules.md"  # instructionファイルなのに .md
+
+# ✅ 修正例  
+recipe:
+  - out: "typescript-rules.instructions.md"  # 正しい拡張子
+```
+
+#### 一般的な問題と解決法
+
+**フィルタリング結果が空**
+- frontmatter属性の確認
+- 大文字小文字の一致確認
+- 配列形式での指定確認
+
+**FrontMatter継承が機能しない**
+- @ syntax の正確な記述確認
+- 継承元ファイルの存在確認
+- フィルタリング条件の見直し
+
+**出力ファイルが期待と異なる**
+- modeの明示的指定
+- 出力パスの絶対/相対パス確認
+- 環境変数展開の動作確認
+
+**プリセットインポートエラー**
+- プリセット名（:prefix）の確認
+- プリセットファイルの存在確認
+- 循環参照の回避
+
+### 関連リソース
+
+#### 参考ドキュメント
+
+- [CLI Options Documentation](../../../docs/cli_options.md)
+- [FrontMatter Inheritance Guide](../../../docs/frontmatter-inheritance.md)
+- [Existing Presets](../../../presets/)
+- [Example Recipes](../../../example/)
+
+#### 活用ツール
+
+- `npx ai-rules stats --src artifact` - 利用可能属性の確認
+- `npx ai-rules presets` - プリセット一覧の表示
+- `npx ai-rules extract --recipe [file]` - レシピ実行
+
+#### コミュニティリソース
+
+- プロジェクトのIssue追跡システム
+- 既存レシピファイルの実装例
+- プロンプト改善提案とベストプラクティス共有

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAygBA;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBpG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAqjBA;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBpG"}