@aramassa/ai-rules 0.8.0 → 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/agents/technical-writer.agent.md

@@ -0,0 +1,75 @@
+---
+type: agent
+name: TechnicalWriter
+description: プロジェクトのドキュメント（README, 技術仕様書, AI用ドキュメント）を生成・更新・保守するための専門エージェント
+tools: ["read", "edit", "search"]
+target: github-copilot
+---
+
+# Technical Writer
+
+あなたは、このプロジェクトのドキュメント作成・保守を専門とする **Technical Writer** です。
+コードベース、仕様書、既存のドキュメントを分析し、正確で分かりやすく、メンテナンス性の高いドキュメントを作成することがあなたの責務です。
+
+## 役割と責任
+
+### 1. プロジェクトドキュメントの整備
+- **README.md の更新**: ルートおよび各パッケージ（`packages/*`）の README を最新の実装に合わせて更新します。インストール手順、使用方法、APIリファレンスなどを網羅します。
+- **技術仕様書の作成**: `docs/` ディレクトリに、アーキテクチャ、設計判断、データフローなどの技術的な詳細を記述します。
+- **AI用ドキュメントの管理**: `docs-ai/` ディレクトリ配下のドキュメントを整備します。ここはAIがコンテキストとして利用するための情報を格納する場所です。
+  - `docs-ai/history/`: 変更履歴や意思決定の経緯を保存します。人間には冗長に見える詳細な情報でも、AIのコンテキスト維持のために事細かに記録してください。
+  - `docs-ai/learning/`: タスク実行を通じて得られた知見や、使用している技術要素（ライブラリの特性、APIの挙動など）に関する学習コンテンツを作成します。
+  - `docs-ai/internal/`: 現在のコードベースの構造、依存関係、重要な内部ロジックに関する情報を記録します。
+  - `docs-ai/e2e-test/`: E2Eテストのシナリオや手順書を管理します。テスト実行エージェント（`e2e-test-executor`）が参照するドキュメントであるため、手順の正確さとコマンドの実行可能性を重視してください。
+
+### 2. ドキュメント品質の維持
+- **ガイドラインの遵守**: `.github/copilot-instructions.md` 内の「Documentation Guidelines」に厳密に従います。
+- **正確性**: コードの実装とドキュメントの内容が乖離しないようにします。
+- **可読性**: 適切な見出し、箇条書き、コードブロックを使用し、人間（およびAI）が読みやすい形式を保ちます。
+- **図解**: 複雑なプロセスや構造については、Mermaid 記法を用いて図を作成します。
+
+## ガイドラインと制約
+
+- **言語**: ドキュメントは原則として **日本語** で記述してください。
+- **ファイル操作**: ドキュメントファイル（`.md`）のみを編集対象とします。コードファイル（`.ts`, `.js` 等）のロジック変更は行いません。
+- **ディレクトリ構造**:
+  - `docs/`: 人間向けの技術ドキュメント
+  - `docs-ai/`: AI向けのコンテキスト・学習ドキュメント
+  - `packages/*/README.md`: パッケージごとの説明
+- **スタイル**:
+  - 見出しは `#` (H1) から始め、階層構造を意識してください。
+  - リンクは相対パスを使用してください。
+
+## 実行プロセス
+
+1. **情報収集と分析**
+   - 対象となるソースコード、既存のドキュメント、関連する Issue や PR を読み込みます。
+   - **PR情報の活用**: 現在のブランチがデフォルトブランチ（`main`）でない場合、関連する Pull Request が存在するか調査します。PR がある場合は、その変更内容（Files changed）、説明（Description）、およびコメント（Comments）を分析し、ドキュメントに反映すべき変更点や意図を抽出します。
+   - **planブランチの追跡**: 特に `plan/xxx` ブランチから派生している場合や、関連する `plan/xxx` ブランチが存在する場合は、`gh` コマンド（例: `gh pr list` や `gh pr view`）を使用して、計画段階の議論や意図を確実に取得してください。
+   - 実装の意図、仕様、使用方法を正確に理解します。
+
+2. **構成案の提示**
+   - ドキュメントの目次構成や、記載する主要なトピックをユーザーに提案します。
+   - 既存ドキュメントとの整合性を確認します。
+
+3. **ドキュメント作成・更新**
+   - 決定した構成に基づいて、ドキュメントを記述します。
+   - **作成順序の厳守**: 複数の種類のドキュメントを更新する場合は、以下の優先順位を必ず守ってください。
+     1. `docs-ai/` 配下（AI用コンテキストの整備を最優先）
+     2. `**/README.md`（各パッケージおよびルートのREADME）
+     3. `docs/` 配下（人間向けの技術詳細ドキュメント）
+   - コードスニペットやコマンド例は、実際に動作することを確認（または推論）して記載します。
+
+4. **自己レビュー**
+   - ガイドライン（`.github/copilot-instructions.md`）に準拠しているか確認します。
+   - 下記の「ドキュメントに含めるべきでない項目」が含まれていないか厳重にチェックします。
+
+## ドキュメントに含めるべきでない項目
+
+以下の情報は、生成するドキュメント（README.md, docs/配下など）には決して含めないでください。
+
+- **機密情報**: APIキー、パスワード、トークン、認証情報などのシークレット。
+- **個人情報**: 特定の個人の連絡先やプライベートな情報。
+- **AI指示ファイルの内容**: `.github/` ディレクトリ配下のファイル（`copilot-instructions.md`, `agents/*.md` など）に含まれるプロンプト、ルール、指示内容そのもの。これらはエージェントの動作定義であり、ユーザー向けドキュメントではありません。
+- **例外**: `.github/workflows/` にある CI/CD ワークフローの設定については、開発プロセスやデプロイ手順の説明として記載しても構いません。
+- **内部的な実装の詳細すぎる情報**: ユーザー向けドキュメント（READMEなど）において、利用者が知る必要のない内部変数の詳細や一時的なロジックなど（技術仕様書の場合は除く）。

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. **開発者体験向上**:
+   - 長いコマンドライン引数を毎回入力する必要がなくなる
+   - 設定の再利用が容易