@aramassa/ai-rules 0.9.5 → 0.9.7

package/artifact/prompts/github-copilot/copilot-agent-environment.prompt.md

@@ -0,0 +1,462 @@
+---
+type: prompt
+category: github-copilot
+focus: agent-environment
+applyTo: ".github/workflows/copilot-setup-steps.yml"
+human-instruction: |-
+  ## GitHub Copilot Coding Agent 環境カスタマイズについて
+  
+  このルールは、GitHub Copilot Coding Agent の開発環境をカスタマイズする方法を説明しています。
+  以下の点で人間の判断が重要です：
+  
+  - **環境要件の分析**: プロジェクトに必要なツールや依存関係の特定
+  - **セキュリティの考慮**: シークレットや認証情報の適切な管理
+  - **パフォーマンス最適化**: ランナーサイズやキャッシュ戦略の選択
+  - **コスト管理**: larger runners や self-hosted runners の費用対効果の判断
+  
+  AIは設定ファイルの生成を支援できますが、プロジェクト固有の要件やセキュリティポリシーの判断は人間が行う必要があります。
+---
+
+# GitHub Copilot Coding Agent 環境カスタマイズガイド
+
+## 概要
+
+GitHub Copilot Coding Agent は、独自のエフェメラルな開発環境（GitHub Actions によって提供）でタスクを実行します。この環境をカスタマイズすることで、エージェントがより効果的にコードの探索、変更、テスト、リンティングなどを実行できるようになります。
+
+本ドキュメントは、GitHub 公式ドキュメントに基づいて作成されています：
+https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment
+
+## Copilot 環境のカスタマイズについて
+
+### 基本概念
+
+Copilot Coding Agent は、タスク実行時に以下の環境を利用します：
+
+- **エフェメラル環境**: タスクごとに作成され、完了後に破棄される一時的な環境
+- **GitHub Actions ベース**: GitHub Actions のランナー上で実行される
+- **独立した環境**: 各タスクは隔離された環境で実行される
+
+### カスタマイズ可能な項目
+
+以下の項目をカスタマイズできます：
+
+1. **ツールや依存関係のプリインストール**
+2. **環境変数の設定**
+3. **より大きな GitHub ホステッドランナーへのアップグレード**
+4. **Git Large File Storage (LFS) の有効化**
+5. **セルフホステッドランナーの使用（ARC 経由）**
+
+## ツールや依存関係のプリインストール
+
+### 概要
+
+Copilot はプロジェクトのビルド、コンパイル、自動テスト、リンターの実行などを行うため、プロジェクトの依存関係をインストールする必要があります。Copilot は自動的にこれらを発見してインストールしようとしますが、以下の理由でプリインストールが推奨されます：
+
+- **速度**: 試行錯誤によるインストールは時間がかかる
+- **信頼性**: LLM の非決定的な性質により、インストールが不安定になる可能性
+- **制限事項**: プライベートな npm レジストリなど、Copilot が自動的にアクセスできない依存関係がある
+
+### プリインストールの設定方法
+
+`.github/workflows/copilot-setup-steps.yml` ファイルを作成し、カスタムセットアップステップを定義します：
+
+```yaml
+name: Copilot setup steps
+
+on:
+  workflow_dispatch:
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      
+      # Node.js プロジェクトの例
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      # Python プロジェクトの例
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+      
+      # カスタムツールのインストール例
+      - name: Install custom tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y your-custom-tool
+```
+
+### プライベート npm レジストリへの認証
+
+プライベート npm レジストリを使用する場合：
+
+```yaml
+- name: Setup .npmrc
+  run: |
+    echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+    echo "@your-scope:registry=https://your-private-registry.com/" >> ~/.npmrc
+
+- name: Install dependencies
+  run: npm ci
+```
+
+### ベストプラクティス
+
+- **キャッシュの活用**: `cache` オプションを使用して依存関係のダウンロード時間を短縮
+- **必要最小限のインストール**: 実際に必要なツールのみをインストール
+- **バージョン固定**: ツールのバージョンを明示的に指定して、一貫性を確保
+
+## 環境変数の設定
+
+### 概要
+
+Copilot の環境で使用するツールや依存関係を設定・認証するために、環境変数を設定できます。
+
+### 設定方法
+
+#### 1. GitHub Actions の変数またはシークレットを作成
+
+**機密情報を含む場合**（パスワード、API キーなど）:
+- GitHub Actions のシークレットを使用
+
+**機密情報を含まない場合**:
+- GitHub Actions の変数を使用
+
+#### 2. リポジトリ設定での作成手順
+
+1. GitHub のリポジトリページに移動
+2. **Settings** をクリック
+3. サイドバーの **Secrets and variables** > **Actions** をクリック
+4. **Variables** タブまたは **Secrets** タブを選択
+5. **New repository variable** または **New repository secret** をクリック
+6. 変数名とを入力
+   - **Environment**: `copilot` を選択（重要）
+7. **Add variable** または **Add secret** をクリック
+
+#### 3. ワークフローでの使用例
+
+```yaml
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    environment: copilot  # 環境を指定
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Configure tool with environment variables
+        env:
+          API_KEY: ${{ secrets.API_KEY }}
+          API_ENDPOINT: ${{ vars.API_ENDPOINT }}
+        run: |
+          echo "API_ENDPOINT=$API_ENDPOINT" >> $GITHUB_ENV
+          # ツールの設定
+          tool configure --api-key "$API_KEY"
+```
+
+### セキュリティのベストプラクティス
+
+- **シークレットの使用**: 機密情報は必ず GitHub Actions のシークレットとして保存
+- **環境の指定**: `environment: copilot` を明示的に指定
+- **最小権限の原則**: 必要最小限の権限のみを付与
+- **シークレットのローテーション**: 定期的にシークレットを更新
+
+## より大きな GitHub ホステッドランナーへのアップグレード
+
+### 概要
+
+デフォルトでは、Copilot は標準的な GitHub Actions ランナー（限られたリソース）で動作します。より大きなランナーを使用することで、以下のメリットがあります：
+
+- **より多くの RAM、CPU、ディスクスペース**
+- **高度なネットワーク制御**
+- **パフォーマンスの向上**（依存関係のダウンロードやテスト実行時）
+
+### 設定方法
+
+#### 1. Larger runners の追加
+
+GitHub のドキュメントを参照: [Larger runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-larger-runners)
+
+#### 2. Copilot 環境での有効化
+
+リポジトリ設定で、`copilot` 環境に larger runners へのアクセスを許可します：
+
+1. **Settings** > **Environments** > **copilot** に移動
+2. **Deployment protection rules** で larger runners を選択
+3. 変更を保存
+
+#### 3. ワークフローでの指定
+
+```yaml
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest-4-cores  # larger runner を指定
+    # または
+    # runs-on: ubuntu-latest-8-cores
+    # runs-on: ubuntu-latest-16-cores
+    steps:
+      - uses: actions/checkout@v4
+      # ... その他のステップ
+```
+
+### 考慮事項
+
+- **コスト**: Larger runners は標準ランナーよりもコストが高い
+- **必要性の評価**: パフォーマンス問題が実際に発生している場合にのみ使用を検討
+- **適切なサイズ選択**: プロジェクトの要件に応じた適切なサイズを選択
+
+## セルフホステッドランナーの使用（ARC）
+
+### 概要
+
+ARC (Actions Runner Controller) を使用して、セルフホステッドランナーで Copilot Coding Agent を実行できます。
+
+### 前提条件
+
+- ARC マネージドスケールセットが環境にセットアップされている
+- Ubuntu x64 Linux ランナー（Windows や macOS は非対応）
+- 永続的なランナーは推奨されない（オートスケーリングシナリオ向け）
+
+### 設定手順
+
+#### 1. ARC スケールセットのセットアップ
+
+GitHub Actions Runner Controller のドキュメントを参照:
+[Actions Runner Controller](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller)
+
+#### 2. ワークフローでの指定
+
+```yaml
+jobs:
+  copilot-setup-steps:
+    runs-on: arc-scale-set-name  # ARC スケールセット名を指定
+    steps:
+      - uses: actions/checkout@v4
+      # ... その他のステップ
+```
+
+#### 3. ファイアウォールの無効化
+
+セルフホステッドランナーを使用する場合、リポジトリ設定で Copilot coding agent の統合ファイアウォールを無効化する必要があります。
+
+**⚠️ 警告**: ファイアウォールを無効化すると、Copilot と セルフホステッド環境間の隔離が減少します。代替のネットワークセキュリティ制御を実装する必要があります。
+
+### セキュリティの考慮事項
+
+#### 必須エンドポイント
+
+セルフホステッドランナーから以下のエンドポイントへのアクセスを許可する必要があります：
+
+- `api.githubcopilot.com`
+- `uploads.github.com`
+- `user-images.githubusercontent.com`
+
+その他、GitHub Actions セルフホステッドランナーに必要なホストの完全なリストについては、[Self-hosted runners reference](https://docs.github.com/en/actions/reference/runners/self-hosted-runners#accessible-domains-by-function) を参照してください。
+
+#### セキュリティ対策
+
+- **ネットワーク通信制御**: ホスティング環境に厳格なネットワーク通信制御を実装
+- **最小権限**: ランナーに必要最小限の権限のみを付与
+- **監視**: ランナーの活動を継続的に監視
+- **隔離**: 可能な限り、Copilot 専用の隔離された環境でランナーを実行
+
+## Git Large File Storage (LFS) の有効化
+
+### 概要
+
+Git LFS を使用してリポジトリに大きなファイルを保存している場合、Copilot の環境で Git LFS をインストールし、LFS オブジェクトをフェッチする必要があります。
+
+### 設定方法
+
+`copilot-setup-steps` ジョブに `actions/checkout` ステップを追加し、`lfs` オプションを `true` に設定します：
+
+```yaml
+name: Copilot setup steps
+
+on:
+  workflow_dispatch:
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read  # actions/checkout に必要
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          lfs: true  # Git LFS を有効化
+      
+      # ... その他のセットアップステップ
+```
+
+### 注意事項
+
+- **帯域幅とストレージ**: Git LFS のファイルは GitHub の LFS 帯域幅とストレージクォータを消費します
+- **パフォーマンス**: 大きなファイルのダウンロードには時間がかかる可能性があります
+- **必要性の確認**: プロジェクトで実際に LFS ファイルが必要な場合にのみ有効化
+
+## ワークフロー全体の例
+
+### 基本的な Node.js プロジェクト
+
+```yaml
+name: Copilot setup steps
+
+on:
+  workflow_dispatch:
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    environment: copilot
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          lfs: false  # LFS が不要な場合
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build project
+        run: npm run build
+```
+
+### 複雑なプロジェクト（複数言語、カスタムツール）
+
+```yaml
+name: Copilot setup steps
+
+on:
+  workflow_dispatch:
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest-4-cores  # larger runner を使用
+    environment: copilot
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          lfs: true  # Git LFS を有効化
+      
+      # Node.js セットアップ
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      # Python セットアップ
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      # カスタムツールのインストール
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential libpq-dev
+      
+      # プライベートレジストリへの認証
+      - name: Setup .npmrc
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+      
+      # 依存関係のインストール
+      - name: Install Node.js dependencies
+        run: npm ci
+      
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+      
+      # 環境変数の設定
+      - name: Configure environment
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          API_KEY: ${{ secrets.API_KEY }}
+        run: |
+          echo "ENVIRONMENT=development" >> $GITHUB_ENV
+      
+      # ビルド
+      - name: Build project
+        run: npm run build
+```
+
+## トラブルシューティング
+
+### よくある問題と解決策
+
+#### 1. 依存関係のインストールが失敗する
+
+**原因**:
+- プライベートレジストリへの認証が不足
+- ネットワーク制限
+
+**解決策**:
+- シークレットと認証設定を確認
+- 必要なエンドポイントへのアクセスを許可
+
+#### 2. パフォーマンスが遅い
+
+**原因**:
+- 標準ランナーのリソースが不足
+- キャッシュが有効化されていない
+
+**解決策**:
+- Larger runners へのアップグレードを検討
+- 依存関係のキャッシュを有効化
+
+#### 3. セルフホステッドランナーで接続エラー
+
+**原因**:
+- ファイアウォールの設定が不適切
+- 必要なエンドポイントへのアクセスがブロックされている
+
+**解決策**:
+- Copilot 用のファイアウォールを無効化
+- 必要なエンドポイントをホワイトリストに追加
+
+## 関連ドキュメント
+
+- [Customizing or disabling the firewall for GitHub Copilot coding agent](https://docs.github.com/en/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent)
+- [Larger runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-larger-runners)
+- [Actions Runner Controller](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller)
+- [Self-hosted runners reference](https://docs.github.com/en/actions/reference/runners/self-hosted-runners)
+- [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
+
+## まとめ
+
+GitHub Copilot Coding Agent の環境カスタマイズにより、以下が実現できます：
+
+✅ **高速化**: 依存関係のプリインストールによる実行時間の短縮
+✅ **信頼性向上**: 確実な依存関係のインストール
+✅ **柔軟性**: プロジェクト固有の要件への対応
+✅ **セキュリティ**: 適切な認証と環境変数の管理
+✅ **パフォーマンス最適化**: Larger runners やセルフホステッドランナーの活用
+
+プロジェクトの要件に応じて、適切なカスタマイズを実施してください。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aramassa/ai-rules",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "This repository collects guidelines and instructions for developing AI agents. It contains documents covering communication rules, coding standards, testing strategies, and general operational practices.",
   "workspaces": [
     "packages/extract",

package/presets/prompts/apply-fix.yaml

@@ -0,0 +1,16 @@
+description: 計画済みの修正をrepoルールに沿って適用するワークフロー。skel先行更新、構造検証、テスト運用、docs更新、PR/Issueコメントによる進捗共有を標準化します。
+
+config:
+  baseDir: .github/prompts
+
+recipe:
+  - title: "prompt apply-fix ワークフロー"
+    out: "apply-fix.prompt.md"
+    type: "prompt"
+    filters:
+      category: "workflow"
+      focus: "implementation-application"
+    frontmatter:
+      description: "計画済みの修正をrepoルールに沿って適用。skel先行更新、構造検証、テスト運用、docs更新、PR/Issueコメントで進捗共有を標準化。"
+      agent: "agent"
+      applyTo: "**/*"

package/presets/prompts/fix-implementation.yaml

@@ -0,0 +1,16 @@
+description: 実装完了後のワークフローを自動化。e2eテスト実行、PR本文更新、Checksへの登録を効率的に実施します。
+
+config:
+  baseDir: .github/prompts
+
+recipe:
+  - title: "prompt fix-implementation ワークフロー"
+    out: "fix-implementation.prompt.md"
+    type: "prompt"
+    filters:
+      category: "workflow"
+      focus: "implementation-completion"
+    frontmatter:
+      description: "実装完了後のワークフローを自動化。e2eテスト実行、PR本文更新、Checksへの登録を効率的に実施。"
+      agent: "agent"
+      applyTo: "**/*"

package/presets/prompts/github-copilot-agent.yaml

@@ -0,0 +1,15 @@
+description: GitHub Copilot Coding Agent の環境カスタマイズに関するプロンプトです。
+
+config:
+  baseDir: .github/prompts
+
+recipe:
+  - title: "GitHub Copilot Agent Environment Customization"
+    out: "copilot-agent-environment.prompt.md"
+    type: "prompt"
+    filters:
+      category: "github-copilot"
+      focus: "agent-environment"
+    frontmatter:
+      description: "GitHub Copilot Coding Agent の開発環境をカスタマイズするための包括的なガイド。依存関係のプリインストール、環境変数、larger runners、Git LFS などを網羅。"
+      applyTo: ".github/workflows/copilot-setup-steps.yml"

package/presets/prompts/plan-fix.yaml

@@ -12,4 +12,5 @@ recipe:
       focus: "plan-to-implementation"
     frontmatter:
       description: "VS Code Plan モードから Agent Coding への移行を自動化。計画完成後の Git/GitHub 操作を簡略化し、効率的な開発ワークフローを実現。"
+      agent: "agent"
       applyTo: "**/*"