プロジェクト構成

create mastra コマンドで作成した新しい Mastra プロジェクトには、開発を始めるためのファイルとフォルダー一式があらかじめ用意されています。

Mastra はフレームワークですが、ファイルの整理方法や同じ場所に配置する方法については、ほとんど規定していません。CLI が提供する実用的なデフォルト構成は大半のプロジェクトに適していますが、ワークフローやチームの慣習に合わせて自由に変更できます。必要であれば、プロジェクト全体を1つのファイルで構築することも可能です。どの構成を選ぶ場合でも、一貫性を保ち、コードを保守しやすく閲覧しやすい状態にしてください。

デフォルトのプロジェクト構成

create mastra コマンドで作成したプロジェクトは、次のような構成になります。

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

あらかじめ用意されたファイルをテンプレートとして使用してください。複製して用途に合わせることで、独自の Agent、Tool、Workflow などをすばやく作成できます。

フォルダー

Mastra では、次のフォルダーにコードを整理することを推奨しています。

フォルダー	説明
src/mastra	Mastra 関連のすべてのコードと設定のエントリーポイント。
src/mastra/agents	Agent の動作、目標、Tool を定義して設定します。
src/mastra/workflows	Agent と Tool を連携させる複数ステップの Workflow を定義します。
src/mastra/tools	Agent が呼び出せる再利用可能な Tool を作成します。
src/mastra/mcp	外部の Agent と Tool を共有するためのカスタム MCP サーバーを実装します。
src/mastra/scorers	Agent のパフォーマンスを継続的に評価する Scorer を定義します。

Mastra には、2つの特別なフォルダー規則があります。

• src/mastra/agents/<name>：コード内で構築する代わりに、ファイル規則に基づいて Agent を定義できます。詳しくは、ファイルベースの Agent のドキュメントを参照してください。
• src/mastra/public：ビルド時に内容が .build/output ディレクトリへコピーされ、実行時に配信できるようになります。

トップレベルファイル

トップレベルファイルでは、Mastra プロジェクトの設定、ビルド、環境との接続方法を定義します。

ファイル	説明
src/mastra/index.ts	Mastra を設定して初期化する中心的なエントリーポイント。
.env.example	環境変数のテンプレート。コピーして .env に名前を変更し、秘密のモデル Providerキーを追加します。
package.json	プロジェクトのメタデータ、依存関係、利用可能な npm スクリプトを定義します。
tsconfig.json	パスエイリアス、コンパイラー設定、ビルド出力などの TypeScript オプションを設定します。