@aramassa/ai-rules 0.2.0 → 0.2.2

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_prompts.prompt.md

@@ -0,0 +1,203 @@
+---
+type: prompt
+category: content-creation
+---
+
+## Prompts 作成ルール
+
+#### 基本ルール
+
+- ファイル名規則は `[用途名].prompt.md` または `[プロジェクト名]/[用途名].prompt.md`
+- プロンプトファイルにはfrontmatterで分類情報を付与する
+- 人間が使いやすく、AIが理解しやすい構造化されたプロンプトを作成する
+- **見出し階層は必ず `##` から開始する** - artifact/ 以下のMarkdownはrecipeファイルで統合されることを想定
+
+#### プロンプトファイルの構造
+
+#### 必須要素
+
+1. **Frontmatter** - プロンプトの分類・属性情報
+2. **プロンプト本体** - AIが実行すべき具体的なタスク
+3. **期待する出力形式** - 生成結果のフォーマットや構造
+
+#### Frontmatterの標準フィールド
+
+```yaml
+---
+type: prompt # プロンプトの種類
+category: [分類] # 用途別カテゴリ
+language: [対象言語] # 対象プログラミング言語（該当する場合）
+applyTo: "[対象パターン]" # 適用対象（該当する場合）
+human-instruction: |- # 人間向けの追加ガイダンス（オプション）
+  [使用上の注意点やコンテキスト]
+---
+```
+
+#### カテゴリ分類
+
+#### type 値の標準
+
+- `prompt` - 一般的なプロンプト
+
+#### category 値の例
+
+- `content-creation` - コンテンツ作成
+- `code-analysis` - コード分析
+- `documentation` - ドキュメント生成
+- `project-planning` - プロジェクト計画
+- `todo-planning` - TODO管理
+- `instruction-generation` - instruction生成
+- `structure-analysis` - 構造分析
+
+#### プロンプト作成ガイドライン
+
+#### 1. 明確性の原則
+
+- **具体的な指示**: 曖昧な表現を避け、実行すべきタスクを明確に記述
+- **期待する出力**: 生成結果のフォーマットや構造を具体的に示す
+- **制約条件**: 守るべきルールや制限を明記
+
+#### 2. 構造化の原則
+
+- **段階的な指示**: 複雑なタスクは段階的に分解
+- **見出し構造**: マークダウンの見出しでセクションを明確に分離
+- **見出し階層の統一**: メインタイトルは `##`、セクションは `###`、サブセクションは `####` で統一
+- **recipeファイル対応**: artifact/ 以下のファイルはrecipeで統合されるため、`#` レベルの見出しは使用禁止
+- **リスト活用**: 項目の列挙にはリストを使用
+
+#### 3. 再利用性の原則
+
+- **パラメータ化**: 変更が必要な部分は明確に示す
+- **テンプレート化**: 類似タスクで再利用できる構造
+- **カスタマイズ指針**: 具体的な用途に合わせた調整方法を記載
+
+#### 4. 品質保証の原則
+
+- **検証可能性**: 出力結果の品質を確認できる基準を提供
+- **エラー処理**: 想定される問題と対処法を記載
+- **改善指針**: プロンプトの効果を向上させる方法を提示
+
+#### プロンプト本体の構造
+
+#### 標準テンプレート
+
+**重要**: 以下のテンプレートでは `#` レベルから始まっていますが、artifact/ 以下の実際のファイルでは `##` レベルから開始してください。
+
+```markdown
+## [プロンプトのタイトル]
+
+### 目的
+
+[このプロンプトが解決する課題や目標を明記]
+
+### 前提条件
+
+[プロンプト実行前に必要な準備や条件]
+
+### 実行タスク
+
+[具体的な実行内容を段階的に記述]
+
+#### 手順1: [フェーズ名]
+
+[具体的な指示内容]
+
+#### 手順2: [フェーズ名]
+
+[具体的な指示内容]
+
+### 出力フォーマット
+
+[期待する出力の構造・形式]
+
+### 品質基準
+
+[出力結果の品質を判断する基準]
+
+### 使用例
+
+[具体的な使用場面や活用方法]
+
+### カスタマイズ指針
+
+[特定の用途に合わせた調整方法]
+```
+
+#### ディレクトリ構造の原則
+
+#### プロジェクト固有プロンプト
+
+```
+artifact/prompts/
+├── [プロジェクト名]/
+│   ├── [用途1].prompt.md
+│   ├── [用途2].prompt.md
+│   └── README.md           # プロジェクト固有プロンプトの説明
+└── [汎用プロンプト].prompt.md
+```
+
+#### 汎用プロンプト
+
+直接 `artifact/prompts/` ディレクトリに配置し、様々なプロジェクトで再利用可能にする
+
+#### 実践ガイドライン
+
+#### プロンプト作成時の確認事項
+
+- [ ] **目的の明確性**: 解決したい課題が具体的に説明されている
+- [ ] **指示の具体性**: AIが実行すべき内容が明確である
+- [ ] **出力の定義**: 期待する結果の形式が明記されている
+- [ ] **再利用性**: 他の用途でも活用できる構造になっている
+- [ ] **品質基準**: 結果の良し悪しを判断する基準がある
+- [ ] **見出し階層**: メインタイトルが `##` レベルから始まっている
+- [ ] **recipe対応**: `#` レベルの見出しを使用していない
+
+#### プロンプトの品質向上
+
+1. **テスト実行**: 実際にAIで実行して結果を確認
+2. **改善反復**: 期待する結果が得られるまで調整
+3. **ドキュメント化**: 効果的な使い方や注意点を記録
+4. **バージョン管理**: 変更履歴をGitで適切に管理
+
+#### 運用における注意事項
+
+- **一貫性の維持**: 同様の用途のプロンプトは統一された構造を使用
+- **メンテナンス**: 技術の進歩に合わせてプロンプトを更新
+- **共有促進**: チーム内でのプロンプト活用を促進
+- **フィードバック収集**: 使用者からの改善提案を積極的に収集
+
+#### 関連ドキュメント
+
+- [Instructions作成ルール](../../instructions/) - AI向けinstruction管理
+- [TODO Plans作成ルール](../development/todo_plans.prompt.md) - 計画管理プロンプト
+- [Recipe Files](../../../presets/) - プロンプト組み合わせ設定
+
+#### ファイル名規則の例
+
+```
+artifact/prompts/
+├── ai-rules/
+│   ├── for_prompts.prompt.md         # 本ファイル
+│   ├── project_analysis.prompt.md    # プロジェクト分析用
+│   └── migration_guide.prompt.md     # 移行ガイド生成用
+├── documentation/
+│   ├── api_docs.prompt.md            # API文書生成
+│   └── readme_generator.prompt.md    # README生成
+├── development/
+│   └── todo_plans.prompt.md          # TODO計画管理
+├── code_analysis.prompt.md           # 汎用コード分析
+```
+
+#### メタルール
+
+#### プロンプトの進化
+
+- **継続的改善**: 使用結果を基にプロンプトを継続的に改善
+- **ベストプラクティス抽出**: 効果的なパターンを標準化
+- **知識の蓄積**: 成功事例と失敗事例を記録・共有
+
+#### 品質保証
+
+- **レビュープロセス**: 新規プロンプトは使用前にレビュー
+- **効果測定**: プロンプトの効果を定量的・定性的に評価
+- **標準化推進**: 組織全体でのプロンプト品質向上

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

