시스템 프롬프트는 Claude의 동작, 기능 및 응답 스타일을 정의합니다. Claude Agent SDK는 시스템 프롬프트를 사용자 정의하는 세 가지 방법을 제공합니다: 출력 스타일(지속적이고 파일 기반 구성) 사용, Claude Code의 프롬프트에 추가, 또는 완전히 사용자 정의된 프롬프트 사용.

시스템 프롬프트 이해하기

시스템 프롬프트는 대화 전반에 걸쳐 Claude가 어떻게 동작할지를 형성하는 초기 명령어 세트입니다.
기본 동작: Agent SDK는 최대한의 유연성을 위해 기본적으로 빈 시스템 프롬프트를 사용합니다. Claude Code의 시스템 프롬프트(도구 지침, 코드 가이드라인 등)를 사용하려면 TypeScript에서 systemPrompt: { preset: "claude_code" }를 지정하거나 Python에서 system_prompt="claude_code"를 지정하세요.
Claude Code의 시스템 프롬프트에는 다음이 포함됩니다:
  • 도구 사용 지침 및 사용 가능한 도구
  • 코드 스타일 및 형식 가이드라인
  • 응답 톤 및 상세도 설정
  • 보안 및 안전 지침
  • 현재 작업 디렉토리 및 환경에 대한 컨텍스트

수정 방법

방법 1: 출력 스타일 (지속적 구성)

출력 스타일은 Claude의 시스템 프롬프트를 수정하는 저장된 구성입니다. 마크다운 파일로 저장되며 세션과 프로젝트 간에 재사용할 수 있습니다.

출력 스타일 생성하기

import { writeFile, mkdir } from 'fs/promises'
import { join } from 'path'
import { homedir } from 'os'

async function createOutputStyle(name: string, description: string, prompt: string) {
  // 사용자 수준: ~/.claude/output-styles
  // 프로젝트 수준: .claude/output-styles
  const outputStylesDir = join(homedir(), '.claude', 'output-styles')
  
  await mkdir(outputStylesDir, { recursive: true })
  
  const content = `---
name: ${name}
description: ${description}
---

${prompt}`
  
  const filePath = join(outputStylesDir, `${name.toLowerCase().replace(/\s+/g, '-')}.md`)
  await writeFile(filePath, content, 'utf-8')
}

// 예시: 코드 리뷰 전문가 생성
await createOutputStyle(
  'Code Reviewer',
  'Thorough code review assistant',
  `You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)`
)

출력 스타일 사용하기

생성된 후, 다음을 통해 출력 스타일을 활성화할 수 있습니다:
  • CLI: /output-style [style-name]
  • 설정: .claude/settings.local.json
  • 새로 생성: /output-style:new [description]

방법 2: append와 함께 systemPrompt 사용하기

모든 내장 기능을 보존하면서 사용자 정의 지침을 추가하기 위해 append 속성과 함께 Claude Code 프리셋을 사용할 수 있습니다.
import { query } from "@anthropic-ai/claude-agent-sdk"

const messages = []

for await (const message of query({
  prompt: "피보나치 수를 계산하는 Python 함수를 작성하는 데 도움을 주세요",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Python 코드에는 항상 상세한 docstring과 타입 힌트를 포함하세요."
    }
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

방법 3: 사용자 정의 시스템 프롬프트

systemPrompt에 사용자 정의 문자열을 제공하여 기본값을 완전히 자신만의 지침으로 대체할 수 있습니다.
import { query } from "@anthropic-ai/claude-agent-sdk"

const customPrompt = `당신은 Python 코딩 전문가입니다.
다음 가이드라인을 따르세요:
- 깔끔하고 잘 문서화된 코드를 작성하세요
- 모든 함수에 타입 힌트를 사용하세요
- 포괄적인 docstring을 포함하세요
- 적절한 경우 함수형 프로그래밍 패턴을 선호하세요
- 항상 코드 선택에 대해 설명하세요`

const messages = []

for await (const message of query({
  prompt: "데이터 처리 파이프라인을 생성하세요",
  options: {
    systemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

세 가지 접근 방식 모두 비교

기능출력 스타일append와 함께 systemPrompt사용자 정의 systemPrompt
지속성✅ 파일로 저장됨❌ 세션만❌ 세션만
재사용성✅ 프로젝트 간❌ 코드 중복❌ 코드 중복
관리✅ CLI + 파일⚠️ 코드 내⚠️ 코드 내
기본 도구✅ 보존됨✅ 보존됨❌ 손실됨 (포함하지 않는 한)
내장 안전성✅ 유지됨✅ 유지됨❌ 추가해야 함
환경 컨텍스트✅ 자동✅ 자동❌ 제공해야 함
사용자 정의 수준⚠️ 기본값 대체⚠️ 추가만✅ 완전한 제어
버전 제어✅ 예✅ 코드와 함께✅ 코드와 함께
발견 가능성/output-style❌ 발견할 수 없음❌ 발견할 수 없음
참고: “append와 함께”는 TypeScript에서 systemPrompt: { type: "preset", preset: "claude_code", append: "..." }를 사용하거나 Python에서 system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}를 사용하는 것을 의미합니다.

사용 사례 및 모범 사례

출력 스타일을 사용해야 하는 경우

최적 용도:
  • 세션 간 지속적인 동작 변경
  • 팀 공유 구성
  • 전문 어시스턴트 (코드 리뷰어, 데이터 사이언티스트, DevOps)
  • 버전 관리가 필요한 복잡한 프롬프트 수정
예시:
  • 전용 SQL 최적화 어시스턴트 생성
  • 보안 중심 코드 리뷰어 구축
  • 특정 교육법을 가진 교육 어시스턴트 개발

append와 함께 systemPrompt를 사용해야 하는 경우

최적 용도:
  • 특정 코딩 표준이나 선호도 추가
  • 출력 형식 사용자 정의
  • 도메인별 지식 추가
  • 응답 상세도 수정
  • 도구 지침을 잃지 않고 Claude Code의 기본 동작 향상

사용자 정의 systemPrompt를 사용해야 하는 경우

최적 용도:
  • Claude의 동작에 대한 완전한 제어
  • 전문화된 단일 세션 작업
  • 새로운 프롬프트 전략 테스트
  • 기본 도구가 필요하지 않은 상황
  • 고유한 동작을 가진 전문 에이전트 구축

접근 방식 결합하기

최대한의 유연성을 위해 이러한 방법들을 결합할 수 있습니다:

예시: 세션별 추가 사항이 있는 출력 스타일

import { query } from "@anthropic-ai/claude-agent-sdk"

// "Code Reviewer" 출력 스타일이 활성화되어 있다고 가정 (/output-style을 통해)
// 세션별 중점 영역 추가
const messages = []

for await (const message of query({
  prompt: "이 인증 모듈을 리뷰해주세요",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        이 리뷰에서는 다음을 우선시하세요:
        - OAuth 2.0 준수
        - 토큰 저장 보안
        - 세션 관리
      `
    }
  }
})) {
  messages.push(message)
}

참고 자료