@aramassa/ai-rules 0.1.1-npmjs.20250910072942

package/artifact/instructions/python-cli.md

@@ -0,0 +1,261 @@
+---
+type: python-cli
+category: implementation
+focus: cli-development
+language: python
+human-instruction: |-
+  ## Python CLI 開発のための包括的ガイドライン
+
+  このガイドラインは、Python CLI アプリケーション開発における
+  ライブラリ選択、アーキテクチャ設計、実装パターンを体系化したものです。
+  argparse/Click/Typer の比較から実際の実装テクニックまで、
+  instruction 改善に活用できる実践的な内容を提供します。
+---
+
+# Python CLI 実装ガイドライン
+
+## 背景
+
+Python CLI 開発においては、適切なライブラリ選択とアーキテクチャ設計が開発効率と保守性に大きく影響します。本ガイドラインは、argparse/Click/Typer の比較分析と実装ベストプラクティスを提供し、instruction 改善の指針として活用できます。
+
+## ライブラリ選択の判断基準
+
+### argparse を選ぶべき場合
+
+- **標準ライブラリのみで完結させたい**
+- **外部依存を追加できない環境制約**
+- **小規模なスクリプト（10個未満のオプション）**
+- **精密な引数制御が必要な特殊ケース**
+
+### Click を選ぶべき場合
+
+- **実績と安定性を重視する本番環境**
+- **大規模CLIツール（複数階層のサブコマンド）**
+- **チーム開発での標準化済み環境**
+- **マルチプラットフォーム配布が重要**
+
+### Typer を選ぶべき場合（推奨）
+
+- **開発効率と型安全性を重視**
+- **FastAPI などモダンなPython技術との統合**
+- **プロトタイピングや素早い実装が必要**
+- **美しいUXを提供したい開発者向けツール**
+
+### 明らかにTyperに適していない場合
+
+- **極めて複雑な引数制御が必要（argparse推奨）**
+- **レガシー環境での長期運用（Click推奨）**
+- **最小限の外部依存が絶対条件（argparse推奨）**
+
+## ライブラリ機能比較表
+
+| 機能 | argparse | Click | Typer |
+|------|----------|-------|-------|
+| 引数・オプション定義 | 手動（add_argument） | デコレータ | 型注釈 |
+| サブコマンド | add_subparsers | 優秀 | 優秀（Click ベース） |
+| 補完機能 | 外部ライブラリ必要 | Bash/Zsh/Fish | 全シェル対応 |
+| 型注釈対応 | なし | なし | フル対応 |
+| 自動ヘルプ生成 | 基本 | 充実 | 最高 |
+| 学習コスト | 中 | 低-中 | 低 |
+| 実績・安定性 | 高（標準） | 高 | 中（新しい） |
+
+## CLI アーキテクチャ設計
+
+### エントリポイント設計パターン
+
+```python
+# packages/cli/src/rag_pf_cli/main.py
+app = typer.Typer(name="ragly", help="RAG Platform CLI")
+app.add_typer(ingest.app, name="ingest", help="Data ingestion commands")
+app.add_typer(evaluation.app, name="evaluate", help="Evaluation commands")
+app.add_typer(retrieval.app, name="retrieve", help="Retrieval commands")
+```
+
+### 一貫したエラーハンドリング
+
+```python
+@app.command()
+def risky_operation():
+    try:
+        # 処理実行
+        console.print("[green]✓ Operation completed[/green]")
+    except Exception as e:
+        console.print(f"[red]✗ Operation failed: {e}[/red]")
+        raise typer.Exit(1)
+```
+
+### Rich による美しい出力
+
+```python
+# テーブル表示
+table = Table(title="RAG Platform Status")
+table.add_column("Component", style="cyan")
+table.add_column("Status", style="green")
+table.add_row("Database", "✓ Connected")
+console.print(table)
+
+# プログレスバー
+with Progress() as progress:
+    task = progress.add_task("[green]Processing...", total=items)
+    for i in range(items):
+        progress.update(task, advance=1)
+```
+
+## 実装テクニック
+
+### 型安全性とPydantic連携
+
+```python
+class AppConfig(BaseModel):
+    database: DatabaseConfig
+    debug: bool = Field(default=False)
+    log_level: str = Field(default="INFO")
+    
+    @classmethod
+    def from_env(cls) -> "AppConfig":
+        """Load configuration from environment variables."""
+        return cls(
+            database=DatabaseConfig(
+                host=os.getenv("DB_HOST", "localhost"),
+                # ...
+            )
+        )
+```
+
+### ログ設定とデバッグ支援
+
+```python
+def setup_logging(level: str = "INFO", rich_output: bool = True):
+    """Set up logging with Rich handler."""
+    logging.basicConfig(
+        level=getattr(logging, level.upper()),
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[RichHandler()] if rich_output else None
+    )
+```
+
+## テスト戦略
+
+### 設定ファイルベースのテスト
+
+```python
+@pytest.fixture
+def sample_config():
+    return RagConfig(
+        database=DatabaseConfig(
+            database="test_db",
+            username="test_user", 
+            password="test_password"
+        ),
+        vector_store=VectorStoreConfig(
+            provider="memory",
+            collection_name="test_collection"
+        ),
+        chunk_size=256,
+        chunk_overlap=25,
+        debug=True
+    )
+```
+
+### CLI統合テスト
+
+```python
+def test_ingest_command(runner):
+    result = runner.invoke(app, [
+        "ingest", "run", "test_data.txt",
+        "--loader-type", "text",
+        "--chunk-size", "256"
+    ])
+    assert result.exit_code == 0
+    assert "Ingestion complete" in result.stdout
+```
+
+### モックとフィクスチャの活用
+
+```python
+@patch('myapp.database.connect')
+def test_database_connection(mock_connect, runner):
+    mock_connect.return_value = Mock()
+    result = runner.invoke(app, ["db", "status"])
+    assert result.exit_code == 0
+    mock_connect.assert_called_once()
+```
+
+## パッケージ管理（uv ワークスペース）
+
+### pyproject.toml の設計
+
+```toml
+[project]
+name = "rag-pf-cli"
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+]
+
+[tool.uv.sources]
+rag-pf-common = { workspace = true }
+rag-pf-core = { workspace = true }
+
+[project.scripts]
+ragly = "rag_pf_cli.main:app"
+```
+
+### 開発スクリプトの活用
+
+```bash
+# setup-dev.sh での CLI インストール
+uv pip install -e packages/cli
+
+# 実行確認
+uv run ragly --help
+```
+
+### 品質保証スクリプト
+
+```bash
+# 型チェック
+uv run mypy packages/
+
+# リンティング
+uv run ruff check packages/
+uv run ruff format packages/
+
+# テスト実行
+uv run pytest tests/ --cov=packages
+```
+
+## CLI 基本設計原則
+
+### サブコマンドベースの構造
+
+- **機能別モジュール分割**: 関連機能をサブコマンドでグループ化
+- **直感的な命名**: ユーザーが推測しやすいコマンド名
+- **一貫したインターフェース**: 共通オプションの統一
+
+### 設定管理のベストプラクティス
+
+- **階層的設定**: 環境変数 → 設定ファイル → CLI引数の優先順位
+- **型安全な設定**: Pydantic による設定値の検証
+- **開発/本番環境の切り分け**: 環境別設定の明確な分離
+
+## 追加検討要素
+
+### パフォーマンス考慮
+
+- **大規模データ処理**: ストリーミング処理とプログレス表示
+- **並列処理**: asyncio や multiprocessing の適切な活用
+- **メモリ効率**: 大量データ処理時のメモリ使用量最適化
+
+### セキュリティ
+
+- **機密データ処理**: 環境変数やシークレット管理の適切な実装
+- **入力検証**: ユーザー入力の適切なサニタイゼーション
+- **ログ安全性**: 機密情報のログ出力防止
+
+### 配布最適化
+
+- **バイナリ配布**: PyInstaller や cx_Freeze を使った単体実行ファイル化
+- **Docker コンテナ化**: マルチステージビルドによる軽量化
+- **パッケージ配布**: PyPI 公開時の品質確保

