> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 지침

Agent의 지시 사항에는 항상 켜져 있는 시스템 Prompt가 포함되어 있습니다. Model은 매 턴마다 이를 읽습니다. 이를 사용하여 Agent의 신원, 어조, 역할 및 입장 규칙을 정의합니다.

Agent 루트에 있는 두 파일 중 하나에 지침을 작성합니다. Prompt가 고정 텍스트이면 `instructions.md`를 사용하세요. 공유 상수로 빌드하거나 요청에 따라 결정하는 등 Prompt에 코드가 필요하면 `instructions.ts`를 사용하세요. 지침은 항상 컨텍스트에 포함되므로 모든 요청에 적용되는 안정적인 동작만 담으세요. 조건부이거나 규모가 크거나 작업 중심인 항목은 [`tools/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools) 또는 [`skills/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/skills)로 옮기세요. Model은 관련이 있을 때만 이를 사용합니다.

## 빠른 시작

Agent 루트에 `instructions.md`를 추가하세요. 작성한 내용이 그대로 Prompt가 되므로 가장 짧은 형태는 한 문장입니다.

```markdown
You are a helpful weather assistant. Answer questions about current conditions and forecasts.
```

## 지침에 들어가는 내용

효과적인 지침은 요청 간에 변경되지 않는 Agent 동작의 일부를 다룹니다.

- 역할과 정체성
- 톤과 스타일
- 상임 규칙
- 출력 형식

조건부이거나 규모가 크거나 작업 중심인 지침은 [`tools/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools) 또는 [`skills/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/skills)로 옮기세요. Model은 관련이 있을 때만 이를 사용합니다.

## TypeScript의 지침

Markdown으로 Prompt를 표현할 수 없으면 `instructions.ts`를 사용하세요. 이 파일은 문자열, 시스템 메시지 또는 이를 반환하는 함수를 기본 내보내기하며, `agentInstructions()`는 내보내기를 변경하지 않고 타입을 지정합니다. 예를 들어 앱의 나머지 부분과 공유되는 상수에서 Prompt가 코드로 조합되면 문자열을 내보냅니다.

```typescript
import { agentInstructions } from '@mastra/core/agent'
import { SUPPORTED_UNITS } from '../../constants'

export default agentInstructions(`
You are a helpful weather assistant.
Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
`)
```

Prompt가 요청에 따라 달라지면 함수를 내보냅니다. Mastra는 매 턴마다 이를 호출하고 요청 컨텍스트를 전달합니다.

```typescript
import { agentInstructions } from '@mastra/core/agent'

export default agentInstructions(({ requestContext }) => {
  const tier = requestContext.get('tier') ?? 'standard'
  return `You are a support agent. Treat this as a ${tier}-tier customer.`
})
```

함수는 `async`일 수 있으며 `requestContext`와 함께 `mastra`를 받으므로, Prompt를 반환하기 전에 스토리지나 등록된 다른 프리미티브에서 데이터를 읽을 수 있습니다. 두 파일 모두 동일한 규칙을 따르는 [하위 Agent](https://mastra.zisheng.pro/ko/reference/file-based-agents/subagents) 디렉터리에서도 작동합니다.

## 빌드 타임 동작

`instructions.md`와 `instructions.ts`는 서로 다른 방식으로 배포된 Agent에 반영됩니다.

- `instructions.md`: Mastra는 파일을 읽고 빌드 시 생성된 코드에 해당 내용을 인라인합니다.
- `instructions.ts`: 생성된 코드는 모듈을 가져오므로 다른 TypeScript 파일처럼 번들로 제공되며 프로젝트의 나머지 부분에서 가져올 수 있습니다.

`mastra dev`에서는 두 파일 중 하나를 편집하면 다시 빌드됩니다. 배포된 앱에서는 런타임에 어느 파일도 디스크에서 읽지 않으므로 변경 사항은 다음 빌드 후 적용됩니다.

## 구성 우선순위

지침은 `instructions.ts`, `instructions.md` 또는 [`config.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/config)의 `instructions` 필드에서 가져올 수 있습니다.

- `config.ts`에서 런타임에 정의한 함수형 `instructions`가 두 파일보다 우선합니다.
- 그렇지 않으면 `instructions.ts`가 `instructions.md`보다 우선합니다.
- `instructions.md`가 `config.ts`의 정적 `instructions` 문자열보다 우선합니다.
- 아무것도 없으면 Agent 디렉터리 이름을 명시한 오류와 함께 빌드가 실패합니다. 여러 곳에서 지침을 정의하면 두 소스의 이름과 어느 소스가 승리하는지에 대한 경고가 기록됩니다. Agent당 하나의 소스를 유지하세요.