TypeScript×Mastraで始めるWebアプリの最適フォルダ構成

はじめに

Mastra（マストラ）は、TypeScript製のオープンソースAIフレームワークです。大規模言語モデル（LLM）を活用したエージェント（Agent）やツール（Tool）、**ワークフロー（Workflow）**の定義を簡潔に行えるため、複雑なAI機能を迅速に組み込めます。本記事では、Mastraを用いてWebアプリを開発する際に推奨されるフォルダ構成を紹介します。適切なディレクトリ階層を設計することで、コードの可読性・保守性・拡張性が大幅に向上します。

プロジェクトのディレクトリ構成例

my-mastra-app/
├── src/
│   └── mastra/
│       ├── agents/
│       ├── tools/
│       ├── workflows/
│       └── index.ts
├── .env
├── package.json
└── tsconfig.json

• src/mastra/agents/：AIエージェント定義用。githubAgent.tsやweatherAgent.tsなど、振る舞いを記述。
• src/mastra/tools/：外部API呼び出しやDB検索などを提供するカスタムツール定義。
• src/mastra/workflows/：複数ステップの対話フローやDurableな状態マシンを定義。
• src/mastra/index.ts：各agents・tools・workflowsを登録してMastraインスタンスを初期化。
• .env：OpenAI APIキーなどの環境変数。
• package.json：依存関係とnpmスクリプト（mastra devなど）を定義。
• tsconfig.json：TypeScriptコンパイラ設定。

各フォルダ・ファイルの目的とメリット

• 可読性／保守性の向上
  機能別にフォルダを分離することで、目的のコードを瞬時に特定でき、レビューやバグ修正が効率化されます。
• 拡張・再利用性
  新規エージェントやツール追加も局所的なファイル作成と登録のみで完了。別プロジェクトへの移植も容易です。
• チーム開発の分業支援
  agentsとtoolsを別担当に割り振るなど、同時並行での作業がしやすく、コンフリクトを低減します。
• フルスタック統合
  Next.js等と併用する際も、src/appとsrc/mastraを明確に分離でき、UIとAIロジックの責務を分担可能です。

---

公式CLIのひな型に沿ったこの構成を採用することで、Mastraを活用したTypeScript製Webアプリの開発効率とコード品質が飛躍的に向上します。ぜひプロジェクトに取り入れてみてください。