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

시스템 프롬프트 이해하기

시스템 프롬프트는 대화 전반에 걸쳐 Claude가 어떻게 동작할지를 형성하는 초기 지시사항 세트입니다. 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: appendSystemPrompt 사용하기

appendSystemPrompt 옵션은 모든 내장 기능을 보존하면서 기본 시스템 프롬프트에 사용자 정의 지침을 추가합니다.
import { query } from "@anthropic-ai/claude-code"

const messages = []

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

방법 3: customSystemPrompt 사용하기

customSystemPrompt 옵션은 전체 기본 시스템 프롬프트를 사용자 정의 지침으로 교체합니다.
import { query } from "@anthropic-ai/claude-code"

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

const messages = []

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

세 가지 접근 방식 비교

기능출력 스타일appendSystemPromptcustomSystemPrompt
지속성✅ 파일로 저장됨❌ 세션만❌ 세션만
재사용성✅ 프로젝트 간❌ 코드 중복❌ 코드 중복
관리✅ CLI + 파일⚠️ 코드 내⚠️ 코드 내
기본 도구✅ 보존됨✅ 보존됨❌ 손실됨 (포함하지 않는 한)
내장 안전성✅ 유지됨✅ 유지됨❌ 추가해야 함
환경 컨텍스트✅ 자동✅ 자동❌ 제공해야 함
사용자 정의 수준⚠️ 기본값 교체⚠️ 추가만✅ 완전한 제어
버전 제어✅ 예✅ 코드와 함께✅ 코드와 함께
발견 가능성/output-style❌ 발견 불가능❌ 발견 불가능

사용 사례 및 모범 사례

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

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

appendSystemPrompt를 사용해야 하는 경우

다음에 적합:
  • 특정 코딩 표준이나 선호도 추가
  • 출력 형식 사용자 정의
  • 도메인별 지식 추가
  • 응답 상세도 수정

customSystemPrompt를 사용해야 하는 경우

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

접근 방식 결합하기

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

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

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

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

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

참고 자료