@@ -0,0 +1,379 @@
+---
+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: "[出力ファイルパス]"
+    # フィルタリング条件
+    # 出力設定
+    # FrontMatter設定
+```
+
+**設定項目の選択**
+- **config section**: 共通設定（baseDir等）
+- **import**: 既存プリセットの活用
+- **filtering**: 対象ファイルの絞り込み
+- **output**: 出力先とモード設定
+- **frontmatter**: メタデータの管理
+
+#### 手順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: "./path/to/output.md"     # 出力先パス（環境変数展開対応）
+mode: overwrite               # overwrite（デフォルト）、append、prepend
+```
+
+**複数アイテムでの同一ファイル出力**
+- 同じ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: [SOURCE_DIRECTORY]
+
+recipe:
+  - title: "[DOCUMENT_TITLE]"
+    out: "[OUTPUT_PATH]"
+    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が全アイテムに指定されている
+- [ ] **フィルター整合性**: 指定したフィルターに対応するファイルが存在する
+- [ ] **パス有効性**: 出力先パスが適切で、ディレクトリが存在または作成可能
+
+#### 機能性の検証
+
+- [ ] **フィルタリング**: 期待するファイル群が正しく抽出される
+- [ ] **出力制御**: 指定したモード（append/prepend/overwrite）で正しく動作
+- [ ] **FrontMatter**: 継承と直接指定が適切に機能する
+- [ ] **インポート**: プリセット活用が正しく展開される
+
+#### 保守性の確保
+
+- [ ] **コメント**: レシピの目的と使用方法が明記されている
+- [ ] **命名規則**: ファイル名とタイトルが分かりやすい
+- [ ] **バージョニング**: 変更履歴と更新理由が追跡可能
+- [ ] **ドキュメント**: 関連するREADMEやドキュメントが整備されている
+
+### 使用例
+
+#### シンプルなプロジェクト向け
+
+```yaml
+# Basic project setup
+config:
+  baseDir: artifact/instructions
+
+recipe:
+  - title: "Project Guidelines"
+    out: "./.github/copilot-instructions.md"
+    type: planning
+    frontmatter:
+      description: "Basic project development guidelines"
+      applyTo: "**/*"
+```
+
+#### TypeScriptプロジェクト向け
+
+```yaml
+# TypeScript project comprehensive rules
+recipe:
+  - import: :basic
+  - import: :typescript
+  
+  - title: "Custom TypeScript Rules"
+    out: "./.github/instructions/custom-typescript.md"
+    type: coding-rules
+    language: typescript
+    filters:
+      focus: 
+        - testing
+        - performance
+    frontmatter:
+      "@description": true
+      customization: "high"
+      applyTo: "**/*.ts"
+```
+
+#### マルチ出力設定
+
+```yaml
+# Generate multiple specialized documents
+recipe:
+  - title: "Development Guidelines"
+    out: "./docs/development.md"
+    type: coding-rules
+    filters:
+      category: development
+      
+  - title: "Testing Guidelines"  
+    out: "./docs/testing.md"
+    type: test
+    filters:
+      category: best-practices
+      
+  - title: "Deployment Guidelines"
+    out: "./docs/deployment.md"
+    filters:
+      category: configuration
+      focus: deployment
+```
+
+### カスタマイズ指針
+
+#### プロジェクト規模による調整
+
+**小規模プロジェクト**
+- 単一レシピファイルでの包括的な設定
+- プリセット（:basic）の積極活用
+- シンプルなフィルタリング条件
+
+**中規模プロジェクト**
+- 機能別・技術別の複数レシピファイル
+- カスタムfrontmatterによる詳細管理
+- 高度なフィルタリングとインポート活用
+
+**大規模プロジェクト**
+- ドメイン別の階層化されたレシピ構成
+- 継承とテンプレート機能の最大活用
+- 自動化ワークフローとの統合
+
+#### 技術スタック別設定
+
+**フロントエンド中心**
+```yaml
+recipe:
+  - import: :typescript
+  - title: "React Guidelines"
+    type: coding-rules
+    language: [typescript, javascript]
+    filters:
+      category: frontend
+      focus: react
+```
+
+**バックエンド中心**
+```yaml
+recipe:
+  - import: :typescript
+  - title: "API Development"
+    type: coding-rules
+    filters:
+      category: backend
+      focus: [api, database, security]
+```
+
+**フルスタック**
+```yaml
+recipe:
+  - import: :basic
+  - import: :typescript
+  - title: "Full Stack Guidelines"
+    type: coding-rules
+    filters:
+      category: [frontend, backend]
+```
+
+### トラブルシューティング
+
+#### 一般的な問題と解決法
+
+**フィルタリング結果が空**
+- 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追跡システム
+- 既存レシピファイルの実装例
+- プロンプト改善提案とベストプラクティス共有