Créer un assistant de développement

Dans ce guide, vous créerez un assistant de développement complet qui combine toutes les fonctionnalités de Workspace :

• Système de fichiers pour la gestion des fichiers
• Sandbox pour l’exécution du code
• Skills pour les normes de programmation
• Recherche pour trouver des exemples

Vous configurerez un Workspace avec un projet d’exemple et ajouterez les normes de programmation sous la forme d’un Skill. Vous créerez ensuite un Agent qui écrit du code selon les pratiques TDD. À la fin, l’Agent pourra lire le code existant et écrire de nouvelles implémentations, puis exécuter les tests dans un Sandbox et itérer selon les résultats.

Prérequis

• Node.js v22.13.0 ou version ultérieure est installé
• Une clé API d’un fournisseur de modèles pris en charge
• Un projet Mastra existant (suivez le guide d’installation pour configurer un nouveau projet)

Installer Vitest

L’assistant de développement utilisera Vitest pour exécuter les tests dans le Sandbox du Workspace. Installez-le comme dépendance de développement dans votre projet :

npm

npm install -D vitest

pnpm

pnpm add -D vitest

Yarn

yarn add --dev vitest

Bun

bun add --dev vitest

Configurer le Workspace

Le Workspace utilise un système de fichiers local pour gérer les fichiers de documentation. L’Agent lit et écrit les fichiers dans le répertoire du Workspace. Dans votre fichier src/mastra/index.ts, importez les classes Workspace, LocalFilesystem et LocalSandbox.

Activez également l’indexation de recherche BM25 et chargez les Skills depuis le répertoire skills.

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,
})

À la racine de votre projet, créez un dossier nommé workspace. C’est là que tous les fichiers seront stockés et gérés par l’Agent.

Ajouter les fichiers d’exemple du projet

Le Workspace utilise la structure de dossiers suivante :

• workspace/src/ : code source du projet d’exemple
• workspace/tests/ : fichiers de test
• workspace/docs/ : documentation du projet
• workspace/skills/ : normes et directives de programmation sous forme d’Agent Skills

Commencez par créer un fichier workspace/src/utils/string-helpers.ts avec quelques fonctions utilitaires, ainsi qu’un fichier de test correspondant dans 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')
    })
  })
})

Créez une définition de Skill dans workspace/skills/coding-standards/SKILL.md. Elle indique à l’Agent comment écrire et tester le code :

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

Créez un fichier de référence dans workspace/skills/coding-standards/references/testing-guide.md avec des modèles de test détaillés :

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)

Créer l’assistant de développement

Une fois le Workspace configuré, il est temps de créer l’Agent assistant de développement. Cet Agent comportera des instructions pour ajouter de nouvelles fonctionnalités au moyen du développement piloté par les tests, ou TDD.

Créez un fichier src/mastra/agents/dev-assistant.ts et définissez l’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',
})

Définissez l’Agent en l’important dans src/mastra/index.ts et en l’enregistrant auprès de l’instance Mastra :

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 },
})

Tester l’assistant

Démarrez Studio et interagissez avec l’Agent pour le voir à l’œuvre.

npm

npm run dev

pnpm

pnpm run dev

Yarn

yarn dev

Bun

bun run dev

Ouvrez localhost:4111, puis accédez à l’assistant de développement.

Essayez de demander à l’Agent d’ajouter une nouvelle fonction avec 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.

Les réponses d’Agent étant non déterministes, la sortie exacte variera. Vous devriez néanmoins voir l’Agent suivre un processus semblable à celui-ci :

1. Activer le Skill coding-standards

2. Rechercher des modèles de code similaires dans le Workspace

3. Écrire les tests en premier, par exemple :

   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. Écrire l’implémentation, par exemple :

   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. Exécuter les tests et vérifier qu’ils réussissent

Étapes suivantes

Vous pouvez étendre cet assistant afin de :

• Ajouter davantage de Skills pour différents langages ou frameworks
• Créer des Agents spécialisés pour le backend, le frontend ou DevOps
• Intégrer GitHub pour automatiser les revues de PR
• Mettre en place une automatisation CI/CD
• Ajouter des Workflows multi-agents