moai-foundation-core

MoAI Foundation Core

MoAI-ADK の AI 主導型開発ワークフローを支える基盤原則とアーキテクチャパターンです。

中核となる理念：実証済みのパターンと自動化されたワークフローを通じて、品質優先、ドメイン駆動、モジュール化、効率的な AI 開発を実現します。

クイックリファレンス

MoAI Foundation Core とは？

AI を活用した開発の品質、効率、拡張性を確保するための 6 つの重要な原則です。

1. TRUST 5 Framework - 品質ゲートシステム（Tested、Readable、Unified、Secured、Trackable）
2. SPEC-First DDD - 仕様駆動型のドメイン駆動開発ワークフロー
3. 委任パターン - 専門エージェントによるタスクのオーケストレーション（直接実行はしません）
4. トークン最適化 - 200K の予算管理とコンテキストの効率化
5. 段階的な情報開示 - 3 段階のナレッジ提供（クイック、実装、上級）
6. モジュラーシステム - 拡張性を高めるファイル分割とリファレンスアーキテクチャ

クイックアクセス：

• 品質基準は modules/trust-5-framework.md を参照してください
• 開発ワークフローは modules/spec-first-ddd.md を参照してください
• エージェントの連携は modules/delegation-patterns.md を参照してください
• 予算管理は modules/token-optimization.md を参照してください
• コンテンツ構造は modules/progressive-disclosure.md を参照してください
• ファイル構成は modules/modular-system.md を参照してください
• エージェントカタログは modules/agents-reference.md を参照してください
• コマンドリファレンスは modules/commands-reference.md を参照してください
• セキュリティと制約は modules/execution-rules.md を参照してください

ユースケース：

• 品質基準を備えた新しいエージェントの作成
• 構造ガイドラインに沿った新しいスキルの開発
• 複雑なワークフローのオーケストレーション
• トークン予算の計画と最適化
• ドキュメントアーキテクチャの設計
• 品質ゲートの設定

---

実装ガイド

1. TRUST 5 Framework - 品質保証システム

目的：コードの品質、セキュリティ、保守性を確保する自動品質ゲートです。

5 つの柱：

Tested の柱：動作の維持を確認する特性テストを含め、包括的なテストカバレッジを維持します。カバレッジを取得しながら、プロジェクトのテストランナーを実行します（例：go test -cover、pytest --cov、cargo test、npm test -- --coverage）。失敗した場合はマージをブロックし、不足しているテストを生成します。特性テストはレガシーコードの現在の動作を捉え、仕様テストは新しいコードのドメイン要件を検証します。高いカバレッジはコードの信頼性を高め、本番環境での不具合を減らし、リファクタリング中の動作を維持します。

Readable の柱：明確で説明的な命名規則を使用します。プロジェクトのリンターを実行します（例：golangci-lint、ruff、eslint、clippy）。失敗した場合は警告を出し、リファクタリングによる改善を提案します。明確な命名は、コードの理解、チームのコラボレーション、保守の迅速化につながります。

Unified の柱：一貫したフォーマットとインポートのパターンを適用します。プロジェクトのフォーマッターを実行します（例：gofmt、black、prettier、rustfmt）。コードを自動フォーマットするか、失敗した場合は警告を出します。一貫性により、スタイルに関する議論やマージコンフリクトをなくし、可読性を高めます。

Secured の柱：OWASP のセキュリティ標準に準拠します。適切なエージェントまたはリファレンススキルを通じて、セキュリティ上の問題を提示します（例：セキュリティの指示を付けて汎用エージェントをスポーンする、または moai-ref-owasp-checklist / moai-ref-llm-security リファレンスを読み込む）。失敗した場合はマージをブロックし、セキュリティレビューを必須とします。セキュリティの脆弱性は、重大なビジネスリスクや法的リスクを招きます。

Trackable の柱：明確で構造化されたコミットメッセージを作成します。Git のコミットメッセージの正規表現パターン（Conventional Commits）に一致させます。失敗した場合は、適切なコミットメッセージの形式を提案します。明確な履歴は、デバッグ、監査、コラボレーションを可能にします。

統合ポイント：自動検証のためのプレコミットフック、品質ゲートを適用する CI/CD パイプライン、TRUST 5 検証のためのエージェントワークフロー（moai-foundation-quality オーケストレーション）、品質メトリクスのためのドキュメントです。

