moai-workflow-testing

開発ワークフローのスペシャリスト

クイックリファレンス

DDD（ドメイン駆動開発）のテスト、デバッグのガイダンス、パフォーマンス最適化、自動コードレビュー、CI/CD 品質ゲートを組み合わせた統合開発ワークフローです。特性テストを通じて、リファクタリング中の振る舞いの維持を重視します。

主な機能：

• DDD テスト：特性テスト（レガシー）＋仕様テスト（グリーンフィールド）＋振る舞いのスナップショット
• AI を活用したデバッグ：エラー分析、分類、解決策候補の提示
• パフォーマンス最適化：プロファイリング、ボトルネックの検出、最適化の推奨
• 自動コードレビュー：TRUST 5 フレームワークによる検証
• PR コードレビュー：マルチエージェントパターン（Haiku による適格性判定＋5 つの Sonnet 並列レビュアー）
• 品質保証：品質ゲートを備えた CI/CD 統合

ワークフローの進行順序：デバッグ → リファクタリング → 最適化 → レビュー → テスト → プロファイリング

使用する場面：

• 開発ライフサイクル全体の管理
• 品質保証と CI/CD 統合
• 多言語対応プロジェクトやパフォーマンスが重要なプロジェクト
• 技術的負債の削減
• PR コードレビューの自動化

---

実装ガイド

コアコンセプト

5 つの統合コンポーネントでワークフローを構成します。

• AI を活用したデバッグ：エラー分類（構文／実行時／ロジック／統合／パフォーマンス）と、可能性の高い順に並べた解決策候補
• スマートリファクタリング：複雑度メトリクスとリスク評価による技術的負債の分析
• パフォーマンス最適化：CPU／メモリ／IO／ネットワークのプロファイリングと最適化戦略
• DDD テスト管理：レガシー向けの特性テスト（PRESERVE フェーズ）＋グリーンフィールド向けの仕様テスト＋TRUST 5 検証
• 自動コードレビュー：実行可能な推奨事項を提示する TRUST 5 フレームワーク

TRUST 5 フレームワーク

5 つの側面から品質を評価するモデルです。

• テスト容易性：純粋関数、注入可能な依存関係、モジュール設計
• 可読性：説明的な名前、論理的な構成、複雑な箇所の文書化
• 理解しやすさ：明確なビジネスロジック、適切な抽象化、概念の明瞭さ
• セキュリティ：入力検証、シークレット管理、OWASP 準拠（インジェクション／XSS／CSRF）
• 透明性：包括的なエラー処理、構造化ログ、追跡可能な問題

総合スコア：重み付き平均を使用し、重要な側面には例外的な評価を適用します（セキュリティ／テスト容易性の低さは、ほかの側面のスコアで補えません）。

評価基準の全文は、TRUST 5 の各側面とスコアリングの詳細を参照してください。

DDD テストプロセス

レガシーコード（PRESERVE フェーズ）：

1. 現在の振る舞いを記録する特性テストを作成します（望ましい振る舞いではなく、現状を記録します）。
2. テストをドメインの概念ごとに整理し、ドメインの境界を明らかにします。
3. 複雑なシナリオの回帰防止策として、振る舞いのスナップショットを使用します。
4. ベースラインを確認します。変更を加える前に、すべての特性テストが PASS することを確認します。
5. テストを継続的に実行しながらリファクタリングを適用します。
6. リファクタリング後に TRUST 5 検証を実行します。

グリーンフィールド開発：

1. ドメイン要件から仕様テストを導き出します（各テストがビジネスルールに対応します）。
2. 集約、エンティティ、値オブジェクト（DDD のユビキタス言語）ごとにテストを整理します。
3. 実装の詳細ではなく、ビジネス用語で振る舞いを定義します。
4. 仕様を満たすように実装します。
5. 統合テスト（ドメイン間の相互作用＋不変条件）で検証します。
6. TRUST 5 検証を適用します。

デバッグ、リファクタリング、パフォーマンスのワークフロー

3 つのワークフローはいずれも、6 段階のパターンに従います：取得／分析 → 分類 → 候補の特定 → 適用 → 検証 → 文書化。

詳細なプロセステーブルについては、デバッグ／リファクタリング／パフォーマンスの手順別ガイドを参照してください。

コードレビュープロセス

1. コードベースをスキャンしてレビュー対象を特定します。
2. ファイルごとに TRUST 5 フレームワークを適用します。
3. 重大な問題を特定します。
4. ファイルごとのスコアと総合スコアを算出します。
5. 優先順位を付けた推奨事項を作成します。
6. 改善ロードマップを含む概要レポートを作成します。

PR コードレビュー（マルチエージェントパターン）

5 ステップのマルチエージェントパイプラインです。

1. 対象判定（Haiku）：クローズ済み／ドラフト／レビュー済み／軽微な PR をスキップします
2. コンテキスト収集：変更された各ディレクトリの AGENTS.md を検索し、PR を要約します
3. 並列レビュー（5 つの Sonnet エージェント）：AGENTS.md への準拠／明白なバグ／git blame／以前のコメント／コードコメントへの準拠
4. 確信度スコア（0〜100）：0＝誤検知、25＝やや確信、50＝ある程度確信、75＝高い確信、100＝確実
5. フィルタリングと報告：確信度が 80 未満の問題を除外し、ファイル／行／コミットへのリンクを含めて gh CLI で投稿します

