Gemini CLI extensionsをチームで使う前に：MCP・custom commands・settingsを分ける基準

このテーマをもう少し広げて見るなら、Codex Skillsをチームで入れる前に：サードパーティSkill・MCP依存・権限を監査する と MCP Registryからサーバーを選ぶ前に：OAuth・tool poisoning・allowlistの安全な見方 も合わせて確認してください。Gemini CLI extensionと同じく、promptやMCP依存を配布単位にする前の監査観点へつなげられる

3行まとめ

GEMINI.md

project固有の文脈を残す。

Commands

繰り返すpromptをTOML化する。

MCP

外部toolの入口を分ける。

Extensions

共有と配布の単位にする。

Gemini CLIは、設定を全部extensionにせず段階で分けます。

• Gemini CLIをチームで使う時は、project文脈を GEMINI.md、繰り返すpromptをcustom commands、外部toolをMCP servers、複数projectへ配るものをextensionsに分けると管理しやすくなります。
• MCP serverを増やす前に、sandbox、checkpointing、include directories、settingsの優先順位を決めます。外部toolを足すことは、agentへ新しい操作能力を渡す判断です。
• extensionは便利な共有単位ですが、最初から作るものではありません。1つのprojectで使われたcommandやMCP設定を、複数projectへ広げる段階で昇格させます。

本文の事実確認には、Gemini CLI公式docsのExtensions、Custom Commands、Configuration、MCP Server Integration、Enterprise Configurationを使っています。Xで見かけるGemini CLI、MCP、custom slash commands、GitHub Actions連携への投稿は需要シグナルとして扱い、本文の根拠にはしていません。

この記事でわかること

Context

GEMINI.mdへ置く情報を決める。

Shortcut

custom commandにするpromptを選ぶ。

Tools

MCP serverの権限を分ける。

Share

extensionへ昇格する条件を決める。

置き場所を分けると、設定が増えても棚卸ししやすくなります。

• Gemini CLIの GEMINI.md、custom commands、MCP servers、extensionsの使い分け
• project設定、user設定、enterprise設定をどう分けるか
• extensionにMCP serverを含める時の注意点
• settingsとextensionで同じMCP server名がある時の見方
• sandboxとcheckpointingを導入初期に決める理由
• 初週にどこまで共有すればよいか

Gemini CLIは、terminalからGemini agentを使うための道具です。個人利用では、GEMINI.md に文脈を書き、よく使うpromptをcustom commandにして、必要なMCP serverを足していけば十分です。

ただしチーム運用になると、設定が散らばります。誰かの ~/.gemini/settings.json だけにあるMCP server、repo内だけにあるcommand、使われていないextension、似た名前のslash commandが増えると、どれが標準なのか追えません。この記事では、Gemini CLIの拡張をチームで扱うための境界を整理します。

前提知識

項目	内容	見方
CLI		terminalからGemini agentを使う。
Settings		settings.jsonで挙動を変える。
Commands		TOMLでslash commandを作る。
Extensions		prompts、MCP、commandsを束ねる。

Gemini CLIの拡張は、設定fileとextensionの関係を見ます。

Gemini CLI公式docsでは、Gemini CLIをclient側のCLIとlocal server側のcoreで構成されるAI agentとして説明しています。設定はenvironment variables、command-line arguments、settings filesで変えられ、projectの .gemini directoryにはproject-specificなfileを置けます。

Extensions docsでは、Gemini CLI extensionsはprompts、MCP servers、custom commandsをpackageし、installしやすく共有しやすい形式にするものと説明されています。Custom Commands docsでは、TOML形式のcommand definition fileで、よく使うpromptをslash commandとして再利用できると説明されています。

この記事の扱う範囲

項目	役割
GEMINI.md	project固有の文脈、方針、よく使う手順を伝える
custom commands	TOMLで繰り返すpromptをslash command化する
MCP servers	GitHub、database、社内APIなど外部toolの入口にする
settings.json	sandbox、checkpointing、MCP、include directoriesなどを管理する
extensions	prompts、MCP servers、custom commandsを束ねて共有する
enterprise config	組織標準の設定を配布する

2026年5月31日時点で公開されているGemini CLI公式docsを確認しています。導入時には、利用中のGemini CLI version、Google account/API keyの認証方式、社内のtool利用規程を確認してください。

注意点

この記事は、外部MCP serverや第三者extensionを無条件に推奨するものではありません。Gemini CLI extensionsはMCP serversを含められるため、単なるprompt集ではなく、tool権限を配る仕組みにもなります。

まず4つの置き場所に分ける

