프로젝트 구조

새로운 Mastra 프로젝트는create mastra명령에는 시작하는 데 도움이 되는 미리 정의된 파일 및 폴더 세트가 함께 제공됩니다.

Mastra는 프레임워크이지만 파일을 구성하거나 같은 위치에 배치하는 방식에 대해서는 대부분 특정 방식을 강제하지 않습니다. CLI는 대부분의 프로젝트에 적합한 합리적인 기본 구조를 제공하지만, Workflow나 팀 규칙에 맞게 자유롭게 조정할 수 있습니다. 원한다면 전체 프로젝트를 단일 파일로 구성할 수도 있습니다! 어떤 구조를 선택하든 일관성을 유지하여 코드를 쉽게 유지보수하고 탐색할 수 있도록 하세요.

기본 프로젝트 구조

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 성능을 평가하기 위한 채점기를 정의합니다
Mastra에는 두 가지 특별한 폴더 규칙이 있습니다.

• src/mastra/agents/<name>: 코드로 구성하는 대신 파일 규칙을 사용하여 Agent를 정의할 수 있습니다. 자세한 내용은 파일 기반 Agent 문서를 참조하세요.
• src/mastra/public: 빌드 과정에서 콘텐츠가 .build/output 디렉터리로 복사되어 런타임에 제공할 수 있게 됩니다.

최상위 파일

최상위 파일은 Mastra 프로젝트가 구성, 구축 및 환경에 연결되는 방법을 정의합니다.

파일	설명
src/mastra/index.ts	Mastra를 구성하고 초기화하는 중앙 진입점입니다.
.env.example	환경 변수 템플릿입니다. 복사한 후 .env로 이름을 변경하여 비밀 Model Provider 키를 추가하세요.
package.json	프로젝트 메타데이터, 종속성, 사용 가능한 npm 스크립트를 정의합니다.
tsconfig.json	경로 별칭, 컴파일러 설정, 빌드 출력 등의 TypeScript 옵션을 구성합니다.