エージェントの役割の詳細と出力例については、PR レビューのマルチエージェントアーキテクチャと出力形式を参照してください。

多言語サポート

言語ごとのツールチェーン対応（Python の pytest+ruff+bandit、JS/TS の Jest+ESLint+npm audit、Go の go test+staticcheck+gosec、Rust の cargo test+clippy+gosec 相当）。

言語ごとのテスト／lint／セキュリティ／パフォーマンスツールの一覧については、多言語ツールチェーンリファレンスを参照してください。

---

高度な機能

品質ゲートの設定

厳格さは 3 つのモードから選べます。

• Strict：すべての TRUST 寸法がしきい値以上で、重大な問題がゼロであり、カバレッジが完全であること
• Standard：平均スコアがしきい値以上で、重大な問題によるブロックがなく、警告は許容されること
• Lenient：重大なブロッカーのみが進行を妨げること

ゲート設定：寸法ごとのしきい値、重大度別の問題の最大数、カバレッジ目標、パフォーマンスベンチマーク。

CI/CD 統合

4 段階のパイプライン：コード品質 → テスト → パフォーマンス → セキュリティ。各段階で失敗するとパイプラインを終了し、その段階に応じた失敗レポートを出力します。

ジョブ設定の手順については、CI/CD 統合パターン（GitHub Actions + Docker）を参照してください。

E2E／ブラウザテスト

Playwright のパターン（ページオブジェクトモデル、クロスブラウザ、ビジュアルリグレッション）とドキュメント検索の統合に対応しています。Playwright のベストプラクティスを参照してください。

---

モジュール

各ワークフロー段階を詳しく説明するモジュールです。これらは概念的なワークフロー（インポート可能な SDK ではありません）を説明するもので、各プロジェクト独自のツールチェーンに適用してください。モジュールのインデックスから始めるか、各段階に直接進んでください。

• AI によるデバッグ — エラー分類＋解決策候補
• スマートリファクタリング — 技術的負債の分析＋安全な変換
• パフォーマンス最適化 — プロファイリング＋ボトルネック検出
• 自動コードレビュー — TRUST 5 スコアリング＋静的解析

---

相性の良い機能

• moai-domain-backend：バックエンドのテストパターン
• moai-domain-frontend：フロントエンド UI のテスト
• moai-foundation-core：SPEC システムの統合
• moai-domain-database / moai-domain-frontend / moai-domain-backend：プラットフォーム固有のテスト
• moai-workflow-project：プロジェクト管理ワークフロー

---

ステータス：本番環境で利用可能 メンテナンス担当：MoAI-ADK Development Workflow Team バージョン：2.5.0（監査対応：言語中立性＋モジュールリンクの再設定）

よくある自己正当化

自己正当化	実情
「このコードはすでに統合テストでカバーされています」	統合テストで検出できるバグは、ユニットテストで検出できるバグとは異なります。テストピラミッドが存在するのには理由があります。
「データベースのモックを作るのは難しすぎるので、そのテストは省略します」	結合度の高さが原因でテストを書くのが難しいなら、コードにはより適切な抽象化の境界が必要です。
「カバレッジは80%あれば十分です」	カバレッジの目標値は最低基準であり、上限ではありません。カバーされていない20%には、多くの場合、エラー処理のパスが含まれています。
「これは単なるユーティリティ関数なので、テストは必要ありません」	ユーティリティ関数は最も再利用されるコードです。ユーティリティのバグはあらゆる箇所に広がります。
「ローカルでテストを実行したので、CIも通ります」	環境の違いにより、CIでのみ失敗することがあります。ローカルでの実行結果ではなく、CIの出力を信頼してください。
「不安定なテストはよくあるので、再実行すればよいです」	不安定なテストは実際の失敗を見えにくくします。不安定さを修正するか、そのテストを明示的に隔離してください。

シフトレフト：欠陥をできるだけ早い段階で見つけて修正します。ローカルではなくCIで実行されるテストは、すべて遅延を増やします。ユニットテストにできたはずなのにE2Eテストになっているテストは、すべて脆弱性を高めます。

ビヨンセ・ルール：気に入ったなら、テストを書いておくべきでした。テストされていない動作は、仕様が定まっていない動作です。

危険信号

• 機能の追加後にカバレッジレポートのカバレッジが低下している
• テストファイルに t.Skip() または skip があり、課題トラッカーへのリンクが添えられていない
• テスト名が動作を説明する名前ではなく、自動生成された名前（test_1、test_2）になっている
• 新しい関数のエラー／失敗分岐を扱うテストがない
• テストファイルがインターフェースではなく、具体的な実装をインポートしている

検証

• テストスイートが失敗ゼロで通る（コマンドの出力を貼り付ける）
• カバレッジレポートを生成し、変更したパッケージが85%のしきい値を満たしている
• エラー経路に専用のテストケースがある（正常系だけではない）
• 不安定なテストを新たに導入していない（安定性を確認するため、-count=3 で実行する）
• テストの分離を確認済み：各テストが独自のフィクスチャまたは t.TempDir() を使用している
• 並行処理を行うコードでレースディテクターを通過している（go test -race または同等のコマンド）