시스템 프롬프트 이해하기
시스템 프롬프트는 대화 전반에 걸쳐 Claude가 어떻게 동작할지를 형성하는 초기 명령어 세트입니다.기본 동작: Agent SDK는 최대한의 유연성을 위해 기본적으로 빈 시스템 프롬프트를 사용합니다. Claude Code의 시스템 프롬프트(도구 지침, 코드 가이드라인 등)를 사용하려면 TypeScript에서
systemPrompt: { preset: "claude_code" }
를 지정하거나 Python에서 system_prompt="claude_code"
를 지정하세요.- 도구 사용 지침 및 사용 가능한 도구
- 코드 스타일 및 형식 가이드라인
- 응답 톤 및 상세도 설정
- 보안 및 안전 지침
- 현재 작업 디렉토리 및 환경에 대한 컨텍스트
수정 방법
방법 1: 출력 스타일 (지속적 구성)
출력 스타일은 Claude의 시스템 프롬프트를 수정하는 저장된 구성입니다. 마크다운 파일로 저장되며 세션과 프로젝트 간에 재사용할 수 있습니다.출력 스타일 생성하기
출력 스타일 사용하기
생성된 후, 다음을 통해 출력 스타일을 활성화할 수 있습니다:- CLI:
/output-style [style-name]
- 설정:
.claude/settings.local.json
- 새로 생성:
/output-style:new [description]
방법 2: append와 함께 systemPrompt
사용하기
모든 내장 기능을 보존하면서 사용자 정의 지침을 추가하기 위해 append
속성과 함께 Claude Code 프리셋을 사용할 수 있습니다.
방법 3: 사용자 정의 시스템 프롬프트
systemPrompt
에 사용자 정의 문자열을 제공하여 기본값을 완전히 자신만의 지침으로 대체할 수 있습니다.
세 가지 접근 방식 모두 비교
기능 | 출력 스타일 | append와 함께 systemPrompt | 사용자 정의 systemPrompt |
---|---|---|---|
지속성 | ✅ 파일로 저장됨 | ❌ 세션만 | ❌ 세션만 |
재사용성 | ✅ 프로젝트 간 | ❌ 코드 중복 | ❌ 코드 중복 |
관리 | ✅ CLI + 파일 | ⚠️ 코드 내 | ⚠️ 코드 내 |
기본 도구 | ✅ 보존됨 | ✅ 보존됨 | ❌ 손실됨 (포함하지 않는 한) |
내장 안전성 | ✅ 유지됨 | ✅ 유지됨 | ❌ 추가해야 함 |
환경 컨텍스트 | ✅ 자동 | ✅ 자동 | ❌ 제공해야 함 |
사용자 정의 수준 | ⚠️ 기본값 대체 | ⚠️ 추가만 | ✅ 완전한 제어 |
버전 제어 | ✅ 예 | ✅ 코드와 함께 | ✅ 코드와 함께 |
발견 가능성 | ✅ /output-style | ❌ 발견할 수 없음 | ❌ 발견할 수 없음 |
systemPrompt: { type: "preset", preset: "claude_code", append: "..." }
를 사용하거나 Python에서 system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}
를 사용하는 것을 의미합니다.
사용 사례 및 모범 사례
출력 스타일을 사용해야 하는 경우
최적 용도:- 세션 간 지속적인 동작 변경
- 팀 공유 구성
- 전문 어시스턴트 (코드 리뷰어, 데이터 사이언티스트, DevOps)
- 버전 관리가 필요한 복잡한 프롬프트 수정
- 전용 SQL 최적화 어시스턴트 생성
- 보안 중심 코드 리뷰어 구축
- 특정 교육법을 가진 교육 어시스턴트 개발
append와 함께 systemPrompt
를 사용해야 하는 경우
최적 용도:
- 특정 코딩 표준이나 선호도 추가
- 출력 형식 사용자 정의
- 도메인별 지식 추가
- 응답 상세도 수정
- 도구 지침을 잃지 않고 Claude Code의 기본 동작 향상
사용자 정의 systemPrompt
를 사용해야 하는 경우
최적 용도:
- Claude의 동작에 대한 완전한 제어
- 전문화된 단일 세션 작업
- 새로운 프롬프트 전략 테스트
- 기본 도구가 필요하지 않은 상황
- 고유한 동작을 가진 전문 에이전트 구축
접근 방식 결합하기
최대한의 유연성을 위해 이러한 방법들을 결합할 수 있습니다:예시: 세션별 추가 사항이 있는 출력 스타일
참고 자료
- 출력 스타일 - 완전한 출력 스타일 문서
- TypeScript SDK 가이드 - 완전한 SDK 사용 가이드
- TypeScript SDK 참조 - 전체 API 문서
- 구성 가이드 - 일반 구성 옵션