가이드

시스템 프롬프트 수정

출력 스타일, append를 사용한 systemPrompt, 커스텀 시스템 프롬프트의 세 가지 접근 방식을 사용하여 Claude의 동작을 커스터마이즈하는 방법을 알아보세요.

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

시스템 프롬프트 이해하기

시스템 프롬프트는 대화 전반에 걸쳐 Claude의 동작 방식을 형성하는 초기 지시 세트입니다.

기본 동작: Agent SDK는 기본적으로 최소한의 시스템 프롬프트를 사용합니다. 필수 도구 지시사항만 포함하며 Claude Code의 코딩 가이드라인, 응답 스타일, 프로젝트 컨텍스트는 생략됩니다. 전체 Claude Code 시스템 프롬프트를 포함하려면 TypeScript에서 systemPrompt: { preset: "claude_code" }를, Python에서 system_prompt={"type": "preset", "preset": "claude_code"}를 지정하세요.

Claude Code의 시스템 프롬프트에는 다음이 포함됩니다:

도구 사용 지시사항 및 사용 가능한 도구
코드 스타일 및 포맷팅 가이드라인
응답 톤 및 상세도 설정
보안 및 안전 지시사항
현재 작업 디렉토리 및 환경에 대한 컨텍스트

수정 방법

방법 1: CLAUDE.md 파일 (프로젝트 수준 지시사항)

CLAUDE.md 파일은 Agent SDK가 디렉토리에서 실행될 때 자동으로 읽히는 프로젝트별 컨텍스트와 지시사항을 제공합니다. 프로젝트의 영구적인 "메모리" 역할을 합니다.

CLAUDE.md가 SDK와 작동하는 방식

위치 및 검색:

프로젝트 수준: 작업 디렉토리의 CLAUDE.md 또는 .claude/CLAUDE.md
사용자 수준: 모든 프로젝트에 걸친 전역 지시사항을 위한 ~/.claude/CLAUDE.md

중요: SDK는 settingSources(TypeScript) 또는 setting_sources(Python)를 명시적으로 구성할 때만 CLAUDE.md 파일을 읽습니다:

프로젝트 수준 CLAUDE.md를 로드하려면 'project'를 포함하세요
사용자 수준 CLAUDE.md(~/.claude/CLAUDE.md)를 로드하려면 'user'를 포함하세요

claude_code 시스템 프롬프트 프리셋은 CLAUDE.md를 자동으로 로드하지 않습니다 - 설정 소스도 반드시 지정해야 합니다.

콘텐츠 형식: CLAUDE.md 파일은 일반 마크다운을 사용하며 다음을 포함할 수 있습니다:

코딩 가이드라인 및 표준
프로젝트별 컨텍스트
일반적인 명령어 또는 워크플로우
API 규칙
테스트 요구사항

CLAUDE.md 예시

# Project Guidelines

## Code Style

- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs

## Testing

- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E

## Commands

- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`

SDK에서 CLAUDE.md 사용하기

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

// 중요: CLAUDE.md를 로드하려면 settingSources를 지정해야 합니다
// claude_code 프리셋만으로는 CLAUDE.md 파일을 로드하지 않습니다
const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Claude Code의 시스템 프롬프트 사용
    },
    settingSources: ["project"], // 프로젝트에서 CLAUDE.md를 로드하는 데 필요
  },
})) {
  messages.push(message);
}

// 이제 Claude가 CLAUDE.md의 프로젝트 가이드라인에 접근할 수 있습니다

CLAUDE.md를 사용해야 하는 경우

적합한 용도:

팀 공유 컨텍스트 - 모든 사람이 따라야 하는 가이드라인
프로젝트 규칙 - 코딩 표준, 파일 구조, 네이밍 패턴
일반적인 명령어 - 프로젝트에 특화된 빌드, 테스트, 배포 명령어
장기 메모리 - 모든 세션에 걸쳐 유지되어야 하는 컨텍스트
버전 관리되는 지시사항 - git에 커밋하여 팀이 동기화 상태를 유지

주요 특성:

✅ 프로젝트 내 모든 세션에서 영구적
✅ git을 통해 팀과 공유
✅ 자동 검색 (코드 변경 불필요)
⚠️ settingSources를 통한 설정 로드 필요

방법 2: 출력 스타일 (영구적 구성)

출력 스타일은 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]

SDK 사용자 참고: 출력 스타일은 옵션에 settingSources: ['user'] 또는 settingSources: ['project'](TypeScript) / setting_sources=["user"] 또는 setting_sources=["project"](Python)를 포함할 때 로드됩니다.

방법 3: append와 함께 `systemPrompt` 사용

Claude Code 프리셋에 append 속성을 사용하여 모든 내장 기능을 유지하면서 커스텀 지시사항을 추가할 수 있습니다.

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

const messages = [];

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Always include detailed docstrings and type hints in Python code.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

방법 4: 커스텀 시스템 프롬프트

커스텀 문자열을 systemPrompt로 제공하여 기본값을 완전히 자신의 지시사항으로 대체할 수 있습니다.

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

네 가지 접근 방식 비교

기능	CLAUDE.md	출력 스타일	append를 사용한 `systemPrompt`	커스텀 `systemPrompt`
영속성	프로젝트별 파일	파일로 저장	세션 한정	세션 한정
재사용성	프로젝트별	프로젝트 간	코드 중복	코드 중복
관리	파일 시스템에서	CLI + 파일	코드 내	코드 내
기본 도구	유지	유지	유지	손실 (포함하지 않는 한)
내장 안전성	유지	유지	유지	직접 추가 필요
환경 컨텍스트	자동	자동	자동	직접 제공 필요
커스터마이즈 수준	추가만	기본값 대체	추가만	완전한 제어
버전 관리	프로젝트와 함께	가능	코드와 함께	코드와 함께
범위	프로젝트 한정	사용자 또는 프로젝트	코드 세션	코드 세션

참고: "append 사용"은 TypeScript에서 systemPrompt: { type: "preset", preset: "claude_code", append: "..." }를, Python에서 system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}를 사용하는 것을 의미합니다.

사용 사례 및 모범 사례

CLAUDE.md를 사용해야 하는 경우

적합한 용도:

프로젝트별 코딩 표준 및 규칙
프로젝트 구조 및 아키텍처 문서화
일반적인 명령어 나열 (빌드, 테스트, 배포)
버전 관리되어야 하는 팀 공유 컨텍스트
프로젝트의 모든 SDK 사용에 적용되는 지시사항

예시:

"모든 API 엔드포인트는 async/await 패턴을 사용해야 합니다"
"커밋 전에 npm run lint:fix를 실행하세요"
"데이터베이스 마이그레이션은 migrations/ 디렉토리에 있습니다"

중요: CLAUDE.md 파일을 로드하려면 settingSources: ['project'](TypeScript) 또는 setting_sources=["project"](Python)를 명시적으로 설정해야 합니다. claude_code 시스템 프롬프트 프리셋은 이 설정 없이는 CLAUDE.md를 자동으로 로드하지 않습니다.

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

적합한 용도:

세션 간 영구적인 동작 변경
팀 공유 구성
전문화된 어시스턴트 (코드 리뷰어, 데이터 과학자, 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: "Review this authentication module",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        For this review, prioritize:
        - OAuth 2.0 compliance
        - Token storage security
        - Session management
      `,
    },
  },
})) {
  messages.push(message);
}

참고 자료

출력 스타일 - 전체 출력 스타일 문서
TypeScript SDK 가이드 - 전체 SDK 사용 가이드
구성 가이드 - 일반 구성 옵션

Was this page helpful?

가이드

시스템 프롬프트 수정

출력 스타일, append를 사용한 systemPrompt, 커스텀 시스템 프롬프트의 세 가지 접근 방식을 사용하여 Claude의 동작을 커스터마이즈하는 방법을 알아보세요.

