@aramassa/ai-rules 0.8.1 → 0.9.0

package/artifact/agents/agent-creation.agent.md

@@ -1,6 +1,6 @@
 ---
 type: agent
-name: agent-creation
+name: AgentCreation
 description: Specialized assistant for creating GitHub Copilot custom agent profiles with proper structure, tools configuration, and best practices based on official documentation
 target: github-copilot
 tools:
@@ -50,7 +50,7 @@ You are a specialized assistant for creating GitHub Copilot custom agent profile
 
 ```yaml
 ---
-name: unique-agent-identifier
+name: UniqueAgentIdentifier
 description: Clear explanation of agent's purpose and capabilities
 ---
 ```

package/artifact/instructions/package-management.md

@@ -44,6 +44,35 @@ human-instruction: |-
 
 （名称はエコシステムに合わせて「モジュール」「パッケージ」等に読み替えて構いません）
 
+### CLI エントリポイントのファイル命名規則
+
+CLI アプリケーションを作成する際は、以下のファイル命名規則に従ってください。
+
+#### 標準ファイル名
+
+CLI のエントリポイントファイルは **`cli.*`** という名前を使用すること：
+
+- **推奨パターン**: `cli.{拡張子}`
+  - 例: `cli.ts`, `cli.js`, `cli.py`, `cli.rb`, `cli.go`, `cli.rs`
+
+#### 配置場所
+
+- **パッケージルート**: `src/cli.*` または `lib/cli.*`
+- **モノレポ構成**: `packages/{パッケージ名}/src/cli.*`
+
+#### 命名規則の理由
+
+- **一貫性**: プロジェクト間で統一された命名により、CLI エントリポイントの識別が容易
+- **自動化**: `**/cli.*` パターンによる自動的なルール適用とツール連携
+- **明確性**: ファイル名から CLI エントリポイントであることが即座に判別可能
+
+#### 例外
+
+以下の場合は、エコシステムの慣習に従って別の命名を使用することができます：
+
+- Python: `__main__.py` または `{パッケージ名}/__main__.py`
+- 複数の CLI コマンドを持つ場合: `cli/` ディレクトリ配下にコマンド別ファイル
+
 ### ローカルスクリプト／CLI の実行
 
 ローカルの CLI やスクリプトを実行する前に、ビルド工程や生成物が必要な場合は必ず事前に準備（ビルド／インストール／リンク）してください。多くのエコシステムでは、実行コマンドがビルド済みの成果物やインストール済みのエントリポイントを前提にしています。

package/artifact/instructions/rules/development/cli-design.md