詳細リファレンス：modules/trust-5-framework.md

---

2. SPEC ファースト DDD - 開発ワークフロー

目的：実装前に要件を明確にする、仕様駆動開発です。

3 フェーズのワークフロー：

フェーズ 1 SPEC（/moai plan）：workflow-spec が GEARS 形式を生成します（現行の主要形式。EARS は 6 か月間の後方互換性を確保するためのレガシー参考資料として保持され、v3 より前の 88 件の SPEC で使用されています）。出力先は .moai/specs/SPEC-XXX/spec.md です。/clear を実行して 45～50K トークンを節約します。

フェーズ 2 DDD（/moai run）：要件の ANALYZE、既存の動作の PRESERVE、機能強化の IMPROVE を行います。カバレッジ 85％以上で検証します。

フェーズ 3 ドキュメント（/moai sync）：API ドキュメント、アーキテクチャ図、プロジェクトレポートを作成します。

GEARS 形式（現行の記法）：5 つのパターン — Ubiquitous「The shall 」はシステム全体で常に有効な要件、Event-driven「When the shall 」はトリガーに応じた応答の要件、State-driven「While the shall 」は条件付きの動作、Where（機能ゲート）「Where , the shall 」は機能に応じた動作、Event-detected（非推奨の条件モダリティに代わる形式）「When , the shall 」は障害モードへの対応を表します。統一された複合節：「[Where ...][While ...][When ...] The shall 」— 3 つの修飾句は、任意の組み合わせで連結できます。<subject> は一般化されており、任意の名詞（system、component、service、agent、function、artifact）を使用できます。正規の作成ガイドについては、~/.claude/skills/moai-workflow-spec/SKILL.md の「GEARS Format」を参照してください。

EARS 形式（レガシー参考資料、6 か月間の後方互換性 — 2026-11-22 に期限切れ）：5 つのパターン Ubiquitous / Event-driven（WHEN/THEN）/ State-driven（WHILE）/ Unwanted（SHALL NOT）/ Optional（WHERE possible）。v3 より前の 88 件の SPEC では引き続き EARS が使用されています。lint エンジンは、新しい SPEC に残存する非推奨の条件モダリティに対して LegacyEARSKeyword 警告を出力します（通常は警告、moai spec lint --strict ではエラー）。新しい SPEC では GEARS を使用してください。modules/spec-ears-format.md を参照してください（レガシー参考資料、非推奨 — GEARS 形式のガイドを参照）。

トークン予算：SPEC は 30K、DDD は 180K、ドキュメントは 40K、合計 250K です。

重要な実践：フェーズ 1 の後に /clear を実行して、コンテキストを初期化してください。

詳細なリファレンス：modules/spec-first-ddd.md

---

3. 委任パターン - エージェントオーケストレーション

目的：直接実行を避け、専門エージェントにタスクを委任します。

基本原則：MoAI は、すべての作業を Agent() を通じて専門エージェントに委任する必要があります。直接実行すると、専門化、品質ゲート、トークン最適化を迂回してしまいます。適切な委任により、タスクの成功率が 40 パーセント向上し、並列実行が可能になります。

委任構文：MoAI は自然言語で委任します — 「Use the {agent} subagent to {task}」 — 完全なコンテキスト、制約、根拠を伝えます。オーケストレーターは subagent_type のコードリテラルを渡しません。代わりに、説明文のプロンプトを指定して Agent()（またはドメイン作業には Agent(general-purpose)）を起動します。

3 つのパターン：

依存関係がある場合は逐次実行：manager-spec サブエージェントを使用して SPEC を作成し、その後、SPEC をコンテキストとして manager-develop サブエージェントを使用して実装します。

独立した作業は並列実行：作業が独立している場合は、1 回のターンで複数の Agent(general-purpose) チームメイトを起動します。たとえば、バックエンド向けの指示を与えたエージェントと、フロントエンド向けの指示を与えたエージェントをそれぞれ起動します。

分析結果に基づく条件付き実行：読み取り専用の診断には Explore サブエージェントを使用し、調査結果に応じて適切な担当エージェント（修正には manager-develop、品質スコアリングには sync-auditor）に結果を渡します。