시스템 프롬프트 이해하기

시스템 프롬프트는 대화 전반에 걸쳐 Claude의 동작 방식을 형성하는 초기 지시 세트입니다.

Claude Code의 시스템 프롬프트에는 다음이 포함됩니다:

도구 사용 지시사항 및 사용 가능한 도구
코드 스타일 및 포맷팅 가이드라인
응답 톤 및 상세도 설정
보안 및 안전 지시사항
현재 작업 디렉토리 및 환경에 대한 컨텍스트

수정 방법

방법 1: CLAUDE.md 파일 (프로젝트 수준 지시사항)

CLAUDE.md가 SDK와 작동하는 방식

위치 및 검색:

프로젝트 수준: 작업 디렉토리의 CLAUDE.md 또는 .claude/CLAUDE.md
사용자 수준: 모든 프로젝트에 걸친 전역 지시사항을 위한 ~/.claude/CLAUDE.md

중요: SDK는 settingSources(TypeScript) 또는 setting_sources(Python)를 명시적으로 구성할 때만 CLAUDE.md 파일을 읽습니다:

프로젝트 수준 CLAUDE.md를 로드하려면 'project'를 포함하세요
사용자 수준 CLAUDE.md(~/.claude/CLAUDE.md)를 로드하려면 'user'를 포함하세요

claude_code 시스템 프롬프트 프리셋은 CLAUDE.md를 자동으로 로드하지 않습니다 - 설정 소스도 반드시 지정해야 합니다.

콘텐츠 형식: CLAUDE.md 파일은 일반 마크다운을 사용하며 다음을 포함할 수 있습니다:

코딩 가이드라인 및 표준
프로젝트별 컨텍스트
일반적인 명령어 또는 워크플로우
API 규칙
테스트 요구사항

CLAUDE.md 예시

# Project Guidelines

## Code Style

- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs

## Testing

- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E

## Commands

- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`

SDK에서 CLAUDE.md 사용하기

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

// 중요: CLAUDE.md를 로드하려면 settingSources를 지정해야 합니다
// claude_code 프리셋만으로는 CLAUDE.md 파일을 로드하지 않습니다
const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Claude Code의 시스템 프롬프트 사용
    },
    settingSources: ["project"], // 프로젝트에서 CLAUDE.md를 로드하는 데 필요
  },
})) {
  messages.push(message);
}

// 이제 Claude가 CLAUDE.md의 프로젝트 가이드라인에 접근할 수 있습니다

CLAUDE.md를 사용해야 하는 경우

적합한 용도:

팀 공유 컨텍스트 - 모든 사람이 따라야 하는 가이드라인
프로젝트 규칙 - 코딩 표준, 파일 구조, 네이밍 패턴
일반적인 명령어 - 프로젝트에 특화된 빌드, 테스트, 배포 명령어
장기 메모리 - 모든 세션에 걸쳐 유지되어야 하는 컨텍스트
버전 관리되는 지시사항 - git에 커밋하여 팀이 동기화 상태를 유지

주요 특성:

✅ 프로젝트 내 모든 세션에서 영구적
✅ git을 통해 팀과 공유
✅ 자동 검색 (코드 변경 불필요)
⚠️ settingSources를 통한 설정 로드 필요

방법 2: 출력 스타일 (영구적 구성)

출력 스타일은 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]

방법 3: append와 함께 `systemPrompt` 사용

Claude Code 프리셋에 append 속성을 사용하여 모든 내장 기능을 유지하면서 커스텀 지시사항을 추가할 수 있습니다.

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

const messages = [];

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Always include detailed docstrings and type hints in Python code.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

방법 4: 커스텀 시스템 프롬프트

커스텀 문자열을 systemPrompt로 제공하여 기본값을 완전히 자신의 지시사항으로 대체할 수 있습니다.

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

네 가지 접근 방식 비교

기능	CLAUDE.md	출력 스타일	append를 사용한 `systemPrompt`	커스텀 `systemPrompt`
영속성	프로젝트별 파일	파일로 저장	세션 한정	세션 한정
재사용성	프로젝트별	프로젝트 간	코드 중복	코드 중복
관리	파일 시스템에서	CLI + 파일	코드 내	코드 내
기본 도구	유지	유지	유지	손실 (포함하지 않는 한)
내장 안전성	유지	유지	유지	직접 추가 필요
환경 컨텍스트	자동	자동	자동	직접 제공 필요
커스터마이즈 수준	추가만	기본값 대체	추가만	완전한 제어
버전 관리	프로젝트와 함께	가능	코드와 함께	코드와 함께
범위	프로젝트 한정	사용자 또는 프로젝트	코드 세션	코드 세션

사용 사례 및 모범 사례

CLAUDE.md를 사용해야 하는 경우

적합한 용도:

프로젝트별 코딩 표준 및 규칙
프로젝트 구조 및 아키텍처 문서화
일반적인 명령어 나열 (빌드, 테스트, 배포)
버전 관리되어야 하는 팀 공유 컨텍스트
프로젝트의 모든 SDK 사용에 적용되는 지시사항

예시:

"모든 API 엔드포인트는 async/await 패턴을 사용해야 합니다"
"커밋 전에 npm run lint:fix를 실행하세요"
"데이터베이스 마이그레이션은 migrations/ 디렉토리에 있습니다"

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

적합한 용도:

세션 간 영구적인 동작 변경
팀 공유 구성
전문화된 어시스턴트 (코드 리뷰어, 데이터 과학자, 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: "Review this authentication module",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        For this review, prioritize:
        - OAuth 2.0 compliance
        - Token storage security
        - Session management
      `,
    },
  },
})) {
  messages.push(message);
}

