@aramassa/ai-rules 0.5.2 → 0.6.0

package/artifact/instructions/git-rules.md

@@ -21,6 +21,22 @@ type: git-rules
 
 * `docs/` + ドキュメント名
 
+### Agent Coding ワークフロー専用ブランチ
+
+#### plan ブランチ
+* `plan/` + Issue番号
+* 例: `plan/123`, `plan/456`
+* 用途: GitHub Issue に基づく実装計画の管理
+* base branch として Agent タスクを起動する
+* 複数の agent ブランチをマージして結合テストを行う
+
+#### agent ブランチ
+* `agent/` + 説明的な名前
+* 例: `agent/login-feature-implementation`, `agent/add-validation-tests`
+* 用途: Agent Coding による自動実装
+* 必ず `plan/X` ブランチを base として作成する
+* PR レビュー後に `plan/X` にマージされる
+
 ## 使用可能文字
 
 * 英数字 (a-z, A-Z, 0-9)
@@ -36,6 +52,69 @@ type: git-rules
 * 特殊文字 (例: !, @, #, $, %, ^, &, *,
 * マルチバイト文字 (例: 漢字、ひらがな、カタカナ)
 
+## Agent Coding のブランチ戦略
+
+### 基本フロー
+
+```
+main
+ └─ plan/123 (Issue #123 に基づく実装計画)
+     ├─ agent/login-feature-implementation → PR → plan/123 にマージ
+     ├─ agent/add-validation-tests → PR → plan/123 にマージ
+     └─ 結合テスト完了後 → PR → main にマージ
+```
+
+### ブランチの役割
+
+#### main ブランチ
+- プロダクション環境にデプロイされる安定版
+- 直接コミット禁止（PR 経由のみ）
+- 全テスト通過、全レビュー完了が必須
+
+#### plan/X ブランチ
+- 特定の Issue（#X）に関連する実装計画を管理
+- 複数の agent ブランチからの PR をマージして統合
+- 結合テストを実施する場
+- main へのマージ前の最終確認ポイント
+
+#### agent/xxxxx ブランチ
+- Agent Coding による自動実装用の一時ブランチ
+- 必ず plan/X ブランチから派生
+- PR レビュー後に plan/X にマージ
+- マージ後は速やかに削除
+
+### ブランチライフサイクル管理
+
+#### plan/X ブランチの管理
+- **作成タイミング**: Issue 起票直後、計画マークダウンをコミットする際
+- **寿命**: 1〜3日を目安（長期化を避ける）
+- **マージ基準**: 
+  - 全 agent ブランチのマージ完了
+  - 結合テストの成功
+  - コードレビューの承認
+- **削除タイミング**: main へのマージ完了後
+
+#### agent/xxxxx ブランチの管理
+- **作成タイミング**: Agent タスク起動時に自動作成
+- **寿命**: 数時間〜1日（タスク完了まで）
+- **マージ基準**:
+  - コードの品質確認
+  - テスト通過
+  - レビュー承認
+- **削除タイミング**: plan/X へのマージ完了直後
+
+### コンフリクト対応指針
+
+#### 予防策
+- plan/X ブランチは小さく分割し、寿命を短く保つ
+- 定期的に main の変更を plan/X に取り込む
+- 複数の plan/X が同じファイルを変更する場合、優先度を調整
+
+#### 発生時の対応
+- 単純なコンフリクト（空白、インポート順序）: AI による解決を許可
+- 複雑なロジックのコンフリクト: 人間による確認と解決
+- 重要ファイル（設定、セキュリティ）: 常に人間がレビュー
+
 ## コミット前必須チェックリスト
 
 ### 必須: ビルド確認

package/artifact/instructions/planning.md

@@ -189,6 +189,115 @@ focus: structured-process
 - **成果物**: Issue、Pull Request、レビュー記録
 - **品質基準**: ステークホルダーとの情報共有
 
+## GitHub Issue 中心の Agent Coding ワークフロー
+
+Agent Coding を活用する際は、GitHub Issue を中心としたブランチ戦略と計画管理を行います。
+
+### ワークフロー全体像
+
+```
+VS Code で計画立案 → Issue 起票 → plan/X ブランチ作成 → Agent タスク実行
+  → PR レビュー → plan/X へマージ → 結合テスト → main へマージ
+```
+
+### 詳細プロセス
+
+#### Phase 1: VS Code での計画立案
+- **実施内容**:
+  - VS Code 上で実装計画をマークダウンファイルに出力
+  - 計画には以下の内容を含める:
+    - 開発要件の整理
+    - 影響箇所の調査
+    - 修正ポイントの特定
+- **成果物**: 計画マークダウンファイル（例: `plans/YYYYMMDD_機能名.md`）
+- **品質基準**: 4段階プランニングプロセスに基づく完全性
+
+#### Phase 2: GitHub Issue 起票
+- **実施内容**:
+  - 上記で作成した計画マークダウンファイルへのパスを必ず含めて Issue を作成
+  - Issue には実装の目的、範囲、制約を明記
+- **成果物**: GitHub Issue（計画ファイルパスを含む）
+- **命名規則**: `[Type] 機能名` 形式（例: `[Feature] ログイン機能追加`）
+
+#### Phase 3: plan/X ブランチの作成とコミット
+- **実施内容**:
+  - Issue 番号を使って `plan/X` ブランチを作成（X は Issue 番号）
+  - 計画マークダウンファイルを `plan/X` ブランチにコミット・プッシュ
+- **ブランチ命名**: `plan/{issue-number}`（例: `plan/123`）
+- **注意点**: この段階では実装コードはコミットしない
+
+#### Phase 4: plan/X を base に Agent タスク起動
+- **実施内容**:
+  - `plan/X` ブランチを base branch として Agent Coding タスクを起動
+  - Agent は `agent/xxxxx` ブランチを自動作成して実装を進める
+- **ブランチ命名**: `agent/{descriptive-name}`（例: `agent/login-feature-implementation`）
+
+#### Phase 5: PR レビューとマージ
+- **実施内容**:
+  - Agent が作成した PR (`agent/xxxxx` → `plan/X`) を人間がレビュー
+  - レビュー観点:
+    - コードの品質と正確性
+    - テストカバレッジの充足
+    - セキュリティの考慮
+    - パフォーマンスへの影響
+  - OK であれば `plan/X` にマージする
+- **品質基準**: レビューチェックリスト完了
+
+#### Phase 6: plan/X での結合テスト
+- **実施内容**:
+  - `plan/X` ブランチ上で複数の Agent タスクの結果を統合
+  - 結合テストを実施して、全体の動作を確認
+  - 問題があれば追加の Agent タスクを起動して修正
+- **品質基準**: 全テスト通過、ビルド成功
+
+#### Phase 7: main へのマージ
+- **実施内容**:
+  - 結合テストが成功したら `plan/X` → `main` への PR を作成
+  - 最終レビューと承認を経て main にマージ
+  - Issue をクローズ
+- **完了条件**: CI/CD パイプライン成功、全レビュー完了
+
+### コンフリクト管理の考慮事項
+
+#### 長期ブランチのリスク
+- **課題**: `plan/X` の実装が長引くと、他の計画と修正箇所がコンフリクトする可能性
+- **対策**:
+  - 計画は可能な限り小さく分割し、`plan/X` の寿命を短く保つ
+  - 定期的に `main` ブランチの変更を `plan/X` に取り込む（リベースまたはマージ）
+  - 複数の `plan/X` ブランチが同じファイルを変更する場合、優先度を明確にする
+
+#### AI によるマージのリスク評価
+- **課題**: AI がコンフリクト解決を行う際の品質リスク
+- **原則**: AI による自動マージは慎重に扱う
+  - 単純なコンフリクト（空白、インポート順序など）: AI による解決を許可
+  - 複雑なロジックのコンフリクト: 人間による確認と解決を必須とする
+  - 重要なファイル（設定、セキュリティ関連）: 常に人間がレビュー
+
+#### コンフリクト発生時の対応フロー
+1. コンフリクト検出（PR 作成時または定期的なマージ試行時）
+2. コンフリクトの複雑度評価（自動 or 人間判断）
+3. 単純な場合: AI に解決を依頼
+4. 複雑な場合: 人間が解決方針を決定し、AI に指示
+5. 解決後の動作確認とテスト実行
+6. レビューと承認
+
+### ワークフロー運用のベストプラクティス
+
+#### 計画の粒度管理
+- 1つの `plan/X` は 1〜3 日で完了できる規模に抑える
+- 大きな機能は複数の Issue と `plan/X` に分割する
+- 依存関係がある場合は、Issue 間でリンクを明記する
+
+#### Agent タスクの管理
+- 1つの Agent タスクは 1つの明確な責務に限定する
+- Agent タスク間の依存関係は `plan/X` ブランチ上で順次実行
+- Agent の出力結果は必ず人間がレビューする
+
+#### ブランチの整理
+- マージ完了後は速やかにブランチを削除する
+- 放置された `plan/X` ブランチは定期的にレビューし、不要なら削除
+- ブランチ一覧を定期的に確認し、長期化しているものを特定する
+
 ### コミュニケーションのルール
 
 #### パスの指定について