エージェントの選択：1 ファイルの単純なタスクでは、1～2 個のエージェントを逐次使用します。3～5 ファイルの中規模タスクでは、2～3 個のエージェントを逐次使用します。10 ファイル以上の複雑なタスクでは、5 個以上のエージェントを組み合わせて使用します。ドメイン固有の作業（バックエンド／フロントエンド／セキュリティ／パフォーマンス／リファクタリング）は、実行フェーズで manager-develop が担当するか、.claude/rules/moai/workflow/archived-agent-rejection.md に従ってドメインの許可リストを設定した Agent(general-purpose) を起動ごとに使用します。

詳細なリファレンス：modules/delegation-patterns.md

---

4. トークンの最適化 - 予算管理

目的：戦略的なコンテキスト管理により、200K トークンの予算を効率的に活用します。

予算の割り当て：

SPEC フェーズでは 30K トークンを使用します。要件のみを読み込み、完了後に /clear を実行するのが戦略です。仕様策定フェーズでは、要件分析に必要な最小限のコンテキストを使用します。これにより、実装フェーズ用に 45～50K トークンを節約できます。

DDD フェーズでは 180K トークンを使用します。実装に関連するファイルのみを読み込む、選択的なファイル読み込みが戦略です。実装には深いコンテキストが必要ですが、コードベース全体は必要ありません。予算内で 70 パーセント規模の大きな実装が可能になります。

ドキュメントフェーズでは 40K トークンを使用します。結果のキャッシュとテンプレートの再利用が戦略です。ドキュメントは完了済みの作業成果物を基に作成します。冗長なファイル読み込みを 60 パーセント削減できます。

全フェーズの合計予算は 250K トークンです。フェーズを分離し、フェーズ間でコンテキストをリセットすると、コンテキストの境界が明確になり、トークンの肥大化を防げます。同じ予算で 2～3 倍規模のプロジェクトが可能になります。

トークン節約戦略：

フェーズの分離：フェーズ間、45～50K を節約するための /moai plan の後、コンテキストが 150K を超えたとき、50 件以上のメッセージの後に /clear を実行します。

選択的な読み込み：必要なファイルのみを読み込みます。

コンテキストの最適化：20～30K トークンを目標にします。

モデルの選択：品質重視には Sonnet、速度とコスト重視には Haiku を使用します。料金が 70% 安いため、合計で 60～70% の節約になります。

詳細なリファレンス：modules/token-optimization.md

---

5. 段階的な開示 - コンテンツアーキテクチャ

目的：価値と深さのバランスを取りながら、3段階で知識を提供します。

3つのレベル：

クイックリファレンスレベル：所要時間30秒、基本原則と必須概念、約1,000トークン。時間に制約のあるユーザーに迅速に価値を提供します。ユーザーは所要時間の5％で、理解度の80％を得られます。

実装レベル：所要時間5分、ワークフロー、実践的な例、統合パターン、約3,000トークン。実行可能なガイダンスにより、概念と実行をつなぎます。深い専門知識がなくても、すぐに生産的な作業を始められます。

高度レベル：所要時間10分以上、技術的な詳細、エッジケース、最適化手法、約5,000トークン。複雑なシナリオに対応する、熟達レベルの知識を提供します。包括的な情報により、エスカレーションを70％削減します。

SKILL.md の構成（最大500行）：クイックリファレンスセクション、実装ガイドセクション、高度なパターンセクション、相性のよいツールセクション。

モジュールアーキテクチャ：SKILL.md を相互参照を含むエントリーポイントとし、詳細な解説用の modules ディレクトリ（サイズ制限なし）、動作サンプル用の examples.md、外部リンク用の reference.md を用意します。

500行を超える場合のファイル分割：SKILL.md には、クイックを80～120行、実装を180～250行、高度な内容を80～140行、参考情報を10～20行で記載します。超過した内容は modules/topic.md に移します。

詳細なリファレンス：modules/progressive-disclosure.md

---

6. モジュール型システム - ファイル構成

目的：コンテンツを無制限に追加できる、拡張性の高いファイル構造を実現します。