참고 자료

출력 스타일 - 전체 출력 스타일 문서
TypeScript SDK 가이드 - 전체 SDK 사용 가이드
구성 가이드 - 일반 구성 옵션

Was this page helpful?

시스템 프롬프트 이해하기

수정 방법

방법 1: CLAUDE.md 파일 (프로젝트 수준 지시사항)

CLAUDE.md가 SDK와 작동하는 방식

CLAUDE.md 예시

SDK에서 CLAUDE.md 사용하기

CLAUDE.md를 사용해야 하는 경우

방법 2: 출력 스타일 (영구적 구성)

출력 스타일 만들기

출력 스타일 사용하기

방법 3: append와 함께 systemPrompt 사용

방법 4: 커스텀 시스템 프롬프트

네 가지 접근 방식 비교

사용 사례 및 모범 사례

CLAUDE.md를 사용해야 하는 경우

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

append를 사용한 systemPrompt를 사용해야 하는 경우

커스텀 systemPrompt를 사용해야 하는 경우

접근 방식 결합

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

참고 자료

시스템 프롬프트 이해하기

수정 방법

방법 1: CLAUDE.md 파일 (프로젝트 수준 지시사항)

CLAUDE.md가 SDK와 작동하는 방식

CLAUDE.md 예시

SDK에서 CLAUDE.md 사용하기

CLAUDE.md를 사용해야 하는 경우

방법 2: 출력 스타일 (영구적 구성)

출력 스타일 만들기

출력 스타일 사용하기

방법 3: append와 함께 systemPrompt 사용

방법 4: 커스텀 시스템 프롬프트

네 가지 접근 방식 비교

사용 사례 및 모범 사례

CLAUDE.md를 사용해야 하는 경우

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

append를 사용한 systemPrompt를 사용해야 하는 경우

커스텀 systemPrompt를 사용해야 하는 경우

접근 방식 결합

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

참고 자료

방법 3: append와 함께 `systemPrompt` 사용

append를 사용한 `systemPrompt`를 사용해야 하는 경우

커스텀 `systemPrompt`를 사용해야 하는 경우

방법 3: append와 함께 `systemPrompt` 사용

append를 사용한 `systemPrompt`를 사용해야 하는 경우

커스텀 `systemPrompt`를 사용해야 하는 경우