項目	内容	見方
Project		repo固有の文脈と手順。
User		個人の好みや短縮command。
Settings		MCPやsandboxなどの挙動。
Extension		複数projectへ配る機能。

使われる範囲が広がってからextension化します。

Gemini CLIの拡張は、最初に置き場所を分けます。すべてをextensionへ入れると、変更の責任範囲が重くなります。すべてを個人設定へ置くと、チーム標準になりません。

置き場所	向くもの	避けたいもの
project	repo固有の文脈、検証command、review観点	他repoでも使う共通tool
user	個人の好み、editor、短縮command	team必須の設定
settings	MCP server、sandbox、checkpointing、include directories	長い作業手順
extension	複数projectへ配るcommands、prompts、MCP設定	試作段階の個人prompt

この4つを分けると、共有する前の実験と、共有した後の運用を切り分けられます。

最初はprojectから始める

初日からextensionを作る必要はありません。まずprojectの .gemini/ に文脈とcommandを置き、実際に使われるかを見ます。複数repoへ同じものをコピーし始めたら、extension化を検討します。

個人設定を標準にしない

個人の ~/.gemini/settings.json にだけMCP serverがある状態で「Gemini CLIならこのtoolが使える」と説明すると、他のteam memberは再現できません。標準化したいものはproject、extension、enterpriseのどこに置くかを決めます。

GEMINI.mdはproject文脈に使う

Structure

主要directoryと責務。

Rules

禁止操作とreview基準。

Commands

よく使う検証command。

Tone

出力の型や言語。

GEMINI.mdは操作を増やす場所ではなく、判断の前提を揃える場所です。

GEMINI.md は、Gemini CLIにprojectの文脈を伝えるための入口です。公式docsのGet Startedでは、/init commandが現在のdirectoryを分析し、project-specificなinstruction fileを作る流れが説明されています。

GEMINI.md に向いているのは、どの作業でも読んでほしい前提です。directory構成、禁止操作、test command、review基準、PR説明の書き方、domain用語などを短く置きます。

入れるもの

項目	例
directory	apps/web、packages/api、docs の責務
commands	lint、test、typecheck、build
rules	secretを出さない、migrationは確認する
review	変更理由、test結果、riskを書く
language	日本語で返す、PR本文は英語にする

入れすぎないもの

GEMINI.md は、長い手順書を全部貼る場所ではありません。毎回使う文脈だけを置き、特定作業の手順はcustom commandや別docへ分けます。長すぎると、agentが重要な部分を拾いにくくなります。

判断基準

「どの依頼でも読んでほしい前提」は GEMINI.md、「特定の作業で呼び出したい手順」はcustom commandです。

custom commandsは繰り返すpromptに使う

項目	内容	見方
Review		diff確認の観点を固定。
Release		release noteや確認項目。
Explain		directoryやfileの説明。
Args		{{args}}で対象を受け取る。

custom commandは、手順を短く呼び出すための入口です。

Gemini CLIのCustom Commands docsでは、TOML形式のdefinition fileを使って、よく使うpromptをslash commandとして保存できると説明されています。{{args}} で引数を受け取り、@{...} のようにfile内容をpromptへ含める使い方も紹介されています。

custom commandに向いているのは、毎回同じ観点で見る作業です。PR review、release note、migration確認、error log要約、directory説明など、出力の型が決まっているものに向きます。

commandにする条件

条件	内容
繰り返す	月に何度も同じpromptを使う
引数がある	対象file、branch、issue番号を受け取る
出力が決まる	summary、risk、test、next actionに分ける
project依存	repo固有ならproject commandにする

commandを増やしすぎない

custom commandが増えると、便利さより探索負荷が勝ちます。最初はreview、release、explainのように3つ以内へ絞ります。使われないcommandはextension化しません。

MCP serversは外部toolの入口にする

APIs

GitHubや社内APIに接続する。

Data

databaseやstorageを扱う。

Scripts

独自workflowをtool化する。

Status

/mcpで接続状態を確認する。

MCP server追加は、agentに新しい操作能力を渡す判断です。

Gemini CLI docsでは、MCP serversを使うと、built-in機能を超えてdatabase、API、custom scripts、specialized workflowsとやり取りできると説明されています。/mcp commandでは、configured MCP servers、connection status、server details、available toolsを確認できます。

MCP serverの追加は、agentが外部toolを使えるようになる判断です。GitHub、Slack、database、browser、社内APIなどへつなぐ場合、promptの品質だけでなく、tool権限、secret、network接続、auditを見ます。

MCP server追加前の確認

