Agent SDK 시스템 프롬프트 수정
공식 기준: https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
시스템 프롬프트는 에이전트의 정체성·권한 모델·코딩 지침을 결정합니다. SDK는 Claude Code preset을 쓰거나, 최소 프롬프트에 덧붙이거나, 전면 교체할 수 있습니다. CLAUDE.md는 시스템 프롬프트가 아니라 대화 컨텍스트로 주입됩니다.
커스텀이 필요한 경우 예: 터미널 외 표면, Claude Code가 아닌 정체성, 무인 권한 모델, 비코딩 업무.
핵심 개념
| 방식 | 어디에 들어가나 | 특징 |
|---|---|---|
| CLAUDE.md | 대화 컨텍스트 (시스템 프롬프트 아님) | CLI·SDK 공유 프로젝트 지침 |
| Output styles | 시스템 프롬프트 섹션 | 영속 설정으로 스타일 전환 |
systemPrompt + append |
preset 뒤에 추가 | 세션 한정 보강 |
커스텀 systemPrompt 문자열 |
전체 교체 | 코딩 preset 제거 |
상세
출발점 결정
- 코딩 에이전트·CLI 호환:
claude_codepreset (+ CLAUDE.md) - 도메인 봇·다른 권한 모델: 커스텀 프롬프트 또는 append로 범위 축소
CLAUDE.md
settingSources에 project/user가 있으면 로드됩니다. SDK 전용 포인트는 로딩 조건입니다. settingSources를 명시하면 필요한 소스를 포함하세요.
options: {
systemPrompt: { type: "preset", preset: "claude_code" },
settingSources: ["project"]
}
Output styles
영속 구성으로 시스템 프롬프트 섹션을 바꿉니다. 팀/프로젝트 스타일 파일과 함께 쓰면 세션마다 동일 톤·형식을 유지합니다. CLI output styles와 같은 메커니즘을 SDK 옵션으로 선택합니다.
Append to claude_code preset
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "Always respond in Korean. Prefer minimal diffs."
}
}
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "Always respond in Korean. Prefer minimal diffs."
}
코딩 능력은 유지한 채 조직 규칙을 덧붙일 때 적합합니다.
커스텀 system prompt
문자열(또는 파일 기반)로 전체를 교체하면 Claude Code 코딩 지침이 사라집니다. 지원 봇·리서치 에이전트 등 다른 정체성에 사용합니다.
네 방식 비교·선택
| 상황 | 권장 |
|---|---|
| 프로젝트 컨벤션 공유 | CLAUDE.md |
| 재사용 가능한 톤/형식 | output styles |
| 이번 세션만 추가 지시 | append |
| Claude Code가 아닌 에이전트 | 커스텀 systemPrompt |
조합 가능: output style + session append, CLAUDE.md + preset 등. Skills/hooks/permissions는 시스템 프롬프트 밖에서 동작을 형성합니다.
체크리스트
- 코딩 preset이 필요한지 판단했다
- CLAUDE.md vs systemPrompt 주입 경로를 구분했다
- 마이그레이션 후 preset 미지정 시 minimal prompt임을 인지했다
- 충돌 지시(프로젝트 vs user)를 정리했다