標準構成：.claude/skills/skill-name/ ディレクトリを作成し、コアファイルとして500行未満の SKILL.md、サイズ制限のない拡張コンテンツ用の modules ディレクトリ（patterns.md を含む）、動作サンプル用の examples.md、外部リンク用の reference.md、ユーティリティ用の scripts ディレクトリ（任意）、templates ディレクトリ（任意）を配置します。

ファイルの原則：SKILL.md は段階的な開示と相互参照を取り入れ、500行未満に保ちます。modules ディレクトリはトピックに特化した、サイズ制限のない自己完結型のコンテンツを配置します。examples.md はコメント付きで、コピーしてすぐに使える内容にします。reference.md には API ドキュメントとリソースを記載します。

相互参照の構文：modules/patterns.md の詳細は Details として参照し、examples.md#auth のサンプルは Examples として参照し、reference.md#api の外部ドキュメントは External として参照します。

検出フロー：SKILL.md からトピックへ、さらに modules/topic.md へ進み、詳細を確認します。

詳細なリファレンス：modules/modular-system.md

---

高度な実装

モジュール間の統合、品質検証、エラー処理などの高度なパターンについては、詳細なモジュールリファレンスを参照してください。

主な高度なトピック：

• モジュール間の統合：TRUST 5 と SPEC-First DDD の組み合わせ
• トークンを最適化した委任：コンテキストをリセットしながら並列実行
• 段階的なエージェントのワークフロー：エスカレーションパターン
• 品質検証：実行前後の検証
• エラー処理：委任の失敗からの復旧

詳細なリファレンス：動作するコードサンプルは references/examples.md を参照してください

---

相性の良いもの

エージェント：基盤原則に基づいてエージェント／スキル／ハーネスを生成する builder-harness、計画フェーズの文書を作成する manager-spec、実行フェーズの実装を行う manager-develop、同期フェーズのドキュメントを作成する manager-docs、独立して TRUST 5 の品質を評価する sync-auditor、必要に応じて高度な推論による相談を行う super-advisor。

スキル：Claude Code の作成（スキル、エージェント、プラグイン、フック）を行う moai-foundation-cc、GEARS 形式の仕様（現行形式。EARS はレガシーな参考資料として保持）を扱う moai-workflow-spec、ANALYZE-PRESERVE-IMPROVE の実行を行う moai-workflow-ddd、RED-GREEN-REFACTOR サイクルを行う moai-workflow-tdd、TRUST 5 の検証を統括する moai-foundation-quality、戦略的推論と ultrathink キーワードによる Adaptive Thinking を行う moai-foundation-thinking。

ツール：ユーザーとの直接的なやり取りや確認が必要な場合の AskUserQuestion。

コマンド：SPEC-First フェーズ 1 の /moai plan、DDD フェーズ 2 の /moai run、ドキュメントフェーズ 3 の /moai sync、継続的な改善のための /moai feedback、トークン管理のための /clear。

基盤モジュール（詳細ドキュメント）：13 エージェントの保持カタログ（MoAI カスタム 12 個。manager-lead と manager-todo を含む。＋ Anthropic 標準の Explore 1 個）については modules/agents-reference.md、6 つのコアコマンドのワークフローについては modules/commands-reference.md、セキュリティ、Git 戦略、コンプライアンスについては modules/execution-rules.md を参照してください。アーカイブ済みエージェント 12 個（manager-strategy、manager-quality、manager-brain、manager-project、claude-code-guide、researcher、および 6 個の expert-* エージェント）への参照を移行する方法については、.claude/rules/moai/workflow/archived-agent-rejection.md を参照してください。

---

クイック判断ガイド

新しいエージェント：主原則は TRUST 5 と委譲です。補助原則はトークン最適化とモジュール化です。

新しいスキル：主原則はプログレッシブとモジュール化です。補助原則は TRUST 5 とトークン最適化です。

ワークフロー：主原則は委譲パターンです。補助原則は SPEC-First とトークン最適化です。

品質：主原則は TRUST 5 フレームワークです。補助原則は SPEC-First DDD です。

予算：主原則はトークン最適化です。補助原則はプログレッシブとモジュール化です。

ドキュメント：主原則はプログレッシブとモジュール化です。補助原則はトークン最適化です。

モジュールの詳細：modules/trust-5-framework.md、modules/spec-first-ddd.md、modules/delegation-patterns.md、modules/token-optimization.md、modules/progressive-disclosure.md、modules/modular-system.md、modules/agents-reference.md、modules/commands-reference.md、modules/execution-rules.md。

