moai-foundation-quality

TRUST 5 品質原則と適用方法

このスキルでは、MoAI の品質モデルに関する背景知識を提供します。5 つの TRUST 5 原則、エージェントによる適用方法、3 段階のハーネス、および /moai gate が実行する言語対応ツールチェーンについて説明します。MoAI には品質検証ライブラリは含まれていません。品質は、エージェント（manager-develop、sync-auditor）、スラッシュコマンド（/moai gate、/moai review）、およびハーネス（minimal/standard/thorough）によって適用されます。

クイックリファレンス

TRUST 5 原則（Tested、Readable、Unified、Secured、Trackable）は品質の観点であり、コードオブジェクトではありません。すべてのコード変更を 5 つすべての観点で評価します。

品質メカニズム（実際に適用するレイヤー）：

• /moai gate — lint + format + type-check + test を並列実行する、コミット前の品質ゲート（<30s）です。プロジェクトの言語を自動検出し、適切なツールチェーンを実行します。
• manager-develop（run-phase）— cycle_type ∈ {tdd, ddd, autofix} に基づいて実装します。選択したサイクルによって、テストと動作の実現方法が決まります。
• sync-auditor — 4 つの観点（Functionality、Security、Craft、Consistency）でスコアリングする、独立した懐疑的な品質評価です。スコアは各観点の平均ではなく、調和平均で算出します。
• 3 段階のハーネス — minimal（高速な検証）、standard（デフォルトのチェック）、thorough（完全な sync-auditor + TRUST 5）です。SPEC の範囲に基づき、Complexity Estimator が自動的に決定します。
• LSP 品質ゲート — フェーズごとのしきい値です（run：errors/type-errors/lint-errors がゼロ、sync：errors がゼロ、warnings は最大 10 件、LSP がクリーン）。

MoAI の品質モデル

MoAI は、品質検証のための Python SDK やライブラリを提供していません。品質は、ワークフロー、エージェント、ゲートコマンドを通じて適用されます。このスキルでは、Claude の呼び出しが品質について正しく判断できるよう、これらの要素の連携方法を説明します。

フェーズごとの TRUST 5 の適用方法

フェーズ	品質チェック	担当
plan	LSP のベースラインを記録し、計画内の品質リスクを特定する	manager-spec
run	errors/type-errors/lint-errors がゼロであること、テストが合格すること、カバレッジが基準を満たすこと	manager-develop（アプローチは cycle_type によって決まります）
sync	lint がクリーン（≤10 warnings）であること、ドキュメントが更新されていること、TRUST 5 が再確認されていること	manager-docs、その後 sync-auditor が採点
audit	独立した 4 観点でのスコアリング（Functionality/Security/Craft/Consistency）	sync-auditor

cycle_type と品質（manager-develop）

run-phase の cycle_type によって、品質を組み込む方法が決まります。

• tdd — テスト駆動開発（RED-GREEN-REFACTOR）です。まず失敗するテストで動作を仕様化し、その後に実装します。新機能に最適です。
• ddd — ドメイン駆動リファクタリング（ANALYZE-PRESERVE-IMPROVE）です。既存コードの動作を維持しながら変換します。リファクタリングや技術的負債の削減に最適です。
• autofix — 診断結果に基づく修正（LSP / lint / type errors）です。/moai fix やリグレッションからの復旧に最適です。

各サイクルの具体的な仕組みについては、Skill("moai-workflow-tdd")、Skill("moai-workflow-ddd")、Skill("moai-workflow-loop") を参照してください。

TRUST 5 原則

TRUST 5 は、5 つの品質の側面を表す語呂合わせです。それぞれをスコアとして算出するのではなく、変更に対して確認する質問として扱います。

• T — テスト済み：変更にはテストがありますか？テストはすべて成功していますか？カバレッジはプロジェクトのしきい値（デフォルトで 85% 以上）以上ですか？既存のテスト未実施コードについては、現行の動作を記録する特性テストがありますか？
• R — 読みやすい：命名は明確ですか？コメントは英語（または設定されたコードコメントの言語）で書かれていますか？新しいコントリビューターが、説明を受けなくてもロジックを理解できますか？
• U — 統一されている：変更はファイル内の既存の規約（命名、エラー処理、インポート）に沿っていますか？プロジェクトのフォーマッターで整形されていますか？個人の好みより、ファイル内の一貫性を優先します。
• S — セキュアである：外部からの入力はすべて検証されていますか？Web セキュリティに関する OWASP のガイダンスに従っていますか？認証情報はバージョン管理の対象外になっていますか（代わりに環境変数を使用します）？moai-ref-owasp-checklist を参照してください。
• T — 追跡可能である：コミットは Conventional Commits に従っていますか？実装する SPEC／issue を参照していますか？変更を要件までたどれますか？

各原則の評価チェックリストと「該当なし」ガードについては、TRUST 5 Principles を参照してください。

品質ゲートと 3 段階ハーネス

ハーネスのレベルによって、品質検証の深さが決まります。SPEC の範囲に基づき、複雑性推定器がレベルを自動判定します。

レベル	実行内容	適用される場合
minimal	高速な検証のみ（lint + type + test）	小規模な SPEC、リスクが低い場合
standard	デフォルトのチェック（lint + type + test + format）	ほとんどの SPEC
thorough	sync-auditor による完全なチェック + 4 次元の TRUST 5 スコアリング	大規模な SPEC、リスクが高い場合

/moai gate は、軽量なコミット前チェックのエントリーポイントです。lint + format + type-check + test を並列で実行し、修正は適用しません。品質の状態をすばやく確認する最速の方法です。より詳細なレビューには /moai review を使用してください。

