@aramassa/ai-rules 0.9.5 → 0.9.7

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

@@ -304,6 +304,14 @@ In case of naming conflicts, lowest level takes precedence:
 2. Organization-level agent
 3. Enterprise-level agent (lowest priority)
 
+### Automation Considerations
+
+**Avoid using `/dev/null` in agent prompts or tool configurations:**
+- Using `/dev/null` can cause automation workflows to stop or hang
+- This is particularly problematic in CI/CD pipelines and automated testing
+- Instead, use proper output handling or logging mechanisms
+- If output suppression is needed, use tool-specific options or environment configurations
+
 ## MCP Server Configuration (Organization/Enterprise Only)
 
 ### Basic MCP Server Setup

package/artifact/instructions/git-rules.md

@@ -145,3 +145,11 @@ main
 2. **CI/CD安定性**: パイプラインの失敗率低下
 3. **開発効率**: 明確なプロセス定義による作業手順統一
 4. **パッケージ品質**: npm publishable な状態の維持
+
+## ブランチのクリーンアップ（リモートで削除済みのみ）
+
+リモートで削除されたブランチだけをローカルから削除し、ローカルでのみ存在するブランチは残す。
+
+```
+git fetch --prune && git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -r git branch -D
+```

package/artifact/instructions/rules/test/e2e-cmd.md

