Building a dev assistant

이 가이드에서는 모든 Workspace 기능을 결합한 완전한 개발 도우미를 구축합니다:

• Filesystem for file management
• Sandbox for code execution
• Skills for coding standards
• Search for finding examples

샘플 프로젝트가 포함된 Workspace를 설정하고 코딩 표준을 Skill로 추가합니다. 그런 다음 TDD 방식을 따르며 코드를 작성하는 Agent를 만듭니다. 이 과정을 마치면 Agent가 기존 코드를 읽고 새로운 구현을 작성한 다음, Sandbox에서 테스트를 실행하고 결과에 따라 반복적으로 개선할 수 있습니다.

Prerequisites

• Node.js v22.13.0 or later installed
• An API key from a supported Model Provider
• An existing Mastra project (Follow the installation guide to set up a new project)

Install vitest

The dev assistant will use Vitest 을 사용하여 Workspace Sandbox 내에서 테스트를 실행합니다. 프로젝트의 개발 의존성으로 설치하세요:

npm

npm install -D vitest

pnpm

pnpm add -D vitest

Yarn

yarn add --dev vitest

Bun

bun add --dev vitest

Set up the workspace

Workspace는 로컬 파일 시스템을 사용하여 문서 파일을 관리합니다. Agent는 Workspace 디렉터리 내의 파일을 읽고 씁니다. src/mastra/index.ts file, import the Workspace, LocalFilesystem, and LocalSandbox classes.

또한 BM25 검색 인덱싱을 활성화하고 다음 위치에서 Skill을 불러오세요: skills directory.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
  skills: ['skills'],
  bm25: true,
  autoIndexPaths: ['docs', 'src'],
})

export const mastra = new Mastra({
  workspace,
})

프로젝트 루트에 다음 이름의 새 폴더를 만드세요: workspace. 모든 파일은 이 위치에 저장되며 Agent가 관리합니다.

Add sample project files

The workspace uses the following folder structure:

• workspace/src/: Source code for the sample project
• workspace/tests/: Test files
• workspace/docs/: Project documentation
• workspace/skills/: Coding standards and guidelines as Agent Skills

Get started by creating a workspace/src/utils/string-helpers.ts 유틸리티 함수가 포함된 파일과 그에 대응하는 테스트 파일을 다음 위치에 만드세요: workspace/tests/string-helpers.test.ts.

workspace/src/utils/string-helpers.ts

export function capitalize(str: string): string {
  if (!str) return str
  return str.charAt(0).toUpperCase() + str.slice(1)
}

export function slugify(str: string): string {
  return str
    .toLowerCase()
    .replace(/[^\w\s-]/g, '')
    .replace(/\s+/g, '-')
}

workspace/tests/string-helpers.test.ts

import { describe, it, expect } from 'vitest'
import { capitalize, slugify } from '../src/utils/string-helpers'

describe('String Helpers', () => {
  describe('capitalize', () => {
    it('capitalizes first letter', () => {
      expect(capitalize('hello')).toBe('Hello')
    })
  })

  describe('slugify', () => {
    it('converts to lowercase and replaces spaces', () => {
      expect(slugify('Hello World')).toBe('hello-world')
    })
  })
})

Create a skill definition at workspace/skills/coding-standards/SKILL.md. 이는 Agent에게 코드를 작성하고 테스트하는 방법을 알려 줍니다:

workspace/skills/coding-standards/SKILL.md

---
name: coding-standards
description: Project coding standards and testing guidelines
---

# Coding Standards

## Code quality

- Functions under 50 lines
- Use descriptive variable names
- Always add TypeScript types

## Testing

- Test all exported functions
- Use AAA pattern: Arrange, Act, Assert
- Cover happy paths and edge cases

## Before committing

1. Write implementation
2. Write comprehensive tests
3. Run tests: `npm test`
4. All tests must pass

Create a reference file at workspace/skills/coding-standards/references/testing-guide.md with detailed testing patterns:

workspace/skills/coding-standards/references/testing-guide.md

# Testing Guide

## AAA pattern

```typescript
it('descriptive test name', () => {
  // Arrange: Set up test data
  const input = 'test'

  // Act: Execute the function
  const result = doSomething(input)

  // Assert: Verify the result
  expect(result).toBe('expected')
})
```

## What to test

- Happy paths (normal inputs)
- Edge cases (empty, null, boundary values)
- Error cases (invalid inputs, exceptions)

Create the dev assistant

Workspace 설정을 마쳤으므로 이제 개발 도우미 Agent를 만들 차례입니다. 이 Agent에는 테스트 주도 개발(TDD)을 사용하여 새로운 기능을 추가하기 위한 instructions가 포함됩니다.

Create a new file src/mastra/agents/dev-assistant.ts and define the agent:

src/mastra/agents/dev-assistant.ts

import { Agent } from '@mastra/core/agent'

export const devAssistant = new Agent({
  id: 'dev-assistant',
  name: 'Dev Assistant',
  instructions: `You are a development assistant.

When adding features:
1. Activate 'coding-standards' skill
2. Search workspace for similar code examples
3. Write the implementation following standards
4. Write comprehensive tests. Leave existing tests in place, only add your new tests
5. Execute the command \`npx vitest run\` to validate that all tests pass
6. Update documentation if needed

For every new feature: Write code → Write tests → Run tests → Update docs

Always explain your reasoning and steps.`,
  model: 'openai/gpt-5.6-sol',
})

Define the agent by importing it inside src/mastra/index.ts and registering it with the Mastra instance:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
import { devAssistant } from './agents/dev-assistant'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
  skills: ['skills'],
  bm25: true,
  autoIndexPaths: ['docs', 'src'],
})

export const mastra = new Mastra({
  workspace,
  agents: { devAssistant },
})

Test the assistant

Start Studio 을 실행하고 Agent와 상호작용하여 실제 작동 모습을 확인하세요.

npm

npm run dev

pnpm

pnpm run dev

Yarn

yarn dev

Bun

bun run dev

Open localhost:4111 and navigate to the dev assistant.

Agent에게 TDD를 사용하여 새 함수를 추가해 달라고 요청해 보세요:

Add a 'truncate' function to string-helpers.ts that shortens strings to a max length. Add '...' if truncated.

Follow TDD: write tests first, then implementation.

Agent 응답은 비결정적이므로 정확한 출력은 달라집니다. 하지만 Agent가 다음과 비슷한 프로세스를 따르는 것을 확인할 수 있습니다:

1. Activate the coding-standards skill

2. Search the workspace for similar code patterns

3. Write tests first, for example:

   describe('truncate', () => {
     it('truncates long strings', () => {
       expect(truncate('Hello World', 5)).toBe('He...')
     })
   
     it('keeps short strings unchanged', () => {
       expect(truncate('Hi', 10)).toBe('Hi')
     })
   
     it('handles edge cases', () => {
       expect(truncate('', 5)).toBe('')
     })
   })

4. Write the implementation, for example:

   export function truncate(str: string, maxLength: number): string {
     if (!str || maxLength < 0) return str
     if (str.length <= maxLength) return str
     if (maxLength === 0) return '...'
     return str.slice(0, maxLength - 3) + '...'
   }

5. Run tests and verify they pass

Next steps

You can extend this assistant to:

• 다양한 언어나 프레임워크를 위한 Skill 추가
• 백엔드, 프런트엔드 또는 DevOps용 전문 Agent 생성
• Integrate with GitHub for automated PR reviews
• Build CI/CD automation
• Add multi-agent workflows