Docs
고급 기능
시스템 프롬프트 재정의

시스템 프롬프트 재정의 (GEMINI_SYSTEM_MD)

Gemini CLI를 안내하는 핵심 시스템 지침을 여러분만의 Markdown 파일로 완전히 대체할 수 있습니다. 이 기능은 GEMINI_SYSTEM_MD 환경 변수를 통해 제어됩니다.

개요

GEMINI_SYSTEM_MD 변수는 CLI가 내장된 기본값 대신 외부 Markdown 파일을 시스템 프롬프트로 사용하도록 지시합니다. 이는 병합이 아니라 완전한 대체입니다. 사용자 지정 파일을 사용하는 경우, 여러분이 직접 포함하지 않는 한 원래의 핵심 지침 중 어느 것도 적용되지 않습니다.

이 기능은 엄격한 프로젝트별 동작을 강제하거나 사용자 지정 페르소나를 생성해야 하는 고급 사용자를 위한 것입니다.

팁: 현재 기본 시스템 프롬프트를 먼저 파일로 내보낸 후 검토하고, 선택적으로 수정하거나 대체할 수 있습니다(“기본 프롬프트 내보내기” 참조).

활성화 방법

셸에서 환경 변수를 일시적으로 설정하거나 .gemini/.env 파일을 통해 지속적으로 설정할 수 있습니다. 환경 변수 지속하기를 참조하세요.

  • 프로젝트 기본 경로 (.gemini/system.md) 사용:

    • GEMINI_SYSTEM_MD=true 또는 GEMINI_SYSTEM_MD=1
    • CLI는 ./.gemini/system.md를 읽습니다 (현재 프로젝트 디렉터리 기준).

  • 사용자 지정 파일 경로 사용:

    • GEMINI_SYSTEM_MD=/absolute/path/to/my-system.md
    • 상대 경로는 지원되며 현재 작업 디렉터리에서 확인됩니다.
    • 물결표 확장(Tilde expansion)이 지원됩니다 (예: ~/my-system.md).

  • 재정의 비활성화 (내장 프롬프트 사용):

    • GEMINI_SYSTEM_MD=false 또는 GEMINI_SYSTEM_MD=0 또는 변수 설정 해제.

재정의가 활성화되었지만 대상 파일이 존재하지 않는 경우, CLI는 다음과 같은 오류를 발생시킵니다: missing system prompt file '<path>'.

간단한 예시

  • 프로젝트 파일을 사용하는 일회성 세션:
    • GEMINI_SYSTEM_MD=1 gemini
  • .gemini/.env를 사용하여 프로젝트에 지속적으로 적용:
    • .gemini/system.md를 생성한 후 .gemini/.env에 추가:
      • GEMINI_SYSTEM_MD=1
  • 홈 디렉터리 아래의 사용자 지정 파일 사용:
    • GEMINI_SYSTEM_MD=~/prompts/SYSTEM.md gemini

UI 표시

GEMINI_SYSTEM_MD가 활성화되면 CLI는 UI에 |⌐■_■| 표시를 보여주어 사용자 지정 시스템 프롬프트 모드임을 알립니다.

변수 대체

사용자 지정 시스템 프롬프트 파일을 사용할 때 다음 변수를 사용하여 내장 콘텐츠를 동적으로 포함할 수 있습니다.

  • ${AgentSkills}: 사용 가능한 모든 에이전트 기술의 전체 섹션(헤더 포함)을 주입합니다.

  • ${SubAgents}: 사용 가능한 서브 에이전트의 전체 섹션(헤더 포함)을 주입합니다.

  • ${AvailableTools}: 현재 활성화된 모든 도구 이름의 글머리 기호 목록을 주입합니다.

  • 도구 이름 변수: 다음 패턴을 사용하여 도구의 실제 이름을 주입합니다: ${toolName}_ToolName (예: ${write_file_ToolName}, ${run_shell_command_ToolName}).

    이 패턴은 사용 가능한 모든 도구에 대해 동적으로 생성됩니다.

예시

# Custom System Prompt
 
You are a helpful assistant. ${AgentSkills}
${SubAgents}
 
## Tooling
 
The following tools are available to you: ${AvailableTools}
 
You can use ${write_file_ToolName} to save logs.

기본 프롬프트 내보내기 (권장)

재정의하기 전에 현재 기본 프롬프트를 내보내서 필요한 안전 및 워크플로 규칙을 검토하세요.

  • 내장 프롬프트를 프로젝트 기본 경로에 쓰기:
    • GEMINI_WRITE_SYSTEM_MD=1 gemini
  • 또는 사용자 지정 경로에 쓰기:
    • GEMINI_WRITE_SYSTEM_MD=~/prompts/DEFAULT_SYSTEM.md gemini

이 명령은 파일을 생성하고 현재 내장된 시스템 프롬프트를 해당 파일에 씁니다.

모범 사례: SYSTEM.md 대 GEMINI.md

  • SYSTEM.md (펌웨어):
    • 협상 불가능한 운영 규칙: 안전, 도구 사용 프로토콜, 승인 및 CLI를 신뢰할 수 있게 유지하는 메커니즘.
    • 작업 및 프로젝트 전반에 걸쳐 안정적입니다 (또는 필요시 프로젝트별로).
  • GEMINI.md (전략):
    • 페르소나, 목표, 방법론 및 프로젝트/도메인 컨텍스트.
    • 작업별로 발전하며 안전한 실행을 위해 SYSTEM.md에 의존합니다.

SYSTEM.md는 안전 및 도구 작동을 위해 최소한으로 유지하되 완전하게 유지하세요. GEMINI.md는 상위 수준의 지침 및 프로젝트 세부 정보에 집중하세요.

문제 해결

  • 오류: missing system prompt file '…'
    • 참조된 경로가 존재하고 읽을 수 있는지 확인하세요.
    • GEMINI_SYSTEM_MD=1|true의 경우, 프로젝트에 ./.gemini/system.md를 생성하세요.
  • 재정의가 적용되지 않음
    • 변수가 로드되었는지 확인하세요 (.gemini/.env 사용 또는 셸에서 내보내기).
    • 경로는 현재 작업 디렉터리에서 확인됩니다. 절대 경로를 시도해보세요.
  • 기본값 복원
    • GEMINI_SYSTEM_MD 설정을 해제하거나 0/false로 설정하세요.
샌드박싱원격 측정