package/artifact/instructions/retrospective.md

@@ -0,0 +1,32 @@
+---
+type: retrospective
+title: タスクの振り返り
+---
+
+実行したタスクを振り返って、次の遂行時によりよい結果を得られるように改善しましょう
+
+## 振り返りの結果得たいこと
+
+* instruction ファイル群の改善点をGitHub Issueにする
+* 学習コンテンツを作成する(学習フォルダに作成)
+
+### 振り返りのポイント
+
+#### 修正指示を受けたこと
+
+一度実行したタスクに対して修正指示があった場合、
+
+#### コマンドエラー
+
+Runner の実行時などでエラーを発生させてしまった場合は、正しいコマンドを選択できるように、
+『いつ、どのコマンドを使用すべきか？』を instruction に追記するようにしましょう。
+
+## GitHub Issueの登録方法
+
+instruction管理用のリポジトリが指定されている場合は、そのリポジトリに新しくIssueを登録してください。
+リポジトリが指定されていない場合は、確認してください。
+
+```
+title: 改善内容を端的に表すもの
+body: 改善内容をできるだけ詳細に記載。実際に遭遇したシチュエーションなどを例として記載してください。
+```

package/artifact/instructions/rules/coding/nodejs.md

@@ -0,0 +1,299 @@
+---
+type: coding-rules
+language:
+  - nodejs
+  - typescript
+---
+
+このドキュメントでは、Node.js/TypeScript プロジェクトにおけるコーディング規約・スタイルガイドについて説明します。
+
+---
+
+## 1. 基本方針
+
+### 1.1 言語とモジュール形式
+
+- **ESM 形式**で書く（CommonJS は使用しない）
+- **TypeScript** の型システムをフル活用し、型安全なコードを書く
+- 可能な限り **`class`** を利用する
+  - メソッドは可能な限りアトミックにし、単一責任を守る
+- メソッドやプロパティの可視性は必ず設定し、不必要に公開範囲を広げない
+
+### 1.2 設計原則
+
+- **依存性逆転 (DIP)**: Domain から外部サービスに直接依存しない。ポート＆アダプター (Hexagonal) を採用する
+- **Config‑as‑Code**: 環境差分は `config/` の設定ファイルに集約し、dotenv で注入する
+- **CQRS / Event‑Driven** を検討し、読み取り専用サービスのスケーラビリティを高める
+- インターフェースを明確にし、共通化できるところは共通化する
+  - Factory パターンや Strategy パターンも使えるところでは使う
+- コンポジションを優先し、継承は必要最小限（例: サードパーティ API の拡張）にとどめる
+
+---
+
+## 2. コーディングスタイル
+
+### ESMファイルの実行制御
+
+- CLI用のESMファイル（実行可能ファイル）では、ファイル末尾での実行判定チェック（`if (import.meta.url === \`file://${process.argv[1]}\`)`）は使用しない
+- 代わりに、CLI として設計されたファイルでは常に main 関数を実行するようにする
+- 理由：npx や npm scripts 経由での実行時に判定が正しく動作しない場合があるため
+- 例：
+  ```typescript
+  // ❌ 避ける
+  if (import.meta.url === `file://${process.argv[1]}`) {
+    main();
+  }
+
+  // ✅ 推奨（CLI用ファイルの場合）
+  main().catch(console.error);
+
+### 2.1 変数と関数
+
+- 変数は再代入が不要な限り **`const`** を使用し、`var` は禁止とする
+- **`async/await`** を優先し、Promise チェーンやコールバックの多用を避ける
+- 公開 API（export される関数・クラス メソッド）は必ず戻り値の型を明示する
+- **Top‑level await** はエントリポイント以外で使用しない
+
+### 2.2 定数管理
+
+- マジックナンバー／マジックストリングを禁止し、`const enum` または設定ファイル・専用の定数オブジェクトに切り出して一元管理する
+  - 例: logger 設定値や API エンドポイント、日付パターン、ファイルサイズなどは `src/utils/loggerConfig.ts` のような専用ファイルで管理する
+  - 既存コードで直値が使われている場合は、リファクタリング時に必ず定数化・集約を行うこと
+
+### 2.3 コード量の目安
+
+- 関数は **20 行以内**、クラスは **400 行以内**を目安とする
+- 循環的複雑度 (cyclomatic complexity) は **10 未満**に抑える
+
+### 2.4 エラーハンドリング
+
+- 非同期エラーは `Result<T, E>` パターンまたは独自の `TypedError` クラスでラップし、`throw` するのは `Error` 派生クラスに限定する
+- エラーハンドリングは `try/catch` または `Error Boundary` で捕捉し、必ず `logger.error` でスタックトレースを出力する
+- `process.exit` の使用は極力避け、正常終了・異常終了の制御は例外処理やエラーハンドリングで行うこと
+
+---
+
+## 3. 静的解析・整形（必須設定）
+
+### 3.1 ツール構成（必須）
+
+- **[ESLint](https://eslint.org/)** + **[@typescript-eslint](https://typescript-eslint.io/)** + **[Prettier](https://prettier.io/)** の導入・設定は**必須**
+- 必須ルール: **Airbnb TypeScript**ベース
+- VSCode使用時は必須設定: `.vscode/settings.json`
+- `.editorconfig` でエディタ横断の整形統一（必須）
+- 新規プロジェクト作成時は必ず設定ファイル（.eslintrc.json, .prettierrc, .editorconfig）を作成すること
+
+### 3.2 ESLint設定
+
+#### パーサとプラグイン
+- パーサ: `@typescript-eslint/parser`（TypeScript対応）
+- 拡張: `eslint:recommended`, `plugin:@typescript-eslint/recommended`, `prettier`
+- プラグイン: `@typescript-eslint`, `import`, `eslint-plugin-tsdoc`
+
+#### 主なルール
+- 未使用変数エラー化、関数戻り値型は警告、TSDoc構文警告など
+- テストコードは一部ルール緩和（`test/**/*`）
+- 除外: `dist/`, `node_modules/`, `*.js`, `*.mjs`
+
+#### 必須コマンド（package.json scripts）
+- `npm run lint` で全体Lint（必須設定）
+- `npm run lint:fix` で自動修正（必須設定）
+- VSCode拡張: `dbaeumer.vscode-eslint` で保存時自動整形
+
+#### 必須パッケージインストール
+```bash
+npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
+npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier
+```
+
+### 3.3 Prettier設定
+
+`.prettierrc.yaml` で整形ルールを一元管理：
+
+- 最大行長: **100桁**（`printWidth: 100`）
+- シングルクォート: **不使用**（`singleQuote: false`）
+- 末尾カンマ: **ES5互換**（`trailingComma: es5`）
+- セミコロン: **必須**（`semi: true`）
+- アロー関数の括弧: **常に付与**（`arrowParens: always`）
+- マークダウンや文章の折返し: **常に有効**（`proseWrap: always`）
+
+### 3.4 EditorConfig設定
+
+`.editorconfig` の主なルール：
+
+- 文字コード: **UTF-8**
+- インデント: **スペース2**
+- 行末: **LF**
+- ファイル末尾改行: **必須**
+- 末尾空白: **自動削除**
+- 最大行長: **100**（`*.{js,ts,md,yaml}`）
+
+### 3.5 VSCode推奨設定
+
+`.vscode/settings.json` の主なルール：
+
+- 保存時自動整形: 有効（`editor.formatOnSave: true`）
+- タブ幅: **2**
+- ルーラー: **80, 120**
+- 末尾改行・空白削除: 有効
+- 検索除外: `node_modules`, `dist`, `build`
+- ESLint拡張: TypeScriptバリデーション有効
+
+---
+
+## 4. テスト方針
+
+### 4.1 基本方針
+
+- **TDD ファースト**: ユースケース単位で `describe → it` を書いてから実装する
+- **Unit Test**: [Vitest](https://vitest.dev/) を利用、**80% 以上**の branch coverage を目標とする
+- テスト用にファイルが必要な場合は、テストケース内で実行時に作るのではなく、予め `test/fixtures/` に作成しておくこと
+- テストは必ず **docker コンテナ上**で実行すること
+
+### 4.2 テスト実行環境
+
+```sh
+rm -rf node_modules package-lock.json
+docker run --rm -v $(pwd):/app -w /app node:20 npm install
+docker run --rm -v $(pwd):/app -w /app -e NODE_ENV=test node:20 npm run test
+```
+
+### 4.3 Vitest設定
+
+- 設定: `vitest.config.ts`
+- テストは `test/` 配下に `*.test.ts` で配置
+- テスト用fixtureは `test/fixtures/` にまとめる
+- テスト環境: Node.js（`environment: node`）
+- グローバル: 有効（`globals: true`）
+
+### 4.4 推奨コマンド
+
+- `npm test` で全テスト実行
+- `npm run test:ui` でUIモード
+- CI/CDで自動実行（`.github/workflows/test.yml`）
+
+### 4.5 テストコード制限
+
+#### it.each の使用禁止
+
+- **`it.each` は使用してはいけない**
+- **理由**: スケルトン構造検証システム（`test/skeleton-structure-validation.test.ts`）が正常に動作しなくなるため
+- `it.each` はテストケースを動的に生成するため、静的解析によるスケルトンファイル（`skel/test/`）との構造比較ができない
+- 代替手段: 複数のテストケースが必要な場合は、個別の `it` ブロックを明示的に記述する
+
+```typescript
+// ❌ 禁止: it.each の使用
+it.each([
+  { input: 1, expected: 2 },
+  { input: 2, expected: 4 },
+])('should multiply by 2: $input -> $expected', ({ input, expected }) => {
+  expect(multiply(input, 2)).toBe(expected);
+});
+
+// ✅ 推奨: 個別の it ブロック
+it('should multiply 1 by 2 to get 2', () => {
+  expect(multiply(1, 2)).toBe(2);
+});
+
+it('should multiply 2 by 2 to get 4', () => {
+  expect(multiply(2, 2)).toBe(4);
+});
+```
+
+---
+
+## 5. 開発フロー
+
+### 5.1 基本ステップ
+
+※ 各ステップで開発者に同意を得てから、次のステップに進むこと
+
+1. **要件の明確化**
+   - 実装する機能を明確に定義する
+   - 開発者と合意が取れるまで会話を続ける
+
+2. **修正対象の特定**
+   - どの部分を修正するかを特定する
+   - どの順番で修正していくかを決める
+
+3. **テストを書く(TDD)**
+   - 修正対象の特定ができたら、テストを書く
+   - テストは、修正対象の特定ができた段階で書く
+
+4. **修正の実行**
+
+5. **テストの実行**（必ず全てのテストを実行）
+
+6. **リファクタリングの実施**
+
+7. **テストの再実行**（必ず全てのテストを実行）
+
+8. **ドキュメントの更新**
+
+9. **全体を振り返って、フローに改善の余地があれば `.github/copilot-instructions.md` を更新する**
+
+### 5.2 計画管理
+
+#### change_plans/ 運用ルール
+
+- 機能追加のために不明な点があれば、追加で確認する
+- 開発内容を決めるにあたっては、`change_plans/` ディレクトリにファイルを作成し、修正計画を記載していく
+  - ファイル名規則は、`YYYYMMDD_[タイトル].md`
+  - 修正計画は、開発の進捗に応じて更新していく
+  - 対応が完了した計画ファイルは削除する。Git の履歴で追跡できるため、`done_plans/` への移動は行わずリポジトリを軽量に保つ。
+
+#### todo_plans/ 運用ルール
+
+- やり残した作業や、将来的に実装が必要な機能がある場合は、`todo_plans/` ディレクトリにMarkdownファイルとして記録する
+- ファイル名は `YYYYMMDD_[タイトル].md` の形式で作成する（例: `20250616_ユーザー認証機能の実装.md`）
+- `todo_plans/` に記録されたタスクに着手する際には、そのファイルを `change_plans/` ディレクトリに移動する
+- 対応が完了したタスクのファイルは削除する。履歴は Git で確認できるため、完了済みの計画を保持する必要はない。
+
+### 5.3 スケルトン（skel/ ディレクトリ）運用ルール
+
+- `skel/` ディレクトリは、実装ファイルやテストファイルの「構造設計図」を管理するための専用ディレクトリ
+- スケルトンファイルは、**本体のクラス・関数・メソッド・プロパティ構造と厳密に一致**させる
+  - メソッド名・引数・戻り値・順序・static/instance区別・プロパティ名なども完全一致が必須
+  - 余計な定義や重複定義が混入しないよう注意する
+- スケルトンは「実装詳細を含まず、構造のみ」を記述する
+- コードやテストの追加・修正時は、**必ず skel/ 側も同時に更新**する
+- skel/ 側の構造は `test/skeleton-structure-validation.test.ts` で自動検証される
+  - 差分が検出された場合は、skel/ 側を本体に合わせて速やかに修正する
+
+#### スケルトンの目的
+- 実装とテストの構造同期・設計意図の明示・自動検証による品質担保
+
+#### 運用上の注意
+- skel/ 側の構造不一致はCIで検出される。必ず全テスト合格状態を維持する
+- スケルトンの自動生成・修正時は、不要な重複やゴミ定義が混入しないように注意する
+- ロジックの修正を行う前に、skel/ ディレクトリにあるスケルトンファイルを更新する
+- `test/skeleton-structure-validation.test.ts` だけを実行して、構造が一致していることを確認する
+- テストの実行とコードの修正は同時に行わない
+  - テスト失敗した場合は、修正方針について指示を仰ぐこと
+
+---
+
+## 6. 推奨運用フロー
+
+- 仕様・設計・構造は `skel/` で管理し、実装と同期
+- 変更計画・TODOは `change_plans/`, `todo_plans/` で管理
+- コード・テスト・ドキュメント・CI/CD・整形ルールを全てリポジトリに含める
+
+## エラー処理とロギング
+
+- エラーハンドリングは `try/catch` または `Error Boundary` で捕捉し、必ず `logger.error`
+  でスタックトレースを出力する。
+
+## テスト方針
+
+- **TDD ファースト**: ユースケース単位で `describe → it` を書いてから実装する。
+- **Unit Test**: vitest、80% 以上の branch coverage を目標とする。
+- テスト用にファイルが必要な場合は、テストケース内で実行時に作るのではなく、予め `test/fixtures/`
+  に作成しておくこと。
+- テストは必ず docker コンテナ上で実行すること。
+
+```sh
+rm -rf node_modules package-lock.json
+docker run --rm -v $(pwd):/app -w /app node:20 npm install
+docker run --rm -v $(pwd):/app -w /app -e NODE_ENV=test node:20 npm run test
+```

package/artifact/instructions/rules/coding/openai.md

@@ -0,0 +1,39 @@
+---
+type: coding-rules
+category: api-usage
+focus: openai
+---
+
+# OpenAI API Usage Guidelines
+
+## Model Selection for Sample Code
+
+When writing sample code or examples that access OpenAI models (such as in the `example/` directory or any demonstration code), **always use `gpt-4.1-mini`** as the default model.
+
+### Rationale
+
+- `gpt-4.1-mini` provides an optimal balance of performance and cost for sample/demonstration purposes
+- Consistent model usage across examples ensures predictable behavior and costs
+- This model is suitable for most demonstration scenarios while being more cost-effective than larger models
+
+### Exceptions
+
+The only cases where you should deviate from `gpt-4.1-mini` in sample code:
+
+1. **Specific feature demonstrations**: When the example specifically demonstrates features only available in other models
+2. **Performance comparisons**: When comparing different models' capabilities
+3. **Cost optimization examples**: When demonstrating cost-aware model selection
+
+In these cases, clearly document why a different model is being used.
+
+### Environment Configuration
+
+Sample code should allow users to override the model while maintaining `gpt-4.1-mini` as the sensible default through environment variables.
+
+## Error Handling
+
+Sample code should include appropriate error handling for OpenAI API calls.
+
+## API Key Management
+
+Always use environment variables for API keys in sample code. Never hardcode API keys in examples.