> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# 開発

Mastra プロジェクトを作成したら、Agent の開発、実行、テストを始められます。

## Mastra をローカルで実行する

Agent の動作を最も手軽に確認できるのは [Mastra Studio](https://mastra.zisheng.pro/ja/docs/studio/overview) です。プロジェクトのルートから [`mastra dev`](https://mastra.zisheng.pro/ja/reference/cli/mastra) を実行し、Studio とローカル開発サーバーを起動します。

**npm**:

```bash
npx mastra dev
```

**pnpm**:

```bash
pnpm dlx mastra dev
```

**Yarn**:

```bash
yarn dlx mastra dev
```

**Bun**:

```bash
bun x mastra dev
```

[`http://localhost:4111`](http://localhost:4111) で Studio を開き、Agent をテストして実行結果を確認します。

開発サーバーは、Agent、Tool、Workflow 用の API も公開します。[`http://localhost:4111/api`](http://localhost:4111/api) を開いて利用可能な API を確認し、[Mastra Client](https://mastra.zisheng.pro/ja/docs/server/mastra-client) を使用してフロントエンドを接続します。

`src/mastra/` ディレクトリを変更すると開発サーバーが自動的に再起動するため、開発中に手動で再起動する必要はありません。

## AI を活用して構築する

Mastra は、コーディング Agent が高品質な Mastra コードを作成できるようにする Skill と CLI を提供します。

### Mastra Skill

AI モデルが Mastra API に関する最新情報を持っているとは限りません。[Mastra Skill](https://github.com/mastra-ai/skills) を使用すると、実装ガイダンス、ベストプラクティス、最新の Mastra ドキュメントを取得する手順をコーディング Agent に提供できます。

Skill を手動でインストールするには、次を実行します。

**npm**:

```bash
npx skills add mastra-ai/skills
```

**pnpm**:

```bash
pnpm dlx skills add mastra-ai/skills
```

**Yarn**:

```bash
yarn dlx skills add mastra-ai/skills
```

**Bun**:

```bash
bun x skills add mastra-ai/skills
```

最新のガイダンスを利用できるよう、Skill を定期的に更新してください。

**npm**:

```bash
npx skills update mastra
```

**pnpm**:

```bash
pnpm dlx skills update mastra
```

**Yarn**:

```bash
yarn dlx skills update mastra
```

**Bun**:

```bash
bun x skills update mastra
```

> **注記:** [create mastra](https://mastra.zisheng.pro/ja/docs) でプロジェクトを作成すると、コーディング Agent が検出して使用できるように Mastra Skill が自動的にインストールされます。

### Mastra CLI

[`mastra` CLI](https://mastra.zisheng.pro/ja/reference/cli/mastra) を使用すると、コーディング Agent は変更をテストして結果を確認するフィードバックループを構築できます。CLI から Agent、Workflow、Tool、メモリ、Evals、Trace、ログにアクセスできます。

たとえば、コーディング Agent は Agent を実行した後、Trace を取得して結果を確認できます。

```bash
npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}'
npx mastra api --url http://localhost:4111 trace list
```

コーディング Agent が CLI の使い方を理解できるよう、[Mastra Skill](#mastra-skill)をインストールしてください。

## プロジェクト構成

フレームワークを導入する際に最初に決めることの 1 つが、プロジェクトの構成です。フレームワークのコードは `src/mastra/` 以下に配置し、関連するプリミティブを個別のファイルやフォルダーにまとめることを推奨します。設定と登録の中心には `src/mastra/index.ts` を使用します。

最小限のプロジェクト構成は次のようになります。

```text
src/
  mastra/
    agents/
      agent.ts
    tools/
      tool.ts
    workflows/
      workflow.ts
    scorers/
      scorer.ts
    skills.ts
    index.ts
```

デフォルトのレイアウトと推奨規約については、[プロジェクト構成リファレンス](https://mastra.zisheng.pro/ja/reference/project-structure)を参照してください。

## ファイルベースの Agent

> **Beta:** ファイルベースの Agent はベータ版であり、安定版になるまでに変更される可能性があります。
>
> ファイルベースの検出は、`mastra dev` または `mastra build` を介した場合にのみ実行されます。Web フレームワークやサーバーアダプター経由の場合を含め、アプリが `mastra` を直接インポートすると、ファイルベースの Agent は検出されません。そのような Agent はコードで登録するか、Mastra を別のサーバーとして実行してください。

> **📹 動画:** [最初のファイルベース Agent を作成する方法](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s)

ファイルベースの Agent では、Mastra が `src/mastra/` 以下の対応ファイルから Agent と関連プリミティブを自動的に[検出](https://mastra.zisheng.pro/ja/reference/file-based-agents/config)します。各プリミティブを [`Mastra`](https://mastra.zisheng.pro/ja/reference/core/mastra-class) インスタンスにインポートして登録する代わりに、規約に従ってファイルを整理します。

ファイルシステムがプロジェクト構成を直接表すため、コード内の接続関係をたどらなくても、開発者とコーディング Agent の双方がプロジェクト全体の構成を把握できます。

プロジェクト全体でファイルベースの Agent を使用することも、コードで定義したプリミティブと併用しながら段階的に導入することもできます。現時点では、Mastra のすべての機能やユースケースに対応しているわけではありません。

### 最初の Agent を作成する

ファイルベースの Agent は、`src/mastra/agents/` 以下の専用ディレクトリに配置します。動作する Agent を作成するには、モデルとランタイムオプションを定義する `config.ts` ファイルと、常時適用されるプロンプトを記述する `instructions.md` ファイルを追加します。

```text
src/mastra/agents/
  writing-assistant/
    config.ts
    instructions.md
```

ディレクトリ名が Agent のデフォルトの `id` と `name` になります。この例では、Mastra は Agent を `writing-assistant` として登録します。

```typescript
import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})
```

```markdown
Rewrite text clearly and concisely.
```

`npx mastra dev` を実行して Studio を開き、`writing-assistant` を選択してテストします。

### 検出の仕組み

Mastra はパスを使用してファイルベースの機能を検出し、名前を付けます。Agent ディレクトリから、Agent のデフォルトの `id` と `name` が決まります。たとえば、`tools/search_docs.ts` は Tool を `search_docs` として登録し、`skills/style-guide.md` は Skill を `style-guide` として登録します。拡張用のパスを次に示します。

### Agent を拡張する

Agent に機能が必要になったら、ファイルまたはディレクトリを追加します。

| パス                                                                                                     | 追加される機能                     |
| ------------------------------------------------------------------------------------------------------ | --------------------------- |
| [`tools/<tool-name>.ts`](https://mastra.zisheng.pro/ja/reference/file-based-agents/tools)              | モデルが呼び出せる関数                 |
| [`skills/<skill-name>.md`](https://mastra.zisheng.pro/ja/reference/file-based-agents/skills)           | 関連する場合に Agent が読み込む詳細なガイダンス |
| [`memory.ts`](https://mastra.zisheng.pro/ja/reference/file-based-agents/memory)                        | 会話履歴と作業コンテキスト               |
| [`workspace.ts` and `workspace/`](https://mastra.zisheng.pro/ja/reference/file-based-agents/workspace) | ファイルシステムとシェルへのアクセス          |
| [`subagents/<agent-id>/`](https://mastra.zisheng.pro/ja/reference/file-based-agents/subagents)         | 親 Agent が委任できる専門 Agent      |

各機能は、それを使用する Agent の近くに配置します。Mastra は開発サーバーの起動時または再起動時に、これらのファイルを検出して登録します。

対応しているすべてのファイル規約と設定オプションについては、[ファイルベース Agent のリファレンス](https://mastra.zisheng.pro/ja/reference/file-based-agents/config)を参照してください。