@aramassa/ai-rules 0.5.3 → 0.6.1

package/artifact/instructions/rules/development/planning-workflow.md

@@ -0,0 +1,792 @@
+---
+type: development
+category: workflow
+focus: planning-and-issue-management
+language: agnostic
+applyTo: "**/*"
+human-instruction: |-
+  ## プランニングワークフローの人間による理解が重要です
+
+  このルールは、新機能の計画立案からIssue起票、ブランチ作成までの標準的なワークフローを定義しています。
+  AIはプロセスに従うことができますが、以下の点で人間の判断が重要です：
+
+  - **要件の本質理解**: 機能の背景や目的の深い理解
+  - **適切な粒度判断**: タスクを適切なサイズに分割する判断
+  - **優先度の決定**: 複数の計画の優先順位付け
+  - **リスク評価**: 技術的・ビジネス的リスクの適切な評価
+  - **コンフリクト解決方針**: 複雑なマージコンフリクトの解決戦略
+
+  このワークフローは、一貫性のある計画書作成とプロジェクト管理を可能にするためのガイドラインです。
+---
+
+# プランニングワークフロー マニュアル
+
+## 概要
+
+新機能の計画立案からIssue起票、ブランチ作成までの標準的なワークフローを定義します。このフローに従うことで、一貫性のある計画書作成とプロジェクト管理が可能になります。
+
+## 目次
+
+- [基本フロー](#基本フロー)
+- [Step 1: 要件の明確化](#step-1-要件の明確化)
+- [Step 2: 計画書の作成](#step-2-計画書の作成)
+- [Step 3: Issue の起票](#step-3-issue-の起票)
+- [Step 4: ブランチの作成とコミット](#step-4-ブランチの作成とコミット)
+- [計画書テンプレート](#計画書テンプレート)
+- [ベストプラクティス](#ベストプラクティス)
+
+---
+
+## 基本フロー
+
+```mermaid
+graph TD
+    A[要件の明確化] --> B[計画書作成]
+    B --> C[Issue起票]
+    C --> D[親Issueとの紐付け]
+    D --> E[ブランチ作成]
+    E --> F[計画書コミット & プッシュ]
+    F --> G[実装開始]
+```
+
+---
+
+## Step 1: 要件の明確化
+
+### 目的
+
+実装する機能の背景、課題、解決策を明確にします。
+
+### 確認事項
+
+#### 1. 背景の整理
+
+**質問リスト**:
+- なぜこの機能が必要なのか？
+- 現状のどのような課題を解決するのか？
+- この機能がないと何が困るのか？
+
+**例** (mastra-tool-mcp-docs CLI機能の場合):
+```markdown
+### 現状の課題
+- Tool の動作確認に必ず mastra-integration で Agent/Workflow を経由する必要がある
+- 問題発生時に、Toolの問題かAgent/Workflowの問題か切り分けが難しい
+- 開発効率の低下
+```
+
+#### 2. 解決策の定義
+
+**質問リスト**:
+- どのようなアプローチで課題を解決するか？
+- 実現可能性は？
+- 既存システムへの影響は？
+
+**例**:
+```markdown
+### 解決策
+CLI インターフェースを追加することで、以下を実現:
+1. スタンドアロン実行
+2. 簡単なデバッグ
+3. 実行例の提供
+4. 開発体験の向上
+```
+
+#### 3. スコープの決定
+
+**確認項目**:
+- [ ] 必須機能（Must Have）の特定
+- [ ] 拡張機能（Should Have）の特定
+- [ ] 将来的な拡張案（Nice to Have）の記録
+
+---
+
+## Step 2: 計画書の作成
+
+### ファイル配置
+
+```
+todo_plans/
+└── YYYYMMDD_[機能名].md
+```
+
+**命名規則**: `YYYYMMDD_[kebab-case-title].md`
+
+**例**: `20251004_mastra_tool_mcp_docs_cli.md`
+
+### 計画書の構成
+
+計画書は以下のセクションで構成します：
+
+#### 必須セクション
+
+1. **背景**
+   - 現状の課題
+   - 解決策
+
+2. **やること**
+   - Phase 1: 必須機能
+   - Phase 2: 拡張機能
+   - Phase 3: ドキュメント・サンプル
+   - Phase 4: テスト・検証
+
+3. **要件分析**
+   - ユーザーストーリー
+   - 技術的制約
+
+4. **アーキテクチャ設計**
+   - システム影響範囲
+   - データフロー設計
+   - インターフェース設計
+
+5. **実装計画**
+   - 改修対象ファイル一覧
+   - ファイルごと改修内容
+   - 実装順序
+
+6. **実装後の挙動**
+   - 使用例
+   - エラーケース
+   - 開発ワークフロー
+
+7. **品質保証**
+   - テスト戦略
+   - 動作確認項目
+   - パフォーマンス考慮事項
+
+8. **リスク評価と対策**
+   - 技術リスク
+   - 運用リスク
+
+#### オプションセクション
+
+9. **更新ポリシー**
+   - 更新トリガー
+   - レビュー責任者
+   - チェックリスト
+
+10. **関連ドキュメント**
+    - 参照する計画書
+    - 関連パッケージ
+    - 参考資料
+
+11. **メモ**
+    - 設計の参考情報
+    - 将来的な拡張案
+    - 既知の制限事項
+
+### 計画書作成のポイント
+
+#### ✅ 良い計画書
+
+- **具体的**: 実装イメージが明確
+- **測定可能**: 完了条件が明確
+- **実現可能**: 技術的制約を考慮
+- **段階的**: Phase分けされている
+- **テスト可能**: 検証方法が明確
+
+#### ❌ 避けるべき計画書
+
+- 抽象的で実装イメージが湧かない
+- 完了条件が曖昧
+- 技術的制約を無視
+- 一括実装を前提
+- テスト方法が不明確
+
+---
+
+## Step 3: Issue の起票
+
+### Issue作成
+
+#### 必須項目
+
+1. **タイトル**
+   - 形式: `[パッケージ名]: [機能概要]`
+   - 例: `mastra-tool-mcp-docs: CLI機能の追加`
+
+2. **本文構成**
+   ```markdown
+   ## 概要
+   [機能の概要を1-2文で]
+   
+   ## 背景
+   ### 現状の課題
+   - [課題1]
+   - [課題2]
+   
+   ### 解決策
+   [解決アプローチ]
+   
+   ## 実装内容
+   ### Phase 1: [フェーズ名]
+   - [ ] タスク1
+   - [ ] タスク2
+   
+   ### Phase 2: [フェーズ名]
+   ...
+   
+   ## 使用例（実装後）
+   ```bash
+   # 使用例のコード
+   ```
+   
+   ## 技術的ポイント
+   - ポイント1
+   - ポイント2
+   
+   ## 受け入れ基準
+   - [ ] 基準1
+   - [ ] 基準2
+   
+   ## 関連ドキュメント
+   - 詳細計画: `todo_plans/YYYYMMDD_xxx.md`
+   
+   ## 優先度
+   [High/Medium/Low]
+   
+   ## 見積もり
+   - Phase 1-2: X-Y時間
+   - Phase 3: X-Y時間
+   合計: X-Y時間
+   ```
+
+3. **ラベル**
+   - 機能種別: `enhancement`, `bug`, `documentation`
+   - カテゴリ: `mastra-tool`, `language-detection` など
+
+#### GitHub CLI での作成例
+
+```bash
+gh issue create \
+  --title "mastra-tool-mcp-docs: CLI機能の追加" \
+  --body-file todo_plans/20251004_mastra_tool_mcp_docs_cli.md \
+  --label "enhancement,mastra-tool"
+```
+
+### 親Issueとの紐付け
+
+既存の親Issueのサブタスクとして追加する場合：
+
+#### 方法1: Issue本文に記載
+
+```markdown
+## 関連Issue
+
+親Issue: Aramassa/ai-rules#6
+```
+
+#### 方法2: GitHub Projects で管理
+
+GitHub Projects を使用している場合、プロジェクトボードで階層構造を設定。
+
+---
+
+## Step 4: ブランチの作成とコミット
+
+### ブランチ命名規則
+
+```
+plan/[親Issue番号].[サブIssue番号]
+```
+
+**例**:
+- 親Issue Aramassa/ai-rules#6 のサブIssue Aramassa/ai-rules#9 の場合: `plan/6.9`
+
+### ブランチ作成とコミット
+
+#### コマンドライン
+
+```bash
+# 1. 現在のブランチを確認
+git branch --show-current
+
+# 2. 新しいブランチを作成して切り替え
+git checkout -b plan/6.9
+
+# 3. 計画書をステージング
+git add todo_plans/20251004_mastra_tool_mcp_docs_cli.md
+
+# 4. コミット
+git commit -m "Add CLI feature implementation plan for mastra-tool-mcp-docs
+
+- CLI interface for standalone testing
+- Command-line argument parsing with commander
+- Config file support (JSON format)
+- Dry-run, verbose, output options
+- Sample configurations for all resource types
+- Related to Issue Aramassa/ai-rules#9, sub-issue of Aramassa/ai-rules#6"
+
+# 5. リモートにプッシュ
+git push -u origin plan/6.9
+```
+
+#### VS Code ソースコントロール
+
+1. **新しいブランチを作成**
+   - 左下のブランチ名をクリック
+   - "Create new branch..." を選択
+   - ブランチ名を入力: `plan/6.9`
+
+2. **変更をステージング**
+   - ソースコントロールパネルで変更ファイルの横の `+` をクリック
+
+3. **コミット**
+   - コミットメッセージを入力
+   - "Commit" ボタンをクリック
+
+4. **プッシュ**
+   - "Sync Changes" または "Publish Branch" ボタンをクリック
+
+### コミットメッセージの書き方
+
+#### 形式
+
+```
+[動詞] [対象] for [パッケージ/機能名]
+
+- [詳細1]
+- [詳細2]
+- [詳細3]
+- Related to Issue #X, sub-issue of #Y
+```
+
+#### 良い例
+
+```
+Add CLI feature implementation plan for mastra-tool-mcp-docs
+
+- CLI interface for standalone testing
+- Command-line argument parsing with commander
+- Config file support (JSON format)
+- Dry-run, verbose, output options
+- Sample configurations for all resource types
+- Related to Issue Aramassa/ai-rules#9, sub-issue of Aramassa/ai-rules#6
+```
+
+#### 避けるべき例
+
+```
+Update plan
+```
+（何を更新したか不明確）
+
+---
+
+## 計画書テンプレート
+
+### 基本テンプレート
+
+```markdown
+# [機能名] 実装計画
+
+## 背景
+
+### 現状の課題
+
+[現在の問題点を箇条書きで記載]
+
+### 解決策
+
+[提案する解決アプローチ]
+
+## やること
+
+### Phase 1: [フェーズ名]（必須機能）
+- [ ] タスク1
+- [ ] タスク2
+
+### Phase 2: [フェーズ名]（拡張機能）
+- [ ] タスク1
+- [ ] タスク2
+
+### Phase 3: [フェーズ名]（ドキュメント）
+- [ ] タスク1
+- [ ] タスク2
+
+### Phase 4: [フェーズ名]（テスト）
+- [ ] タスク1
+- [ ] タスク2
+
+## 要件分析
+
+### ユーザーストーリー
+
+**US-1: [ストーリータイトル]**
+```
+AS A [ユーザー種別]
+I WANT TO [やりたいこと]
+SO THAT [目的]
+```
+
+**受け入れ基準**:
+- [ ] 基準1
+- [ ] 基準2
+
+### 技術的制約
+
+#### TC-1: [制約名]
+[制約内容の説明]
+
+## アーキテクチャ設計
+
+### システム影響範囲
+
+#### 影響を受けるファイル
+- ✅ **変更**: ファイル名（変更内容）
+- ✅ **新規**: ファイル名（用途）
+
+#### 影響を受けないファイル
+- 既存ファイル1
+- 既存ファイル2
+
+### データフロー設計
+
+```mermaid
+graph LR
+    A[開始] --> B[処理1]
+    B --> C[処理2]
+    C --> D[終了]
+```
+
+### インターフェース設計
+
+```typescript
+interface FeatureConfig {
+  // 型定義
+}
+```
+
+## 実装計画
+
+### 改修対象ファイル一覧
+
+```
+packages/[パッケージ名]/
+├── ファイル1          # 変更内容
+├── ファイル2          # 変更内容
+└── ファイル3          # 変更内容
+```
+
+### ファイルごと改修内容
+
+#### 1. ファイル名
+
+**変更内容**:
+```typescript
+// コード例
+```
+
+**理由**:
+[変更の理由]
+
+### 実装順序
+
+#### Step 1: [ステップ名]
+1. タスク1
+2. タスク2
+
+#### Step 2: [ステップ名]
+...
+
+## 実装後の挙動に関する説明
+
+### 基本的な使用例
+
+```bash
+# 使用例
+```
+
+### エラーケース
+
+```bash
+# エラー例
+```
+
+## 品質保証
+
+### テスト戦略
+
+#### Unit Tests
+[単体テストの方針]
+
+#### Integration Tests
+[統合テストの方針]
+
+### 動作確認項目
+
+#### 必須確認項目
+- [ ] 確認項目1
+- [ ] 確認項目2
+
+## リスク評価と対策
+
+### 技術リスク
+
+#### R-1: [リスク名]
+
+**リスク**: [リスクの説明]
+
+**対策**:
+[対策の説明]
+
+**影響度**: 高/中/低
+
+## 関連ドキュメント
+
+- [関連する計画書やドキュメント]
+
+## メモ
+
+### 設計の参考
+
+[参考にした情報源]
+
+### 将来的な拡張案
+
+- [ ] 拡張案1
+- [ ] 拡張案2
+
+---
+
+**作成日**: YYYY年MM月DD日
+**ステータス**: 計画中/実装中/完了
+```
+
+---
+
+## ベストプラクティス
+
+### 計画立案時
+
+#### 1. Small Batch原則
+
+大きな機能は Phase に分割して段階的に実装します。
+
+**良い例**:
+```
+Phase 1: 基本機能（2-3時間）
+Phase 2: 拡張機能（2-3時間）
+Phase 3: ドキュメント（1-2時間）
+Phase 4: テスト（1-2時間）
+```
+
+**避けるべき例**:
+```
+Phase 1: 全機能実装（10時間）
+```
+
+#### 2. 受け入れ基準の明確化
+
+各機能に対して検証可能な受け入れ基準を定義します。
+
+**良い例**:
+```
+- [ ] `--config` オプションで設定ファイルを指定できる
+- [ ] 実行結果が標準出力に表示される
+- [ ] エラー時に終了コード 1 が返る
+```
+
+**避けるべき例**:
+```
+- [ ] 正しく動作する
+```
+
+#### 3. 技術的制約の事前確認
+
+実装前に技術的な制約や依存関係を明確にします。
+
+```markdown
+### 技術的制約
+
+#### TC-1: npm バイナリ公開の仕組み
+- `package.json` の `bin` フィールドで実行ファイルを指定
+- shebang (`#!/usr/bin/env node`) が必要
+```
+
+### Issue管理時
+
+#### 1. 親子関係の明示
+
+関連するIssueは階層構造で管理します。
+
+```
+Issue Aramassa/ai-rules#6 (親): パッケージ全体の実装
+  └── Issue Aramassa/ai-rules#9 (子): CLI機能の追加
+```
+
+#### 2. ラベルの活用
+
+機能種別とカテゴリでラベルを付与します。
+
+```
+ラベル: enhancement, mastra-tool
+```
+
+#### 3. 見積もりの記載
+
+実装時間の見積もりを記載して、スケジュール管理に役立てます。
+
+```markdown
+## 見積もり
+
+- Phase 1-2: 4-6時間（基本実装とオプション）
+- Phase 3: 2-3時間（サンプルとドキュメント）
+- Phase 4: 1-2時間（テストと検証）
+
+合計: 7-11時間
+```
+
+### ブランチ管理時
+
+#### 1. 命名規則の統一
+
+```
+plan/[親Issue番号].[サブIssue番号]
+feat/[Issue番号]-[機能名]
+fix/[Issue番号]-[修正内容]
+```
+
+#### 2. 計画書のみをコミット
+
+実装開始前は計画書のみをコミットします。
+
+```bash
+# 良い例
+git add todo_plans/20251004_xxx.md
+git commit -m "Add implementation plan for xxx"
+
+# 避けるべき例（計画と実装を混在させない）
+git add todo_plans/ src/ test/
+git commit -m "Add plan and implementation"
+```
+
+#### 3. 詳細なコミットメッセージ
+
+何を追加/変更したか、なぜ変更したかを明確に記載します。
+
+```
+Add CLI feature implementation plan for mastra-tool-mcp-docs
+
+- CLI interface for standalone testing
+- Command-line argument parsing with commander
+- Config file support (JSON format)
+- Dry-run, verbose, output options
+- Sample configurations for all resource types
+- Related to Issue Aramassa/ai-rules#9, sub-issue of Aramassa/ai-rules#6
+```
+
+---
+
+## チェックリスト
+
+### 計画書作成完了時
+
+- [ ] 背景と課題が明確に記載されている
+- [ ] 解決策が具体的である
+- [ ] Phase分けされている（最大4-5 Phase）
+- [ ] ユーザーストーリーと受け入れ基準が記載されている
+- [ ] 技術的制約が考慮されている
+- [ ] システム影響範囲が特定されている
+- [ ] 実装順序が明確である
+- [ ] テスト戦略が記載されている
+- [ ] リスクと対策が記載されている
+
+### Issue起票完了時
+
+- [ ] タイトルが明確である
+- [ ] 概要が1-2文で説明されている
+- [ ] 実装内容がPhase分けされている
+- [ ] 受け入れ基準が記載されている
+- [ ] 見積もりが記載されている
+- [ ] 適切なラベルが付与されている
+- [ ] 親Issueと紐付けられている（該当する場合）
+- [ ] 詳細計画へのリンクが記載されている
+
+### ブランチ作成・コミット完了時
+
+- [ ] ブランチ名が命名規則に従っている
+- [ ] 計画書のみがステージングされている
+- [ ] コミットメッセージが詳細である
+- [ ] Issue番号が記載されている
+- [ ] リモートにプッシュされている
+
+---
+
+## よくある質問
+
+### Q1: 計画書はどのくらい詳細に書くべきですか？
+
+**A**: 実装者が迷わず作業を開始できるレベルの詳細度が適切です。以下を目安にしてください：
+
+- ✅ ファイルごとの変更内容が明確
+- ✅ 実装順序が論理的
+- ✅ 受け入れ基準が検証可能
+- ✅ 技術的制約が考慮されている
+
+### Q2: Phase はいくつに分けるべきですか？
+
+**A**: 通常は3-5 Phase が適切です：
+
+1. **Phase 1**: 必須機能（最小限の動作確認が可能）
+2. **Phase 2**: 拡張機能（利便性向上）
+3. **Phase 3**: ドキュメント・サンプル
+4. **Phase 4**: テスト・検証
+5. **Phase 5**: 統合・本番投入準備（必要に応じて）
+
+### Q3: 実装中に計画を変更する場合は？
+
+**A**: 計画書を更新してコミットします：
+
+```bash
+git add todo_plans/20251004_xxx.md
+git commit -m "Update implementation plan: Add error handling strategy
+
+- Add detailed error handling for CLI execution
+- Update risk assessment section
+- Related to Issue Aramassa/ai-rules#9"
+```
+
+### Q4: 小さな変更でも計画書は必要ですか？
+
+**A**: 以下の場合は簡易的な計画で構いません：
+
+- バグ修正（影響範囲が限定的）
+- ドキュメント修正のみ
+- 軽微なリファクタリング
+
+ただし、以下の場合は詳細な計画が推奨されます：
+
+- 新機能追加
+- 既存機能の大幅な変更
+- 複数ファイルにまたがる変更
+- アーキテクチャ変更
+
+### Q5: 親Issueとサブ Issueの使い分けは？
+
+**A**: 以下の基準で判断します：
+
+**親Issue**:
+- パッケージ全体の実装
+- 大きな機能単位
+- 複数のサブタスクを含む
+
+**サブIssue**:
+- 親Issueの一部機能
+- 独立して実装可能
+- 1-2日で完了する規模
+
+---
+
+## まとめ
+
+このワークフローに従うことで：
+
+✅ **一貫性**: 誰が計画しても同じ品質
+✅ **追跡可能性**: Issueとブランチで進捗管理
+✅ **レビュー容易性**: 計画段階でフィードバック
+✅ **実装効率**: 迷わず実装に集中
+
+---
+
+**最終更新日**: 2025年10月4日
+**バージョン**: 1.0.0