完全な例：references/examples.md 外部リソース：references/reference.md

よくある誤った判断

誤った判断	実際のところ
「TRUST 5 はガイドラインであり、必須条件ではない」	TRUST 5 は必須の品質ゲートです。完了前に 5 つすべてのディメンションに合格する必要があります。
「小さな変更なので SPEC を省略できる」	SPEC のない変更はすべて追跡されません。SPEC のない変更が積み重なると、管理不能な技術的負債になります。
「単純なタスクでは、エージェントへの委譲は余計な手間になる」	MoAI はオーケストレーターであり、実装者ではありません。委譲を省略すると、ドメインの専門知識や品質チェックを迂回することになります。
「コードは明らかに正しいので、品質ゲートを省略する」	明らかに正しいコードでも、根拠が必要です。テストとリンティングは検証手段であり、自信は根拠ではありません。
「このプロジェクトではプログレッシブ開示は重要ではない」	小規模なプロジェクトでも、トークン効率の良いスキル読み込みは有益です。開示はプロジェクトの規模ではなく、コンテキストの予算に関するものです。

危険信号

• エージェントに委譲せず、MoAI が実装コードを直接実行している
• TRUST 5 のディメンションを一部しかチェックしていない（Tested と Readable だけを確認し、Secured を無視している）
• SPEC ドキュメントがあるものの、受け入れ基準がない
• 選択判断ツリーを参照せずにエージェントを選んでいる
• 「後で確認する」というコメントを残して品質ゲートを省略している

検証

• TRUST 5 の5つの側面すべてに対応している（テスト済み、読みやすい、統一されている、安全である、追跡可能である）
• エージェントの選定について、意思決定ツリーに沿った根拠が記載されている
• SPEC ドキュメントに、観察可能な証拠の要件を含む受け入れ基準がある
• 委任の連鎖を追跡できる：MoAI -> エージェント -> 実行
• スキルのフロントマターで段階的開示レベルが設定されている

---

トークン予算（moai-foundation-context から取り込み）

コンテキストウィンドウの最適化、/clear 戦略、セッション状態の永続化、マルチエージェントの引き継ぎパターンについて説明します。

コンテキストウィンドウの目標

モデルクラスごとの権威ある /clear 閾値表（1M/GLM = 50%、200K/256K = 90%）については、.claude/rules/moai/workflow/context-window-management.md § Context Window Targets を参照してください。ここでは閾値を再記載しないでください（SSOT）。

フェーズごとのトークン割り当て

フェーズ	予算	戦略
/moai plan	30,000	要件のみを読み込み、完了後に /clear
/moai run	180,000	ファイルを選択的に読み込み、必要に応じてスキルを読み込み
/moai sync	40,000	結果をキャッシュし、重複する読み込みを削減

/clear 戦略

必須の /clear 実行ポイント：

1. /moai plan の完了後（/moai run の前）
2. コンテキストが 150,000 トークンを超えたとき（Sonnet/standard）
3. 主要なフェーズの移行前

次の場合は /clear を実行しないでください：エージェントタスクの途中、セッション状態が永続化されていない場合。

セッション状態の永続化

/clear の前に、進行中の状態を .moai/specs/<SPEC-ID>/progress.md に保存してください：

• 現在のタスクの状態（完了、進行中、ブロック中）
• ファイル変更の概要
• 次に必要なアクション
• /clear 後に貼り戻す再開メッセージ

再開メッセージの形式：

Wave <N> 이어서 진행. SPEC-<ID>부터 <approach>.
progress.md: .moai/specs/<ID>/progress.md
다음 단계: <command>.

マルチエージェントの引き継ぎ

コンテキストの上限に近い状態でサブエージェントに委任する場合：

1. Agent() の呼び出し前に、調査結果を progress.md に要約する
2. spawn プロンプトには必要なコンテキストのみを渡す（ファイル全体のダンプは避ける）
3. サブエージェントの結果は戻り時に親のコンテキストに追加されるため、それを考慮する
4. 戻り後に親のコンテキストが 120,000 トークンを超えている場合は、保存して /clear を実行する

最適化パターンの全容：modules/token-optimization.md