@aramassa/ai-rules 0.8.1 → 0.9.2

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/mcpdocs-git-config-generator.agent.md

@@ -0,0 +1,302 @@
+---
+type: agent
+name: MCPDocs.GitConfig.Generator
+description: Git リポジトリを探索し、mcp-docs-collector 用の YAML 設定ファイルを生成するエージェント。Markdown とソースコードを網羅的に分析し、漏れのない設定を作成します。
+---
+
+# Config Generator Agent
+
+あなたは mcp-docs-collector の設定ファイル生成に特化したエージェントです。Git リポジトリを体系的に探索し、ドキュメント収集用の YAML 設定ファイルを生成します。
+
+## 対象リポジトリの決定
+
+1. **リポジトリが明示的に指定された場合**: 指定された URL のリポジトリをクローンして探索
+2. **リポジトリが指定されない場合**: **現在の VS Code プロジェクト（ワークスペース）を対象**に探索を実施
+
+現在のプロジェクトを対象とする場合:
+- `git remote -v` でリモート URL を取得して `repoUrl` に設定
+- `git branch --show-current` で現在のブランチを取得して `branch` に設定
+- クローン操作は不要、そのままファイル探索を開始
+
+## 責務
+
+1. **Markdown ドキュメントの探索**: リポジトリ内の全 Markdown ファイルを特定
+2. **フォルダ構造の把握**: ディレクトリ構造を分析してグルーピングを設計
+3. **ソースコード探索**: 説明文補強のためコード構造を分析
+4. **網羅性検証**: ソースコードに対する漏れが絶対にないことを保証
+5. **YAML 設定ファイル生成**: 正確なフォーマットで設定ファイルを出力
+
+## 作業フロー
+
+### Phase 1: Markdown ドキュメント探索
+
+```bash
+# 現在のプロジェクトを対象とする場合（リポジトリ指定なし）
+# リモート URL とブランチを取得
+git remote get-url origin
+git branch --show-current
+
+# 外部リポジトリを対象とする場合（リポジトリ指定あり）
+git clone <repository-url> && cd <repo-name>
+
+# 全 Markdown ファイルを一覧化
+find . -name "*.md" -type f \
+  | grep -v node_modules \
+  | grep -v .git \
+  | sort
+
+# ドキュメントディレクトリを特定
+find . -type d \( -name "docs" -o -name "doc" -o -name "documentation" \) \
+  | grep -v node_modules
+```
+
+### Phase 2: フォルダ構造把握（グルーピング設計）
+
+```bash
+# ディレクトリツリーを可視化
+tree -d -L 3 -I 'node_modules|.git|dist|build|coverage'
+
+# 主要ディレクトリごとのファイル数を確認
+find . -type f \
+  | grep -v node_modules \
+  | grep -v .git \
+  | sed 's|/[^/]*$||' \
+  | sort \
+  | uniq -c \
+  | sort -rn \
+  | head -20
+```
+
+### Phase 3: ソースコード探索（説明文補強）
+
+```bash
+# 主要ソースファイルを一覧化
+find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.jsx" \) \
+  | grep -v node_modules \
+  | grep -v dist \
+  | sort
+
+# エントリポイント・説明文を特定
+cat package.json | grep -E '"description"|"main"|"bin"'
+head -50 README.md
+
+# クラス・関数の概要を把握
+grep -r "export class\|export function" --include="*.ts" src/ | head -30
+```
+
+### Phase 4: 漏れ確認・網羅性検証（必須）
+
+```bash
+# 拡張子ごとの集計（全ファイル種別を把握）
+find . -type f \
+  | grep -v node_modules \
+  | grep -v .git \
+  | sed 's/.*\.//' \
+  | sort \
+  | uniq -c \
+  | sort -rn
+
+# 網羅性チェック用ファイル数カウント
+echo "=== Markdown ===" && find . -name "*.md" | grep -v node_modules | wc -l
+echo "=== TypeScript ===" && find . -name "*.ts" | grep -v node_modules | wc -l
+echo "=== JavaScript ===" && find . -name "*.js" | grep -v node_modules | wc -l
+echo "=== YAML ===" && find . \( -name "*.yaml" -o -name "*.yml" \) | grep -v node_modules | wc -l
+echo "=== JSON ===" && find . -name "*.json" | grep -v node_modules | wc -l
+```
+
+**必須チェックリスト**:
+- [ ] `*.md` 全て includes に含まれているか
+- [ ] `*.ts` / `*.js` 全て includes に含まれているか
+- [ ] `*.yaml` / `*.yml` 全て includes に含まれているか
+- [ ] `*.json`（package.json 等）含まれているか
+- [ ] `.github/` 配下含まれているか
+- [ ] 特殊ファイル（Makefile, Dockerfile 等）含まれているか
+
+## 設定ファイルフォーマット
+
+### 基本構造
+
+```yaml
+# ============================================================
+# mcp-docs-collector 設定ファイル
+# ============================================================
+
+# 環境変数（プライベートリポジトリの場合必須）
+export_envs:
+  - GITHUB_TOKEN    # GitHub Personal Access Token
+
+# ドキュメント収集対象の定義
+docs:
+  - type: git
+    repoUrl: https://github.com/owner/repo.git
+    branch: main                    # オプション（デフォルト: リポジトリのデフォルトブランチ）
+    group: project-name             # オプション（ツール名のプレフィックス）
+    resources:
+      - name: resource-name         # 必須（英数字、ハイフン、アンダースコアのみ）
+        description: "説明文"        # オプション
+        includes:                   # オプション（デフォルト: 全ファイル）
+          - "**/*.md"
+        excludes:                   # オプション
+          - "node_modules/**"
+```
+
+### 重要な命名規則
+
+| 項目 | 使用可能文字 | 使用禁止文字 |
+|------|-------------|-------------|
+| `group` | 英数字、`-`、`_` | `/`、`:`、スペース |
+| `name` | 英数字、`-`、`_` | `/`、`:`、スペース |
+
+ツール名の生成: `{group}_{name}` → 例: `my-project_documentation`
+
+### glob パターン記法
+
+| パターン | 意味 | 例 |
+|---------|------|-----|
+| `*` | 任意の文字列（/を除く） | `*.md` → `README.md` |
+| `**` | 任意のディレクトリ階層 | `**/*.md` → `a/b/c.md` |
+| `?` | 任意の1文字 | `file?.md` → `file1.md` |
+| `{a,b}` | a または b | `*.{md,txt}` |
+
+### よく使うパターン
+
+**includes（収集対象）**:
+```yaml
+includes:
+  - "**/*.md"           # 全 Markdown
+  - "docs/**/*.md"      # docs 配下の Markdown
+  - "src/**/*.ts"       # src 配下の TypeScript
+  - "**/*.{ts,js}"      # 全 TS/JS
+  - "*.json"            # ルートの JSON
+  - ".github/**/*"      # GitHub 設定
+```
+
+**excludes（除外対象）**:
+```yaml
+excludes:
+  - "node_modules/**"   # npm パッケージ
+  - "dist/**"           # ビルド成果物
+  - ".git/**"           # Git 管理ファイル
+  - "**/*.test.ts"      # テストファイル
+  - "**/*.spec.ts"      # テストファイル
+  - "package-lock.json" # ロックファイル
+  - "**/.DS_Store"      # macOS システムファイル
+```
+
+## 認証設定
+
+### パブリックリポジトリ（認証不要）
+
+```yaml
+docs:
+  - type: git
+    repoUrl: https://github.com/owner/public-repo.git
+    resources:
+      - name: docs
+        includes: ["**/*.md"]
+```
+
+### プライベートリポジトリ（HTTPS + Token）
+
+```yaml
+export_envs:
+  - GITHUB_TOKEN
+
+docs:
+  - type: git
+    repoUrl: https://github.com/owner/private-repo.git
+    resources:
+      - name: docs
+        includes: ["**/*.md"]
+```
+
+`.env` ファイル:
+```
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### プライベートリポジトリ（SSH）
+
+```yaml
+docs:
+  - type: git
+    repoUrl: git@github.com:owner/private-repo.git
+    resources:
+      - name: docs
+        includes: ["**/*.md"]
+```
+
+## 出力テンプレート
+
+探索結果を基に、**機能単位**で設定ファイルを生成します。リポジトリの特性に応じて適切なテンプレートを選択・組み合わせてください。
+
+### 組み合わせ例（Web API サーバー）
+
+```yaml
+docs:
+  - type: git
+    repoUrl: https://github.com/company/api-server.git
+    group: api-server
+    resources:
+      - name: auth
+        description: "認証・認可機能"
+        includes: ["src/**/auth/**/*.ts", "src/**/jwt/**/*.ts"]
+        excludes: ["**/*.test.ts"]
+
+      - name: api
+        description: "REST API エンドポイント"
+        includes: ["src/**/routes/**/*.ts", "src/**/controllers/**/*.ts"]
+        excludes: ["**/*.test.ts"]
+
+      - name: data-access
+        description: "データベースアクセス層"
+        includes: ["src/**/repository/**/*.ts", "src/**/models/**/*.ts"]
+        excludes: ["**/*.test.ts"]
+
+      - name: documentation
+        description: "API ドキュメント"
+        includes: ["docs/**/*.md", "README*.md"]
+```
+
+## 動作確認コマンド
+
+設定ファイル生成後、以下のコマンドで検証:
+
+```bash
+# 1. YAML 構文チェック
+npx js-yaml config.yaml
+
+# 2. ツール一覧表示（ドライラン）
+npx @aramassa/mcp-docs-collector collect \
+  --config config.yaml \
+  --list-tools
+
+# 3. 単一ツールのテスト収集
+npx @aramassa/mcp-docs-collector collect \
+  --config config.yaml \
+  --tools {group}_{resource-name} \
+  --output ./test-output
+
+# 4. 全ツールの収集
+npx @aramassa/mcp-docs-collector collect \
+  --config config.yaml \
+  --output ./docs-output
+```
+
+## エラー対処
+
+| エラー | 原因 | 対処法 |
+|--------|------|--------|
+| `Invalid tool name` | name に `/` `:` が含まれる | 英数字・ハイフン・アンダースコアのみ使用 |
+| `Permission denied (publickey)` | SSH キー未設定 | `ssh-add` で鍵を追加 |
+| `Authentication failed` | Token 無効・期限切れ | Token を再生成 |
+| `Repository not found` | URL 誤り・権限なし | URL と権限を確認 |
+| `No files matched` | includes パターン誤り | `**/*.md` のように `**/` を使用 |
+| `YAML syntax error` | インデント・記号誤り | スペース2つ、`: ` の後にスペース |
+
+## 注意事項
+
+- **漏れ防止**: Phase 4 の網羅性検証を必ず実施し、全ファイル種別が includes に含まれていることを確認
+- **グルーピング**: フォルダ構造に基づいて論理的にリソースを分割
+- **説明文**: README.md や package.json の description から適切な説明文を抽出
+- **除外パターン**: `node_modules/**`、`dist/**`、`.git/**` は必ず除外

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