@@ -0,0 +1,286 @@
+---
+type: development-rules
+category: cli-design, best-practices, configuration-management
+focus: environment-file-support
+applyTo: "**/cli.*"
+human-instruction: |-
+  ## CLI Environment File Support Guidelines
+  
+  これは言語非依存のCLI設計ガイドラインです。すべてのCLIアプリケーションは、
+  環境変数ファイル（.env file）のサポートを標準機能として実装すべきです。
+  
+  このルールにより、セキュリティ、保守性、開発者体験が大幅に向上します。
+  実装時は各言語のエコシステムに応じた適切なライブラリを使用してください。
+---
+
+# CLI Environment File Support Guidelines
+
+## Overview
+
+すべてのCLIアプリケーションは、設定管理の一環として環境変数ファイルをサポートすべきです。これにより、セキュリティ、保守性、開発者体験が大幅に向上します。
+
+このガイドラインは言語非依存の原則を定義しており、TypeScript、Python、Rust、Goなど、どの言語でCLIを実装する場合にも適用されます。
+
+## 主な要件
+
+### 1. Environment File Option
+
+CLIは必ず `--env-file` オプション（または同等の機能）を提供すること。
+
+**基本要件**:
+- ✅ 相対パスと絶対パスの両方をサポート
+- ✅ オプション指定は任意（デフォルトでは不要）
+- ✅ 複数の環境ファイルを順次読み込める（推奨）
+
+```bash
+# 基本的な使用例
+my-cli command --env-file .env
+my-cli command --env-file .env.production
+my-cli command --env-file ~/.config/my-app/.env
+
+# 複数ファイルの読み込み（推奨）
+my-cli command --env-file .env.base --env-file .env.local
+```
+
+### 2. Variable Priority Order
+
+環境変数の優先順位を明確に定義し、ドキュメント化すること。
+
+**推奨優先順位（高→低）**:
+1. **CLI引数で直接指定された値**（`--var KEY=value`）
+2. **設定ファイル内の変数定義**
+3. **`--env-file`で指定された.envファイル**
+4. **システムの環境変数**
+5. **デフォルト値**
+
+**重要**: この優先順位により、ユーザーは状況に応じて柔軟に設定を上書きできます。
+
+### 3. Error Handling
+
+**Required Error Handling**:
+- ✅ ファイルが存在しない場合: 明確なエラーメッセージ（パスを含む）
+- ✅ ファイルが読み取れない場合: 権限エラーを適切に報告
+- ✅ パースエラー: エラーが発生した行を特定
+- ✅ 相対パスのサポート: カレントディレクトリからの解決
+
+**良いエラーメッセージの例**:
+```
+Error: Environment file not found: .env.production
+  Searched in: /path/to/current/directory/.env.production
+  
+  Tip: Create the file or specify a different path with --env-file
+```
+
+**エラーハンドリングの原則**:
+- **オプション指定なし**: エラーを出さない（.envファイルの使用は任意）
+- **オプション指定あり**: ファイルが存在しない場合はエラー
+- **パースエラー**: 問題のある行番号と内容を明示
+
+### 4. File Format Support
+
+標準的な.envファイル形式をサポート：
+
+**必須サポート**:
+- ✅ コメント（`#`）
+- ✅ 空行の許容
+- ✅ 引用符のサポート（シングル・ダブル）
+- ✅ トリムされた値（前後の空白削除）
+
+**推奨サポート**:
+- 🔶 基本的な変数展開（`${VAR}`）
+- 🔶 デフォルト値の指定（`${VAR:-default}`）
+
+```env
+# コメント
+API_KEY=your_secret_key_here
+DATABASE_URL=postgresql://user:pass@localhost/db
+APP_NAME="My Application"
+
+# 変数展開（推奨）
+BASE_PATH=/var/app
+LOG_PATH=${BASE_PATH}/logs
+```
+
+## Security Considerations
+
+### 1. Sensitive Data Protection
+
+**必須対策**:
+- ✅ API key、パスワード、トークンをログに出力しない
+- ✅ `.env`ファイルを`.gitignore`に追加
+- ✅ `.env.example`サンプルファイルを提供
+- ✅ 機密データは環境変数名で判定（API_KEY, PASSWORD, TOKEN, SECRETなどを含む）
+
+**ログ出力時の安全な処理**:
+```
+✅ Good:
+  API_KEY: [REDACTED]
+  DATABASE_PASSWORD: [REDACTED]
+  APP_NAME: My Application
+
+❌ Bad:
+  API_KEY: sk-1234567890abcdef
+  DATABASE_PASSWORD: mypassword123
+```
+
+### 2. Validation and Sanitization
+
+**推奨検証**:
+- 環境変数の値を適切に検証（型、形式、範囲）
+- 機密データは長さのみチェック（内容は検証しない）
+- URL形式、メールアドレス、数値範囲などの検証
+
+```typescript
+// 良い例: 機密データの検証
+function validateApiKey(key: string): boolean {
+  // 長さのみチェック（実際の値は検証しない）
+  return key.length >= 32;
+}
+
+// 良い例: 非機密データの検証
+function validateUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+## Documentation Requirements
+
+### 1. Usage Examples
+
+CLI のドキュメント（README.md、--help など）に以下を含めること：
+
+**必須内容**:
+- 基本的な使用方法
+- 優先順位の説明
+- エラーケースの例
+
+### 2. .env.example Template
+
+プロジェクトルートに `.env.example` を配置し、必要な設定項目を明示：
+
+```env
+# .env.example - Configuration template for My CLI
+
+# API Configuration
+API_KEY=your_api_key_here
+API_ENDPOINT=https://api.example.com
+
+# Database Configuration
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# Application Settings
+APP_NAME=My Application
+LOG_LEVEL=info
+```
+
+## Testing Requirements
+
+env-file機能のテストを必ず含めること：
+
+**必須テストケース**:
+- ✅ 正常な読み込み
+- ✅ ファイルが存在しない場合のエラー
+- ✅ CLI変数の優先順位
+- ✅ 複数の変数ソースの統合
+- ✅ パースエラーのハンドリング
+- ✅ 相対パス・絶対パスの解決
+
+## Best Practices Summary
+
+### ✅ DO
+
+- Provide `--env-file` option for all CLIs
+- Document variable priority clearly
+- Show helpful error messages with file paths
+- Support relative and absolute paths
+- Provide `.env.example` template
+- Add `.env` to `.gitignore`
+- Validate sensitive values appropriately
+- Test env file loading scenarios
+- Redact sensitive values in logs and error messages
+- Support standard .env file format
+
+### ❌ DON'T
+
+- Require env file when not explicitly specified
+- Log sensitive environment variable values
+- Commit `.env` files to version control
+- Give vague error messages
+- Ignore file permission errors
+- Hard-code default sensitive values
+- Skip validation of critical variables
+- Show full sensitive values in any output
+
+## Migration Guide
+
+既存のCLIに env-file サポートを追加する場合の段階的アプローチ：
+
+### Phase 1: Add --env-file Option (Basic)
+- `--env-file` オプションを追加（オプショナル）
+- 基本的なファイル読み込み機能を実装
+
+### Phase 2: Implement Priority Logic
+- 優先順位ロジックを実装
+- システム環境変数 → env-file → CLI引数の順
+
+### Phase 3: Enhance Error Handling
+- エラーメッセージを改善
+- ファイルパス、行番号を含める
+
+### Phase 4: Add Documentation and Tests
+- README.mdに使用例を追加
+- テストケースを追加
+
+### Phase 5: Provide .env.example
+- `.env.example`を作成
+- `.gitignore`に`.env`を追加
+
+## Related Standards
+
+### 12-Factor App 準拠
+
+このガイドラインは、12-Factor Appの以下の原則に準拠しています：
+
+- **III. Config**: 環境変数による設定の外部化
+- **X. Dev/prod parity**: 開発と本番の環境の一致
+- **XII. Admin processes**: 管理プロセスの実行環境の統一
+
+### Language-Specific Implementation
+
+このルールの具体的な実装は、各言語専用のドキュメントで詳細化されています：
+
+- **Python CLI**: `python-cli.md` - python-dotenv の使用
+- **TypeScript CLI**: dotenv パッケージの使用
+- **Rust CLI**: dotenvy クレートの使用
+- **Go CLI**: godotenv パッケージの使用
+
+各言語のエコシステムに応じた適切なライブラリを使用してください。
+
+## Rationale
+
+### このルールが必要な理由
+
+1. **セキュリティ向上**:
+   - API keyやパスワードなどの機密情報をコードやコマンドライン履歴に残さない
+   - バージョン管理システムから機密情報を除外
+
+2. **環境管理の簡素化**:
+   - 開発/ステージング/本番環境の設定を簡単に切り替え可能
+   - チームメンバー間で設定を共有しやすい
+
+3. **チーム協業の改善**:
+   - `.env.example`により必要な設定項目が明確
+   - オンボーディングの効率化
+
+4. **12-Factor App準拠**:
+   - 業界標準のベストプラクティスへの準拠
+   - クラウドネイティブアプリケーションの原則に従う
+
+5. **開発者体験向上**:
+   - 長いコマンドライン引数を毎回入力する必要がなくなる
+   - 設定の再利用が容易