観点	確認すること
接続先	GitHub、database、社内API、local command
権限	read-onlyか、write可能か
secret	tokenやAPI keyの置き場所
scope	project単位かuser単位か
audit	tool callの記録を残せるか

Gemini CLIに限らず、MCPの更新やtool追加は影響範囲を分ける必要があります。MCPそのものの確認観点は、MCP更新で壊さないための確認手順でも整理しています。

extensionsは共有と配布の単位にする

Reusable

複数repoで同じcommandを使う。

Bundled

commandsとMCPをまとめる。

Versioned

releaseとupdateを管理する。

Installable

GitHub URLやlocal pathから入れる。

extensionは便利な箱ですが、更新責任も一緒に生まれます。

Extensions docsでは、extensionがprompts、MCP servers、custom commandsをpackageし、installしやすく共有しやすい形式にすると説明されています。gemini extensions install はGitHub URLまたはlocal pathからinstallでき、installed extensionはcopyされるため、更新には gemini extensions update が必要です。

extension化する条件は、単に「便利だから」ではありません。複数projectで同じcommandやMCP設定を使う、versionやreleaseを管理したい、install手順を標準化したい、という段階で検討します。

extension化する前の質問

• 2つ以上のrepoで同じcommandを使っているか
• MCP serverを含める必要があるか
• 更新責任者は誰か
• GitHub releaseやversionを使うか
• 壊れた時にupdate、disable、uninstallできるか

extensionは共有に向いていますが、壊れた時の影響も広がります。特にMCP serverを含むextensionは、promptだけでなくtool権限も共有します。

Claude Code pluginとの違い

Claude Codeではplugin、skills、hooks、marketplaceを分けて考えました。詳しくはClaude Codeのpluginをチームで使う前にで整理しています。Gemini CLIでは、TOML custom commands、settings.json、extension内MCP、settings優先関係が実務上の焦点になります。

settings優先順位と名前衝突を見る

項目	内容	見方
MCP name		settings側が優先される場合を見る。
Command name		短いslash commandの衝突に注意。
Merge		objectやarrayのmergeを確認。
Restart		変更反映に再起動が必要なもの。

同じ名前を使う前に、どちらが効くかを確認します。

Gemini CLIでは、settingsの置き場所とmergeを意識します。Enterprise docsでは、arrayやobjectに対してmergeされる設定があることが説明されています。Extensions docsでは、extensionと settings.json が同じ名前のMCP serverを設定している場合、settings.json 側のserverが優先されると説明されています。

この仕様を知らないと、「extensionを入れたのにMCP serverが想定と違う」「個人設定がteam標準を上書きしている」という状態になります。

衝突しやすい項目

項目	見ること
MCP server name	extensionとsettingsで同名がないか
custom command name	短いslash commandが重複していないか
includeDirectories	読ませる範囲が広がりすぎていないか
sandbox	project標準と個人設定が矛盾していないか

名前の付け方

team共有のMCP server名は、短すぎる名前を避けます。github だけではなく、github-readonly、internal-docs-readonly のように権限や用途が見える名前にします。custom commandも、/review だけでなく、project固有なら /web-review のように役割が見える名前にします。

sandboxとcheckpointingを先に決める

項目	内容	見方
Sandbox		tool実行を隔離する。
Checkpoint		file変更の戻し口を作る。
Shell		危険commandを確認対象にする。
Directory		includeする範囲を絞る。

拡張を増やす前に、実行範囲と戻し方を決めます。

Gemini CLI docsでは、advanced featureとしてsandboxingとcheckpointingが説明されています。sandboxingはtool executionを隔離するための仕組みで、checkpointingはtool実行前の状態へ戻すための入口として扱えます。

拡張を増やす前に、実行範囲と戻し方を決めます。MCP serverやcustom commandを増やした後で決めようとすると、既にteam memberごとの運用が分かれています。

最初に決めること

項目	決める内容
sandbox	どのprofileで使うか
checkpointing	file変更を戻す運用を使うか
shell	! commandやshell実行の扱い
directories	includeするdirectoryの範囲
secrets	prompt、file、MCP envへ入れない情報

このあたりは、AI coding agent全般の権限設計と同じです。企業導入の権限境界は、AIコーディングエージェント導入ガイドでも整理しています。

最小構成の始め方

項目	内容	見方
GEMINI.md		project文脈を1枚にまとめる。
One command		review commandを1つ作る。
No MCP		初回はtool追加を避ける。
No extension		使われるまで配布物にしない。

最初は文脈とpromptだけを固定し、tool権限は後から足します。

最初の構成は、小さくします。GEMINI.md でproject文脈を固定し、custom commandを1つだけ作り、MCP serverとextensionはまだ追加しません。これで、team memberがGemini CLIをどう使うかを観察できます。