言語対応のツールチェーン

品質ゲートはプロジェクトの言語を自動検出し、適切なツールチェーンを実行します。インストールされていないツールは適切にスキップされ、認識可能な言語マーカーがないプロジェクトは、ゲートを何も表示せずに通過します。このスキルは言語に依存せず、サポート対象の 16 言語をすべて同等に扱います。

言語	Lint	Format	Test
Go	go vet → golangci-lint	gofmt	go test
Python	ruff	black	pytest
TypeScript / JavaScript	eslint	prettier	jest / mocha
Rust	cargo clippy	rustfmt	cargo test
Java / Kotlin	(プロジェクトの linter による)	(プロジェクトによる)	junit
Ruby	rubocop	rubocop	rspec
PHP	phpstan / phpcs	php-cs-fixer	pest / phpunit
...	(16 言語をサポート。自動検出)

ツールチェーンの全マッピングと /moai gate による言語検出の仕組みについては、Language-Aware Toolchains を参照してください。

モジュールリファレンス

各モジュールは必要に応じて読み込まれます。現在のタスクに関連するものを読み込んでください。

• TRUST 5 Principles — 評価項目としての 5 つの側面、各原則のチェックリスト、「該当なし」ガード。
• Proactive Analysis — /moai gate、/moai review、/moai loop が品質上の問題を事前に検出する仕組みと、検出結果のトリアージ方法。
• Best Practices — WebSearch / WebFetch を使用してフレームワークやライブラリの最新のベストプラクティスを調べ、それらに照らして検証する方法。
• Integration Patterns — SPEC ワークフローの各フェーズ（plan/run/sync）およびハーネスの各レベルに、品質をどのように組み込むか。

参考ファイル

• examples.md — TRUST 5 の評価例と、ゲート／レビューのトリアージ手順を 実例で解説しています。具体的な変更に TRUST 5 を適用する際に読み込んでください。
• reference.md — 品質メカニズムのリファレンスです。 ハーネスの詳細レベル、言語ツールチェーンの表、エージェントの役割、 sync-auditor のスコアリングモデルを掲載しています。正式な対応関係を確認する際に読み込んでください。

相性のよいもの

エージェント（13 エージェントのカタログは .moai/config/sections/delegation.yaml を参照）：

• manager-develop — run フェーズの実装を担当し、cycle_type を通じて Tested と Unified の 原則を担います。
• sync-auditor — 4 つの独立した観点から品質を採点します（Functionality／ Security／Craft／Consistency）。
• Explore（Anthropic 組み込み）— 品質を評価する前に、コードベースを読み取り専用で調査します。

スキル：

• moai-foundation-core — TRUST 5 フレームワークの相互参照と SPEC ワークフローの基礎。
• moai-ref-testing-pyramid — テストピラミッド戦略、カバレッジ目標、テストパターン。
• moai-ref-owasp-checklist — Secured 原則のための OWASP Top 10 セキュリティチェックリスト。
• moai-workflow-tdd / moai-workflow-ddd / moai-workflow-loop — manager-develop が使用する cycle_type ワークフロー。

コマンド：

• /moai gate — コミット前の品質ゲート（lint + format + type + test）。
• /moai review — セキュリティと MX タグの準拠状況を含むコードレビュー。
• /moai fix — LSP／lint／type のエラーを自動検出して修正します。
• /moai loop — 解決するまで、または最大反復回数に達するまで、修正を繰り返します。

よくある正当化

正当化	実態
「リンターの警告は誤検出です」	誤検出はインラインコメントで抑制してください。無視すると、チームが実際の問題も無視するようになります。
「セキュリティスキャンはリリース前まで待てます」	セキュリティの脆弱性は積み重なります。発見が遅れると、手戻りのコストが増大します。継続的にスキャンしてください。
「カバレッジは十分に高く、残りの 15% はエッジケースです」	エッジケースに本番環境のバグは潜んでいます。カバーされていないコードは、最もリスクの高いコードです。
「コードレビューには主観が入り、自動化だけで十分です」	自動化で検出できるのは構文やパターンです。レビューでは設計上の欠陥、わかりにくい命名、抽象化の不足を見つけます。
「TRUST 5 は緊急修正には官僚的すぎます」	品質ゲートを通さない緊急修正は、次の緊急修正を招きます。緊急修正での TRUST 5 は最低限であり、最大限ではありません。

チェスタトンの柵：品質チェックを削除する前に、なぜ追加されたのかを理解してください。その経緯を理解せずにゲートを削除すると、防ぐために設計された失敗を繰り返すことになります。

シフトレフト：欠陥の発見が早いほど、修正コストは低くなります。品質チェックは開発の終わりではなく、開発サイクルに組み込んでください。

危険信号

• リンターまたは型チェッカーの警告が、行ごとではなくグローバルに抑制されている
• ユーザー入力または認証を扱う際に、OWASP チェックリストを参照していない
• 新しい機能を追加するコミットで、カバレッジレポートが生成されていない
• TRUST 5 の項目を、根拠なく「該当なし」として省略している
• 品質レポートを生成したものの、特定された問題に対処していない

検証

• リンターが警告なしで実行されるか、残りの警告に理由を添えたインライン抑制コメントがある（コマンド出力を示す）
• セキュリティに関係する変更について OWASP チェックリストを確認している（チェックリストの参照箇所を示す）
• カバレッジレポートが生成され、しきい値を満たしている（ツールの出力を示す）
• TRUST 5 の 5 つの観点すべてを評価している（各観点の評価を示す）
• 品質に関する指摘をトリアージし、それぞれに解決計画を立てている
• リンター設定でルールをグローバルに無効化していない