프로젝트 구조

이 페이지는 Mastra에서 폴더와 파일을 구성하는 방법에 대한 가이드를 제공합니다. Mastra는 모듈형 프레임워크이므로, 모든 모듈을 함께 사용하거나 개별적으로 사용할 수 있습니다.

모든 것을 단일 파일에 작성하거나, 각 에이전트(Agent), 도구(Tool), 워크플로우(Workflow)를 개별 파일로 분리할 수 있습니다.

특정 폴더 구조를 강제하지는 않지만, 몇 가지 모범 사례를 권장하며, CLI는 합리적인 구조로 프로젝트를 스캐폴딩합니다.

예시 프로젝트 구조

CLI로 생성한 기본 프로젝트는 다음과 같습니다:

Copysrc/
├── mastra/
│   ├── agents/
│   │   └── agent-name.ts
│   ├── tools/
│   │   └── tool-name.ts
│   ├── workflows/
│   │   └── workflow-name.ts
│   └── index.ts
├── .env
├── package.json
└── tsconfig.json

최상위 폴더

최상위 파일

폴더별 상세 설명

/src/mastra/agents/

에이전트(Agent) 관련 파일들을 저장하는 폴더입니다.

권장 구조:

Copyagents/
├── weather-agent.ts        # 날씨 관련 에이전트
├── customer-support.ts     # 고객 지원 에이전트
└── index.ts                # 에이전트 내보내기 (선택사항)

예제 파일 (weather-agent.ts):

Copyimport { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

export const weatherAgent = new Agent({
  name: "날씨 에이전트",
  instructions: "날씨 정보를 제공하는 도우미입니다.",
  model: openai("gpt-4o-mini"),
});

/src/mastra/tools/

커스텀 도구(Tool) 정의를 저장하는 폴더입니다.

권장 구조:

Copytools/
├── weather-api.ts         # 날씨 API 도구
├── database-query.ts      # 데이터베이스 쿼리 도구
├── email-sender.ts        # 이메일 발송 도구
└── index.ts               # 도구 내보내기 (선택사항)

예제 파일 (weather-api.ts):

Copyimport { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "특정 도시의 날씨 정보를 가져옵니다",
  inputSchema: z.object({
    city: z.string().describe("도시 이름"),
  }),
  execute: async ({ context }) => {
    // 실제 날씨 API 호출 로직
    return { weather: "맑음", temperature: "22°C" };
  },
});

/src/mastra/workflows/

워크플로우(Workflow) 정의를 저장하는 폴더입니다.

권장 구조:

Copyworkflows/
├── user-onboarding.ts     # 사용자 온보딩 워크플로우
├── data-processing.ts     # 데이터 처리 워크플로우
├── content-generation.ts  # 콘텐츠 생성 워크플로우
└── index.ts               # 워크플로우 내보내기 (선택사항)

예제 파일 (user-onboarding.ts):

Copyimport { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const welcomeStep = createStep({
  id: "send-welcome-email",
  // 스텝 정의...
});

export const userOnboardingWorkflow = createWorkflow({
  id: "user-onboarding",
  description: "신규 사용자 온보딩 프로세스",
  inputSchema: z.object({
    userId: z.string(),
  }),
})
  .then(welcomeStep)
  .commit();

/src/mastra/index.ts

모든 Mastra 컴포넌트를 등록하는 메인 파일입니다.

Copyimport { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent";
import { weatherTool } from "./tools/weather-api";
import { userOnboardingWorkflow } from "./workflows/user-onboarding";

export const mastra = new Mastra({
  agents: { 
    weatherAgent 
  },
  tools: { 
    weatherTool 
  },
  workflows: { 
    userOnboardingWorkflow 
  },
});

모범 사례

1. 파일 명명 규칙

• 케밥 케이스 사용: weather-agent.ts, user-onboarding.ts

• 목적을 명확히: email-sender.ts, database-query.ts

• 일관성 유지: 프로젝트 전체에서 동일한 명명 규칙 적용

2. 폴더 구조 확장

대규모 프로젝트의 경우 하위 폴더를 만들어 더 세분화할 수 있습니다:

Copysrc/mastra/
├── agents/
│   ├── customer-service/
│   │   ├── support-agent.ts
│   │   └── billing-agent.ts
│   └── content/
│       ├── writer-agent.ts
│       └── editor-agent.ts
├── tools/
│   ├── apis/
│   │   ├── weather-api.ts
│   │   └── payment-api.ts
│   └── utilities/
│       ├── text-processor.ts
│       └── file-handler.ts
└── workflows/
    ├── user-management/
    └── content-pipeline/

3. 내보내기 패턴

각 폴더에 index.ts 파일을 만들어 깔끔한 가져오기를 지원할 수 있습니다:

Copy// src/mastra/agents/index.ts
export { weatherAgent } from "./weather-agent";
export { supportAgent } from "./support-agent";

// src/mastra/index.ts에서 사용
import { weatherAgent, supportAgent } from "./agents";

4. 타입 정의

공통(Common) 타입이나 인터페이스(Interface)는 별도 파일로 관리하세요:

Copysrc/mastra/
├── types/
│   ├── weather.ts
│   ├── user.ts
│   └── common.ts
├── agents/
├── tools/
└── workflows/

환경별 설정

개발 환경

Copy.env.development

프로덕션 환경

Copy.env.production

테스트 환경

Copy.env.test

추가 고려사항

1. 버전 관리

• .env 파일은 .gitignore에 포함

• .env.example 파일로 필요한 환경 변수 문서화

2. 문서화

각 주요 컴포넌트에 대한 README 파일 작성을 고려하세요:

Copysrc/mastra/
├── agents/README.md
├── tools/README.md
└── workflows/README.md

3. 테스트 구조

Copytests/
├── agents/
├── tools/
└── workflows/

이 구조를 따르면 Mastra 프로젝트를 체계적이고 확장 가능하게 관리할 수 있습니다. 프로젝트 규모와 팀의 요구사항에 따라 구조를 조정하세요.

---

2025년 7월 26일 기준 번역
by dongne.lab@gmail.com