最初のfile構成

.gemini/
  commands/
    pr-review.toml
GEMINI.md

GEMINI.md にはproject文脈、test command、禁止操作を短く書きます。pr-review.toml には、PRを見る順番、risk、tests、not run、next actionの出力型を書きます。

最初のcommandに入れる内容

• 対象diffやfileをどう渡すか
• 先に読むproject文脈
• 出力形式
• test確認の書き方
• 実行していないことの書き方

この段階では、外部MCP serverを入れません。まず、promptと出力の型だけで改善する範囲を見ます。

導入初週の進め方

1. 1日目

   GEMINI.mdでproject文脈を整える。

2. 2日目

   custom commandを1つ作る。

3. 3日目

   /mcpで既存serverを確認する。

4. 5日目

   sandboxとcheckpointingを確認。

5. 7日目

   extension化する候補をreview。

使われた設定だけを共有物へ昇格させると、管理が軽くなります。

初週は、拡張を増やすより、再現できる使い方を作る週です。個人設定へ隠れたMCP serverやcommandを標準にしないよう、project内に見える形で始めます。

日	やること	完了条件
1日目	GEMINI.md を作る	directory、commands、禁止操作が短く書かれている
2日目	custom commandを1つ作る	team memberが同じpromptを呼び出せる
3日目	/mcp で現状確認する	使っているserver名と権限を説明できる
5日目	sandboxとcheckpointingを確認する	実行範囲と戻し方が決まる
7日目	extension化候補をreviewする	複数projectへ配る価値があるか判断できる

extension化の合図

• 同じcommandを複数repoへコピーしている
• 同じMCP server設定を複数repoで使っている
• settingsの説明がREADMEだけでは追えなくなった
• versionやreleaseで配りたい
• onboarding時のinstall手順を短くしたい

この条件を満たしたらextension化を検討します。まだ1repoでしか使っていないものは、project設定に残します。

FAQ

Command or GEMINI.md?

呼び出す手順か常時文脈かで分ける。

MCP or extension?

tool単体か配布単位かで分ける。

Settings?

挙動と権限を管理する。

Enterprise?

組織標準の配布に使う。

迷ったら、誰が使い、何を実行できるかを先に見ます。

GEMINI.md とcustom commandはどう分けますか

常に読ませたいproject文脈は GEMINI.md、特定作業で呼び出したいpromptはcustom commandです。review手順やrelease note生成のように、呼び出し名がある方が自然なものはcommandにします。

MCP serverとextensionは何が違いますか

MCP serverは外部toolの入口です。extensionは、MCP servers、custom commands、promptsを束ねてinstallしやすくする配布単位です。tool単体ならMCP server設定、共有物として配るならextensionを検討します。

settingsとextensionで同じMCP server名があるとどうなりますか

Gemini CLI Extensions docsでは、extensionと settings.json が同じMCP server名を設定している場合、settings.json 側が優先されると説明されています。同名を使う時は、どちらが効いているかを /mcp で確認します。

enterprise設定はいつ必要ですか

個人や1projectなら不要です。複数teamでGemini CLIの挙動、MCP server、sandbox、policyを揃えたい時にenterprise configurationを検討します。

CodexやClaude Codeにも同じ考え方を使えますか

使えます。形式は違っても、project文脈、繰り返す手順、外部tool、共有単位を分ける考え方は共通です。チームでagentを使う基本は、チーム向けAGENTS.mdテンプレートも参考になります。

---

次に読むなら

参照した主な情報源

• Gemini CLI documentation

https://google-gemini.github.io/gemini-cli/docs/

• Gemini CLI Extensions

https://google-gemini.github.io/gemini-cli/docs/extensions/

• Gemini CLI Custom Commands

https://google-gemini.github.io/gemini-cli/docs/cli/custom-commands.html

• Gemini CLI Configuration

https://google-gemini.github.io/gemini-cli/docs/get-started/configuration.html

• Gemini CLI Enterprise Configuration

https://google-gemini.github.io/gemini-cli/docs/cli/enterprise.html

• Google for Developers: Gemini CLI

https://developers.google.com/gemini-code-assist/docs/gemini-cli

次に読むなら

更新履歴

1. 2026年5月31日

   Gemini CLI公式docsのextensions、custom commands、configuration、MCP、enterpriseを確認して初版を作成しました。

導入時には公式docsと利用中のGemini CLI versionを確認してください。

• 2026年5月31日: Gemini CLI公式docsのextensions、custom commands、configuration、MCP、enterpriseを確認し、初版を作成しました。