@@ -0,0 +1,323 @@
+---
+type: test
+category: e2e-test
+focus: command-line-testing
+applyTo: "todo_plans/**/e2e-cmd.md"
+---
+
+# E2E コマンドラインテスト計画ガイドライン
+
+## 概要
+
+このドキュメントは、`todo_plans/${ISSUE_NUMBER}/e2e-cmd.md` ファイルに記載すべき E2E テストの追加/更新/削除内容に関するガイドラインです。
+
+## 基本原則
+
+### コマンドライン完結の原則
+
+**E2E テストは、原則としてコマンドライン（CLI）上で完結するもののみを対象とします。**
+
+**対象となるテスト**:
+- CLI ツールの動作確認
+- API サーバーの HTTP リクエスト/レスポンス検証（curl、httpie などを使用）
+- ビルドプロセスの実行確認
+- スクリプトの実行と出力検証
+- ファイル操作の確認
+
+**対象外となるテスト**:
+- ブラウザ UI のインタラクション（Playwright、Selenium などを使うもの）
+- デスクトップアプリケーションの GUI 操作
+- モバイルアプリケーションのテスト
+- コマンドラインから実行できないインタラクティブな操作
+
+### なぜコマンドライン完結なのか
+
+- **再現性**: コマンドは完全に記録でき、誰でも同じ手順で実行可能
+- **自動化**: CI/CD パイプラインで容易に実行可能
+- **保守性**: テストスクリプトがシンプルで理解しやすい
+- **環境依存性の最小化**: ブラウザやGUIツールのバージョン差異を避けられる
+
+## e2e-cmd.md の記載内容
+
+### ファイル構成
+
+`todo_plans/${ISSUE_NUMBER}/e2e-cmd.md` ファイルには、以下の内容を記載します：
+
+```markdown
+# E2E テスト計画: [機能名]
+
+## 追加すべきテスト
+
+### テスト1: [テスト名]
+- **目的**: [何を検証するか]
+- **対象ファイル**: [プロジェクトルートからのフルパス]
+- **コマンド**:
+  ```bash
+  # セットアップ
+  npm run build
+  
+  # テスト実行
+  ./dist/cli.js command --option value
+  
+  # 期待する結果
+  # - 終了コード: 0
+  # - 標準出力: "Success message"
+  ```
+- **検証ポイント**:
+  - [ ] 終了コードが正しい
+  - [ ] 標準出力/標準エラー出力が期待通り
+  - [ ] ファイル生成が正しく行われる
+
+## 更新すべきテスト
+
+### テスト2: [既存テスト名]
+- **現在の問題**: [なぜ更新が必要か]
+- **対象ファイル**: docs-ai/e2e-test/[既存ファイル名]
+- **変更内容**:
+  - 変更前: `old command`
+  - 変更後: `new command --new-option`
+- **理由**: [変更理由]
+
+## 削除すべきテスト
+
+### テスト3: [削除するテスト名]
+- **対象ファイル**: docs-ai/e2e-test/[ファイル名]
+- **削除理由**: [なぜ不要になったか]
+```
+
+### 記載のポイント
+
+#### 1. 追加すべきテスト
+
+新機能や改善により、新たに動作確認が必要になったテストを記載します。
+
+**必須項目**:
+- テスト名（何をテストするか明確に）
+- 目的（このテストで何を保証するか）
+- 対象ファイル（プロジェクトルートからのフルパス）
+- 実行コマンド（コピペで実行可能な形式）
+- 検証ポイント（チェックリスト形式）
+
+**良い例**:
+```markdown
+### テスト: CLI のヘルプ表示
+
+- **目的**: CLI が正しくヘルプメッセージを表示することを確認
+- **対象ファイル**: packages/cli/dist/index.js
+- **コマンド**:
+  ```bash
+  cd /home/runner/work/ai-rules/ai-rules
+  ./packages/cli/dist/index.js --help
+  ```
+- **検証ポイント**:
+  - [ ] 終了コード 0
+  - [ ] 使用方法が表示される
+  - [ ] オプション一覧が表示される
+```
+
+**悪い例**:
+```markdown
+### ヘルプのテスト
+- ヘルプが表示されることを確認
+- コマンド: `cli --help`
+```
+
+#### 2. 更新すべきテスト
+
+既存の E2E テストの変更が必要な場合に記載します。
+
+**記載すべき内容**:
+- 既存テストファイルのフルパス（docs-ai/e2e-test/ 配下）
+- 変更前後のコマンド
+- 変更理由
+
+**例**:
+```markdown
+### テスト: presets コマンドの引数変更
+
+- **現在の問題**: 新しいオプション `--format` が追加されたが、既存テストでカバーされていない
+- **対象ファイル**: docs-ai/e2e-test/presets-command-e2e.md
+- **変更内容**:
+  - 変更前: `./dist/cli.js presets`
+  - 変更後: `./dist/cli.js presets --format json`
+- **理由**: JSON 形式の出力を検証するため
+```
+
+#### 3. 削除すべきテスト
+
+不要になったテストや、機能削除により実行できなくなったテストを記載します。
+
+**記載すべき内容**:
+- 削除対象ファイルのフルパス
+- 削除理由
+
+**例**:
+```markdown
+### テスト: 旧形式の config ファイル読み込み
+
+- **対象ファイル**: docs-ai/e2e-test/legacy-config-e2e.md
+- **削除理由**: 旧形式のサポートを終了したため、このテストは不要
+```
+
+## コマンド記述のベストプラクティス
+
+### 1. 絶対パスの使用
+
+```bash
+# ✅ 良い例: プロジェクトルートからの明示的なパス
+cd /home/runner/work/ai-rules/ai-rules
+./dist/cli.js command
+
+# ❌ 悪い例: 相対パスのみ
+./cli.js command
+```
+
+### 2. 環境変数の明示
+
+```bash
+# ✅ 良い例: 必要な環境変数を明示
+NODE_ENV=test ./dist/cli.js test-command
+
+# ❌ 悪い例: 環境変数が暗黙的
+./dist/cli.js test-command
+```
+
+### 3. 前提条件の記載
+
+```bash
+# ✅ 良い例: セットアップ手順を含める
+# 前提: ビルド済みであること
+npm run build
+
+# テスト実行
+./dist/cli.js command
+
+# ❌ 悪い例: 前提条件が不明
+./dist/cli.js command
+```
+
+### 4. 期待結果の明記
+
+```bash
+# ✅ 良い例: 期待する出力を明記
+# 期待する結果:
+# - 終了コード: 0
+# - 標準出力に "Success" を含む
+# - ファイル dist/output.json が生成される
+
+# ❌ 悪い例: 期待結果が不明
+./dist/cli.js command
+```
+
+### 5. エラーケースの検証
+
+```bash
+# ✅ 良い例: エラーケースも記載
+# エラーケース: 無効な引数
+./dist/cli.js command --invalid-option ; echo "exit code: $?"
+# 期待: 終了コード 1、エラーメッセージ出力
+
+# ❌ 悪い例: 正常系のみ
+./dist/cli.js command
+```
+
+## E2E テストドキュメントへの反映
+
+`todo_plans/${ISSUE_NUMBER}/e2e-cmd.md` に記載した内容は、実装完了後に `docs-ai/e2e-test/` ディレクトリ配下の適切なファイルに反映します。
+
+### 反映先の決定
+
+- **既存機能の拡張**: 既存の E2E テストファイルに追記
+- **新機能**: 新しい E2E テストファイルを作成（命名規則: `[機能名]-e2e.md`）
+- **大規模な変更**: 既存ファイルを分割または再構成
+
+### 反映時の注意点
+
+1. **ファイルパスはプロジェクトルートからのフルパス**で記載
+2. **コマンドはコピペで実行可能**な形式で記載
+3. **セクション構成**は既存ファイルに合わせる：
+   - 前提条件
+   - 全体ビルド・テスト
+   - パッケージ別テスト
+   - コマンドライン検証
+   - エラーケーステスト
+   - クリーンアップ
+
+## チェックリスト
+
+e2e-cmd.md を作成する際の確認事項：
+
+- [ ] すべてのテストがコマンドライン上で完結する
+- [ ] ファイルパスはプロジェクトルートからのフルパスで記載されている
+- [ ] コマンドがコピペで実行可能である
+- [ ] 期待結果（終了コード、出力内容など）が明記されている
+- [ ] セットアップ手順が含まれている
+- [ ] クリーンアップ手順が必要な場合は記載されている
+- [ ] 既存の E2E テストファイルとの関連が明確である
+
+## 関連ドキュメント
+
+- **E2E テストガイドライン**: artifact/instructions/rules/test/e2e-cli-execution.md
+- **E2E テストディレクトリ**: docs-ai/e2e-test/README.md
+- **計画ワークフロー**: artifact/prompts/development/plan-fix.prompt.md
+
+## 例
+
+### 完全な e2e-cmd.md の例
+
+```markdown
+# E2E テスト計画: presets コマンド拡張
+
+## 追加すべきテスト
+
+### テスト1: JSON 形式での出力
+
+- **目的**: presets コマンドが JSON 形式で出力できることを確認
+- **対象ファイル**: packages/cli/dist/cli.js
+- **コマンド**:
+  ```bash
+  cd /home/runner/work/ai-rules/ai-rules
+  npm run build
+  ./dist/cli.js presets --format json
+  ```
+- **検証ポイント**:
+  - [ ] 終了コード 0
+  - [ ] 標準出力が有効な JSON である
+  - [ ] JSON に "presets" 配列が含まれる
+
+### テスト2: サブディレクトリのプリセット検出
+
+- **目的**: presets/ 配下のサブディレクトリ内のプリセットも検出できることを確認
+- **対象ファイル**: packages/cli/dist/cli.js
+- **コマンド**:
+  ```bash
+  cd /home/runner/work/ai-rules/ai-rules
+  npm run build
+  
+  # サブディレクトリを作成してテスト
+  mkdir -p presets/custom
+  echo "test: true" > presets/custom/test.yaml
+  
+  ./dist/cli.js presets
+  
+  # クリーンアップ
+  rm -rf presets/custom
+  ```
+- **検証ポイント**:
+  - [ ] 終了コード 0
+  - [ ] "custom/test.yaml" がリストに含まれる
+
+## 更新すべきテスト
+
+### テスト3: 既存の presets 一覧表示テスト
+
+- **現在の問題**: 新しい `--format` オプションが追加されたが、既存テストでカバーされていない
+- **対象ファイル**: docs-ai/e2e-test/presets-command-e2e.md
+- **変更内容**:
+  - セクション「基本的な presets 一覧表示」の後に、「JSON 形式での出力」セクションを追加
+- **理由**: 新機能のテストを既存の E2E テストファイルに統合
+
+## 削除すべきテスト
+
+なし
+```

