본문으로 건너뛰기

Building a docs manager

이 가이드에서는 프로젝트 문서를 유지 관리하는 문서 관리자를 구축합니다. 이 관리자는 체계적인 마크다운 파일을 만들고, 실수로 덮어쓰는 일을 방지하면서 문서를 정리된 상태로 유지합니다. Workspace 파일 시스템을 설정하고 문서 관리 instructions가 포함된 Agent를 만듭니다. 그런 다음 대화형 Prompt를 사용하여 문서를 생성하고 업데이트합니다.

Prerequisites
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)

Set up the workspace
Set up the workspace에 대한 직접 링크

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

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: resolve(import.meta.dirname, '../../workspace'),
  }),
})

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

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

Add example documentation
Add example documentation에 대한 직접 링크

Inside the workspace directory, create the following folders:

  • docs/guides/: For how-to guides
  • docs/api/: For API reference documentation
  • docs/tutorials/: For step-by-step tutorials

Create workspace/docs/README.md as the documentation index:

workspace/docs/README.md
# Project Documentation

Welcome to the documentation!

## Sections

- [Guides](./guides/): How-to guides
- [API](./api/): API reference
- [Tutorials](./tutorials/): Step-by-step tutorials

Agent가 기존 문서 스타일을 확인할 수 있도록 샘플 가이드를 추가하세요:

workspace/docs/guides/getting-started.md
# Getting Started

Quickstart guide for the project.

## Installation

```bash npm2yarn
npm install example-package
```

## Quick example

```typescript
import { Example } from 'example-package'

const example = new Example()
example.run()
```

Create the docs manager
Create the docs manager에 대한 직접 링크

이제 문서 관리자 Agent를 만들 차례입니다. 이 Agent에는 Workspace에서 마크다운 파일을 생성하고 업데이트하기 위한 instructions가 포함됩니다. 다음 새 파일을 만드세요: src/mastra/agents/docs-manager.ts and define the agent:

src/mastra/agents/docs-manager.ts
import { Agent } from '@mastra/core/agent'

export const docsManager = new Agent({
  id: 'docs-manager',
  name: 'Docs Manager',
  instructions: `You are a documentation manager that creates and maintains markdown docs.

When creating new docs:
1. Ask for topic and target audience
2. Create well-structured markdown with clear sections
3. Include relevant code examples with syntax highlighting
4. Save in the appropriate directory:
   - /docs/guides/ for user guides and how-tos
   - /docs/api/ for API reference
   - /docs/tutorials/ for step-by-step tutorials

When updating existing docs:
1. ALWAYS read the file first
2. Make targeted updates without removing unrelated content
3. Preserve existing structure and formatting

Use kebab-case naming for files (getting-started.md).
Always explain what you're creating and why.`,
  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 } from '@mastra/core/workspace'
import { docsManager } from './agents/docs-manager'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: resolve(import.meta.dirname, '../../workspace'),
  }),
})

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

Test the docs manager
Test the docs manager에 대한 직접 링크

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

npm run dev

Open localhost:4111 and navigate to the docs manager.

Create a new document
Create a new document에 대한 직접 링크

Ask the agent to create a tutorial:

Create a tutorial for setting up authentication. Cover installation, configuration, and a basic example.

The agent should create a file like docs/tutorials/authentication-setup.md. Agent 응답은 비결정적이므로 정확한 내용은 달라지지만, 다음과 비슷한 결과를 확인할 수 있습니다:

# Authentication Setup

Learn how to add authentication to your application.

## Installation

Install the auth package:

```bash npm2yarn
npm install @example/auth
```

## Configuration

Create a config file:

```typescript
// auth.config.ts
export const authConfig = {
  provider: 'oauth',
  clientId: process.env.AUTH_CLIENT_ID,
  secret: process.env.AUTH_SECRET,
}
```

## Basic example

```typescript
import { createAuth } from '@example/auth'
import { authConfig } from './auth.config'

const auth = createAuth(authConfig)

app.get('/protected', auth.requireAuth(), (req, res) => {
  res.json({ user: req.user })
})
```

Update an existing document
Update an existing document에 대한 직접 링크

Try updating an existing document:

Update the getting started guide to include a section on configuration after the Quick Example

The agent should read the existing getting-started.md 파일을 열어 적절한 삽입 위치를 찾습니다. 기존 내용을 흐트러뜨리지 않고 새 섹션을 추가해야 합니다.

Organize documentation
Organize documentation에 대한 직접 링크

Ask the agent to create an index:

List all tutorial files and create an index page that links to all of them

The agent should create a file like /docs/tutorials/index.md that links to all available tutorials.

Next steps
Next steps에 대한 직접 링크

You can extend this manager to:

  • 관련 문서를 찾을 수 있도록 BM25 또는 벡터 검색 추가
  • Create skills for documentation templates
  • Build automated doc generation from source code
  • 커밋 시 문서를 업데이트하도록 GitHub와 통합
  • Add validation to check links and formatting
On this page