Gemini CLI 확장: 모범 사례

이 가이드는 Gemini CLI 확장을 개발, 보안 및 유지 관리하기 위한 모범 사례를 다룹니다.

개발

Gemini CLI용 확장을 개발하는 것은 가볍고 반복적인 과정이 되도록 의도되었습니다.

확장 구조화하기

간단한 확장은 몇 개의 파일로 구성될 수 있지만, 복잡한 확장을 위해서는 견고한 구조를 권장합니다:

my-extension/
├── package.json
├── tsconfig.json
├── gemini-extension.json
├── src/
│   ├── index.ts
│   └── tools/
└── dist/

TypeScript 사용: 타입 안전성과 더 나은 도구 지원을 위해 TypeScript 사용을 강력히 권장합니다.
소스와 빌드 분리: 소스 코드는 src에 유지하고 dist로 빌드하세요.
종속성 번들링: 확장에 많은 종속성이 있는 경우, 설치 시간과 잠재적 충돌을 줄이기 위해 번들링(예: esbuild 또는 webpack 사용)을 고려하세요.

`link`로 반복하기

gemini extensions link를 사용하여 지속적으로 다시 설치하지 않고 로컬에서 개발하세요:

cd my-extension
gemini extensions link .

코드를 변경하고 다시 빌드하면, CLI를 재시작했을 때 변경 사항을 즉시 사용할 수 있습니다.

`GEMINI.md` 효과적으로 사용하기

GEMINI.md 파일은 모델에 컨텍스트를 제공합니다. 초점을 유지하세요:

할 것: 높은 수준의 목표와 제공된 도구 사용 방법을 설명하세요.
하지 말 것: 전체 문서를 쏟아붓지 마세요.
할 것: 명확하고 간결한 언어를 사용하세요.

보안

Gemini CLI 확장을 구축할 때 일반적인 보안 모범 사례(최소 권한 및 입력 유효성 검사 등)를 따 위험을 줄이세요.

최소 권한

MCP 서버에서 도구를 정의할 때 필요한 권한만 요청하세요. 더 제한된 도구 세트로 충분하다면 모델에 광범위한 액세스(예: 전체 쉘 액세스)를 제공하지 마세요.

run_shell_command와 같은 강력한 도구를 사용해야 하는 경우, gemini-extension.json에서 특정 명령으로 제한하는 것을 고려하세요:

{
  "name": "my-safe-extension",
  "excludeTools": ["run_shell_command(rm -rf *)"]
}

이렇게 하면 모델이 위험한 명령을 실행하려고 시도하더라도 CLI 수준에서 차단됩니다.

입력 유효성 검사

MCP 서버는 사용자의 컴퓨터에서 실행됩니다. 도구에 대한 입력을 항상 검증하여 의도한 범위를 벗어난 임의 코드 실행이나 파일 시스템 액세스를 방지하세요.

// Good: 경로 유효성 검사
if (!path.resolve(inputPath).startsWith(path.resolve(allowedDir) + path.sep)) {
  throw new Error('Access denied');
}

민감한 설정

확장에 API 키가 필요한 경우 gemini-extension.json에서 sensitive: true 옵션을 사용하세요. 이렇게 하면 키가 시스템 키체인에 안전하게 저장되고 UI에서 난독화됩니다.

"settings": [
  {
    "name": "API Key",
    "envVar": "MY_API_KEY",
    "sensitive": true
  }
]

배포

확장을 GitHub에 직접 업로드하여 갤러리에 나열할 수 있습니다. Gemini CLI 확장은 더 복잡한 릴리스에 대한 지원도 제공합니다.

시맨틱 버저닝 (Semantic Versioning)

Semantic Versioning (opens in a new tab)을 따르세요.

Major: 호환되지 않는 변경 (도구 이름 변경, 인수 변경).
Minor: 새로운 기능 (새 도구, 명령).
Patch: 버그 수정.

배포 채널

git 브랜치를 사용하여 배포 채널을 관리하세요 (예: 안정 버전은 main, 최신 개발 버전은 dev). 이를 통해 사용자는 안정성 수준을 선택할 수 있습니다:

# Stable (안정 버전)
gemini extensions install github.com/user/repo
 
# Dev (개발 버전)
gemini extensions install github.com/user/repo --ref dev

아티팩트 정리

GitHub Releases를 사용하는 경우 릴리스 아티팩트에 필요한 파일(dist/, gemini-extension.json, package.json)만 포함되어 있는지 확인하세요. 다운로드 크기를 작게 유지하기 위해 node_modules(사용자가 설치함)와 src/는 제외하세요.

확장 레퍼런스 확장 배포