package/artifact/prompts/development/apply-fix.prompt.md

@@ -0,0 +1,254 @@
+---
+type: prompt
+name: apply-fix
+category: workflow
+focus: implementation-application
+description: "計画済みの修正をrepoルールに沿って適用。skel先行更新、構造検証、テスト運用、docs更新、PR/Issueコメントで進捗共有を標準化。"
+agent: agent
+---
+# prompt apply-fix ワークフロー
+
+## 概要
+
+計画（Issue/planブランチ/Draft PR）と、実装完了後の締め作業（e2e実行/PR本文追記/Checks登録）の間にある「実装中」の作業を、この prompt で標準化します。
+
+この prompt の主目的は、計画済みの修正を repo 固有ルール（skel先行更新・構造検証・テスト制約・docs更新・change_plans運用）を破らずに適用し、実装完了後の締め作業を実行できる状態まで到達することです。
+
+## 目的
+
+- 実装の適用（コード/テスト）を安全な順序で進める
+- `skel/` を先行更新し、`test/skeleton-structure-validation.test.ts` で構造一致を担保する
+- テスト運用ルール（特に `it.each` 禁止）を順守する
+- `docs/` と必要に応じて `docs-ai/e2e-test/` を更新する
+- Git 連携できる場合、PR と Issue に進捗・判断・結果を「頻繁に」コメントして追跡可能性を上げる
+- 冗長コードを見つけたら `@TODO` を付け、後日リファクタリング候補として明示する（ただしスコープ外の大改修はしない）
+
+## 前提条件
+
+- 計画が完了している（Issue/planブランチ/Draft PR が存在）
+- 作業ブランチは `plan/{issue_number}` を base にした `agent/*` である
+- プロジェクトのテスト/ビルド/静的解析（該当する場合）が実行可能
+- GitHub 連携（`gh` 認証）は任意だが、可能ならコメント運用を行う
+
+## この prompt がやること / やらないこと
+
+### やること
+
+- 計画に従った実装（コード・テスト）の適用
+- `skel/` の先行更新と構造検証
+- docs 更新（必要に応じて `docs-ai/e2e-test/` の手順整備まで）
+- 進捗ログ（`change_plans/`）の更新
+- PR/Issue への進捗コメント（可能な場合）
+
+### やらないこと
+
+- Issue 作成・plan ブランチ作成・plan PR 作成（計画段階の領域）
+- 実装完了後の e2e 実行、PR本文の実装完了レポート追記、Checks 登録（実装完了後の締め作業の領域）
+
+## ワークフロー
+
+### Step 1: 現状確認（ブランチ/PR/差分）
+
+```bash
+# 現在のブランチ
+git branch --show-current
+
+# PR番号（存在する場合）
+PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null || true)
+echo "PR Number: ${PR_NUMBER}"
+
+# 変更ファイル一覧
+git --no-pager diff --name-only origin/main...HEAD
+```
+
+**確認ポイント**:
+- [ ] `agent/*` ブランチで作業している
+- [ ] 変更ファイル一覧が意図どおり
+
+### Step 2: 実装開始ログ（change_plans）を用意
+
+この repo では、作業中の計画・進捗は `change_plans/` に置き、完了後は削除します（Git履歴で追跡可能）。
+
+ただし計画段階の運用では `todo_plans/${ISSUE_NUMBER}/index.md` が Issue 本文の正本です。
+本タスクの進捗ログは `change_plans/` に作り、`todo_plans/${ISSUE_NUMBER}/index.md` は「要点の正本」として維持します。
+
+```bash
+DATE=$(date +%Y%m%d)
+ISSUE_NUMBER=$(gh issue view --json number -q '.number' 2>/dev/null || true)
+
+# gh が使えない場合は ISSUE_NUMBER を手で埋める
+# ISSUE_NUMBER=123
+
+CHANGE_PLAN="change_plans/${DATE}_issue-${ISSUE_NUMBER}_apply-fix.md"
+
+if [ ! -f "$CHANGE_PLAN" ]; then
+	cat > "$CHANGE_PLAN" <<'EOF'
+# apply-fix 実装ログ
+
+## 進捗
+- [ ] skel更新
+- [ ] 構造検証
+- [ ] 実装
+- [ ] テスト
+- [ ] docs更新
+
+## 判断・メモ
+
+## skel差分（patch）
+
+EOF
+fi
+
+echo "$CHANGE_PLAN"
+```
+
+### Step 2.1: 詳細ログ（検証結果/調査/判断根拠）を `todo_plans/${ISSUE_NUMBER}/` に残す
+
+- PR/Issue のコメントは「最初に自然文で3行」を必須にする（読む負担を増やさない）。
+- その後の追記は状況に応じてよいが、**原則7行以内**に抑える。
+- コマンド出力や長い実行ログは PR/Issue に貼らず、`todo_plans/${ISSUE_NUMBER}/` 配下にファイルとして残し、コメントから参照する。
+- 実装中に調べた内容や、実装手法の選択根拠（なぜその方針にしたか）も、同様に `todo_plans/${ISSUE_NUMBER}/` 配下に残す。
+
+**推奨ファイル（例）**:
+- `todo_plans/${ISSUE_NUMBER}/verification.md`: 実行した確認内容・結果（長くてよい）
+- `todo_plans/${ISSUE_NUMBER}/research.md`: 調査メモ・選択根拠（長くてよい）
+
+### Step 3: skel を先に更新（ロジック修正前）
+
+- ロジックの修正・テストの修正に入る前に、`skel/` を更新して「構造設計図」を先に確定します。
+- `skel/` の変更差分は patch 形式で取得し、Step 2 の `change_plans/*` に貼り付けます。
+
+```bash
+# 例: skel差分（patch）を確認して change_plans に貼る
+git --no-pager diff -- skel | cat
+```
+
+### Step 4: 構造検証テストだけ先に実行
+
+この repo では、まず `test/skeleton-structure-validation.test.ts` **だけ**を実行して、構造が一致していることを確認します。
+
+```bash
+# プロジェクトのテストランナーで「構造検証テスト」だけを実行
+<test-command> <structure-validation-test-only>
+```
+
+**参考（このリポジトリの例）**:
+
+```bash
+npm test -- skeleton-structure-validation.test.ts --run
+```
+
+**確認ポイント**:
+- [ ] skel/test と test の describe/it 構造が一致している
+- [ ] skel/src と src の構造が一致している
+
+### Step 5: テスト方針（TDD / 禁止事項 / 停止条件）
+
+- 修正対象が特定できたら、まずテストを書く（TDD）。
+- **`it.each` は使用禁止**（skel構造検証ができなくなる）。
+- テストが失敗した場合は、原因と修正方針をまとめ、合意が取れるまで先に進まない。
+
+### Step 6: 実装を適用（最小変更・根本原因）
+
+- できるだけ最小の差分で、根本原因に対処する。
+- 既存のAPI/CLI互換性を意識し、破壊的変更がある場合は計画と Issue/PR に明記する。
+- 実装中に冗長なコードを見つけた場合は、今回のスコープ外であれば削らずに `@TODO` を付けて後日対応に回す。
+
+### Step 7: docs 更新（docs/ と docs-ai/e2e-test/）
+
+- 変更内容が利用者に影響する場合は `docs/` を更新する。
+- 動作確認の再現手順が必要な場合は `docs-ai/e2e-test/` を追加/更新する。
+	- ここでは「手順整備」まで（実行と結果記録は実装完了後の締め作業で行う）。
+	- ここでは「手順整備」まで（実行と結果記録は実装完了後の締め作業で行う）。
+
+### Step 8: 最小のローカル検証
+
+```bash
+# 構造検証（再確認）
+<test-command> <structure-validation-test-only>
+
+# 可能なら、影響範囲のテストも実行
+<test-command>
+
+# 変更がビルド成果物に影響する場合
+<build-command>
+```
+
+**参考（このリポジトリの例）**:
+
+```bash
+npm test -- skeleton-structure-validation.test.ts --run
+npm test
+npm run root:build
+```
+
+### Step 9: コミット / PR・Issue コメント（頻繁に）
+
+- コミットはレビュー可能な粒度で積む（例: `skel` → `test` → `impl` → `docs`）。
+- GitHub 連携できる場合、以下のタイミングで PR と Issue にコメントする：
+	- 重要な判断変更（仕様・方針・スコープ）
+	- テスト戦略確定、テスト結果
+	- ブロッカー発生と解消
+	- マイルストーン（skel完了/実装完了/docs完了）
+
+#### コメントの定型（先頭3行は自然文）
+
+コメントは「最初に自然文で3行」を必須にし、その後の追記は状況に応じて行います（原則7行以内）。
+
+長いコマンドや出力を載せたい場合は、**自然文サマリのみ**をコメントに書き、実行ログや詳細は `todo_plans/${ISSUE_NUMBER}/` 配下に保存して参照します。
+
+（例：5行）
+
+1行目: 今回の変更で「何を」したかを書きます。
+2行目: 現在の進捗と、次にやることを書きます。
+3行目: 影響範囲・注意点（なければ「影響なし」）を書きます。
+補足: 検証は○○を実施しました。
+詳細: todo_plans/${ISSUE_NUMBER}/verification.md / todo_plans/${ISSUE_NUMBER}/research.md
+
+```bash
+# 進捗コメント（PR）
+if [ -n "$PR_NUMBER" ]; then
+	gh pr comment "$PR_NUMBER" --body "進捗: [skel/実装/テスト/docs] の状況を更新しました。次は [次の作業] に進みます。"
+fi
+
+# 進捗コメント（Issue）
+if [ -n "$ISSUE_NUMBER" ]; then
+	gh issue comment "$ISSUE_NUMBER" --body "進捗: [skel/実装/テスト/docs]。変更点/判断: ..."
+fi
+```
+
+### Step 10: 完了条件（実装完了後の締め作業に引き渡せる状態）
+
+- [ ] 変更がコミット済み（作業ブランチに反映されている）
+- [ ] `npm test -- skeleton-structure-validation.test.ts --run` が通る
+- [ ] 必要な `docs/` 更新が完了している
+- [ ] 必要な `docs-ai/e2e-test/` が存在する（影響がある場合）
+- [ ] `change_plans/*` に進捗と skel差分patch が残っている（完了後の削除は、merge/完了確認後に実施）
+- [ ] 必要に応じて `todo_plans/${ISSUE_NUMBER}/verification.md` と `todo_plans/${ISSUE_NUMBER}/research.md` が更新されている
+
+## コマンド一覧（まとめ）
+
+```bash
+# 1) 現状確認
+git branch --show-current
+git --no-pager diff --name-only origin/main...HEAD
+
+# 2) skel → 構造検証
+<test-command> <structure-validation-test-only>
+
+# 3) テスト/実装/ドキュメント
+<test-command>
+<build-command>
+
+# 4) PR/Issue コメント
+gh pr comment <PR_NUMBER> --body "..."
+gh issue comment <ISSUE_NUMBER> --body "..."
+```
+
+**参考（このリポジトリの例）**:
+
+```bash
+npm test -- skeleton-structure-validation.test.ts --run
+npm test
+npm run root:build
+```