Gemini CLI 自定义命令教程：从创建到实战全流程

Gemini CLI 除了提供 /model、/settings、/init 等内置命令外，还支持用户创建自定义命令。你可以把复杂的多步骤开发任务封装成一条简单的斜杠命令，让 AI 按照预设的提示词自动执行。本文通过一个 UI 组件生成命令的完整案例，手把手演示自定义命令从创建到使用的全过程。

什么是 Gemini CLI 自定义命令

自定义命令的本质是一段预定义的详细提示词（prompt）。它可以接收用户输入的参数，并引导模型按照既定流程完成特定任务。调用方式和内置命令一样——输入 /命令名 即可触发。

Gemini CLI 是 Google 推出的基于 Gemini 大语言模型的命令行交互工具，允许开发者直接在终端中与 AI 对话、执行代码分析和生成任务。它属于近年来兴起的 AI 编程助手（AI Coding Assistant）类别，与 GitHub Copilot CLI、Cursor、Aider 等工具类似，但其独特之处在于深度集成了 Google 的 Gemini 模型能力，并提供了可扩展的命令系统。这类工具的核心理念是将 AI 能力嵌入开发者最熟悉的工作环境——终端，减少上下文切换的成本。自定义命令正是这种可扩展性的核心体现。

常见的应用场景包括：

• Bug 修复命令：让模型扫描代码中的 bug 并给出修复方案
• Git 自动化命令：执行一系列 git 操作并推送到远程仓库
• 组件生成命令：根据描述自动创建 UI 组件、测试文件和预览页面

这种机制的核心价值在于：把你的最佳实践和工作流程固化为可复用的命令，每次执行都能保持一致的质量标准。

创建自定义命令的完整步骤

准备目录结构

首先确认项目根目录下有 .gemini 文件夹，没有就手动创建。接着在 .gemini 文件夹内新建一个 commands 子文件夹，所有自定义命令都放在这里。

注册新命令的方式很简单：在 commands 文件夹中创建一个 .toml 文件，文件名就是命令名。比如创建 component.toml，之后在 CLI 中输入 /component 就能调用。

TOML 文件的基本结构

每个命令文件需要包含两个关键字段：

• description：命令的简短描述，输入命令时会在 CLI 中显示
• prompt：命令执行时发送给模型的完整提示词

TOML（Tom's Obvious, Minimal Language）是一种语义明确、易于阅读的配置文件格式，由 GitHub 联合创始人 Tom Preston-Werner 于 2013 年创建。它被广泛用于 Rust 的 Cargo.toml、Python 的 pyproject.toml 等项目配置中。相比 JSON 不支持注释、YAML 对缩进敏感容易出错，TOML 在可读性和严谨性之间取得了良好平衡。Gemini CLI 选择 TOML 作为命令定义格式，使得命令文件既能包含多行提示词文本（使用三引号语法），又保持结构清晰，非常适合承载复杂的提示词内容。

这里有个重要的语法：prompt 中可以使用 {{args}} 双花括号来引用用户在命令名之后输入的所有参数。举个例子，当用户输入 /component 一个圆形头像组件 时，"一个圆形头像组件" 这段文字会自动填充到 {{args}} 的位置。这种模板变量机制在提示词工程中非常常见，它让同一个命令模板能够适应不同的具体需求，实现了"一次编写、多次复用"的效果。

实战：编写 UI 组件生成命令

下面是 component.toml 的完整提示词逻辑，包含 7 个精心设计的步骤。这些步骤的编排本身就是一种 Prompt Engineering（提示词工程）实践——通过分步指令（Step-by-step Instructions）将复杂任务拆解为有序步骤，降低模型遗漏关键环节的概率；通过约束强调（Constraint Reinforcement）多次重复关键约束条件来提高模型遵守规则的可靠性。这些技巧的组合使用，是自定义命令能够稳定产出高质量结果的关键。

第一步：Git 安全检查

提示词首先要求模型运行 shell 命令，检查当前分支是否存在未提交、未暂存或未跟踪的更改。一旦检测到，立即中止流程并通知用户。这一步至关重要——后续需要切换到新分支，如果当前有未处理的更改，可能导致代码丢失。

第二步至第三步：自动创建分支

模型会根据组件描述自动推导出一个分支名，格式为 component/slug（小写字母、kebab-case）。然后向用户展示即将执行的 git 命令（如 git switch -c component/avatar），并切换到新分支。

kebab-case 是一种以连字符分隔单词、全部小写的命名风格（如 circular-avatar、user-profile），因形似烤肉串上的食材排列而得名。它在 URL 路径、CSS 类名、Git 分支名和 npm 包名中被广泛使用，因为连字符在这些上下文中是合法且可读的分隔符。与之对应的还有 camelCase（驼峰式，如 circularAvatar，常用于 JavaScript 变量和函数名）、PascalCase（帕斯卡式，如 CircularAvatar，常用于组件名和类名）以及 snake_case（蛇形式，如 circular_avatar，常用于 Python 和数据库字段）。在本文的命令中，分支名使用 kebab-case 而组件文件名使用 camelCase，这体现了对不同上下文命名约定的尊重。

命令中使用 git switch -c 而非传统的 git checkout -b，是因为 Git 2.23 版本（2019 年发布）引入了 switch 命令，专门用于分支操作，语义更加清晰。传统的 checkout 命令身兼数职（切换分支、恢复文件等），容易造成混淆，而 switch 和 restore 的分离使得每个命令的职责更加单一明确。在团队协作中，常见的分支前缀包括 feature/（新功能）、bugfix/（缺陷修复）、hotfix/（紧急修复）、release/（发布准备）等。这种命名约定不仅提高了分支列表的可读性，还能配合 Git 钩子（hooks）和 CI/CD 管道实现自动化——例如，以 component/ 开头的分支可以自动触发组件库的构建和视觉回归测试。

第四步至第六步：TDD 测试驱动开发流程

这部分体现了 TDD（测试驱动开发）的核心思想：

1. 先写测试：在测试目录中编写一套有意义的测试用例，但暂不运行
2. 再写组件：在 components 目录中创建组件文件，命名采用 camelCase，与项目现有约定保持一致
3. 运行测试验证：执行测试确保全部通过；如果有失败的用例，修复组件后重新运行，直到全部通过

TDD（Test-Driven Development，测试驱动开发）是 Kent Beck 在 2003 年系统化提出的软件开发方法论，其核心循环为"红-绿-重构"：先编写一个必然失败的测试（红），再编写最少量的代码使测试通过（绿），最后重构代码消除重复和改善设计。TDD 的价值不仅在于提高代码覆盖率，更在于它迫使开发者在编码前先思考接口设计和预期行为。在 AI 辅助编程场景中，让模型遵循 TDD 流程尤为重要——测试用例充当了对生成代码的自动化验证机制，有效防止 AI 产生看似合理但实际有缺陷的代码。当模型先写测试再写实现时，测试本身就定义了"正确"的标准，模型生成的代码必须通过这些测试才算完成，这比单纯依赖模型的"自信"要可靠得多。

第七步：预览与总结

所有测试通过后，将组件的示例渲染到预览页面，方便在浏览器中直接查看效果。最后向用户简要总结所完成的工作。

命令执行演示与效果验证

验证安全检查是否生效

创建命令后，需要退出当前 Gemini 会话（使用 /quit）并重新启动，新命令才会被加载。

为了测试安全检查机制，先在项目中制造一个未提交的更改（比如修改 README 文件），然后执行命令：

/component a circular avatar component which takes in an initial prop and a bg color prop which should be limited to a few color choices

Gemini 首先请求运行 git status，检测到未提交的更改后立即中止流程，并提示用户先提交或暂存更改。这正是提示词中设定的预期行为。

完整执行流程

提交更改后再次执行命令（可以用上下箭头键快速调出历史命令），这次 Gemini 会依次完成所有步骤：

1. 运行 git status 确认工作区干净
2. 创建并切换到 component/avatar 分支
3. 创建测试文件，包含多个测试用例
4. 创建 Avatar 组件代码
5. 运行测试确保全部通过
6. 在预览页面渲染组件示例
7. 输出工作总结

自动生成的代码质量

来看看 Gemini 生成的代码效果：

测试文件包含四个测试用例：正确渲染 initials、应用正确的背景色、未提供颜色时使用默认值、验证允许的颜色列表。

组件文件定义了两个 props：initials（字符串类型）和 bgColor（限定为 red、blue、green、yellow、gray、purple 之一，默认值为 gray）。组件使用 computed 函数生成背景色 class，并对传入的颜色值进行校验。

样式文件自动添加了 .avatar 基础类和各颜色变体类。

预览页面展示了多种颜色变体的头像组件，涵盖单字母和双字母 initials 的情况，以及不传 bgColor 时的默认效果。

编写高质量自定义命令的6个最佳实践

通过这个实战案例，可以总结出以下几个关键要点：

1. 加入安全防护：在执行破坏性操作前检查环境状态，避免意外损失。这一原则在 DevOps 领域被称为"防御性编程"（Defensive Programming），同样适用于提示词设计——永远假设执行环境可能处于非预期状态。
2. 步骤清晰明确：用编号列表组织指令，每一步的预期行为都写清楚。大语言模型在处理结构化指令时的遵从度远高于模糊的自然语言描述，编号列表还能帮助模型维持执行顺序，避免跳步或乱序。
3. 善用 {{args}} 参数：让命令具备灵活性，通过参数适应不同使用场景
4. 强调边界条件：重要的约束条件可以多次强调（如本例中反复提及"检测到未提交更改则中止"）。研究表明，在提示词中重复关键约束可以显著降低模型忽略该约束的概率，这在长提示词中尤为重要。
5. 包含验证环节：让模型自行验证输出质量（如运行测试），而不是盲目生成代码。这种"生成-验证-修复"的闭环模式是当前 AI 编程工具提升可靠性的核心策略，也是 Agentic AI（智能体 AI）区别于简单问答式 AI 的关键特征。
6. 要求总结反馈：让模型在完成后汇报所做的工作，便于用户确认结果

自定义命令把开发经验和最佳实践编码化，每次执行都能保证一致的流程和质量标准。无论是组件生成、代码审查还是部署流程，都可以通过这种方式实现自动化，切实提升日常开发效率。从更宏观的角度看，这种将领域知识封装为可执行提示词的做法，代表了 AI 工具从"通用助手"向"领域专家"演进的趋势——通过积累和复用高质量的提示词模板，团队可以逐步构建起自己的 AI 自动化知识库。

核心要点

• Gemini CLI 支持通过 .gemini/commands/ 目录下的 .toml 文件创建自定义斜杠命令，文件名即为命令名
• 自定义命令的 prompt 中可使用 {{args}} 语法捕获用户输入的参数，实现灵活的命令定制
• 本教程演示的组件生成命令包含完整的 TDD 流程：安全检查→分支管理→编写测试→创建组件→运行验证→预览展示
• 编写高质量自定义命令的关键在于：加入安全防护、步骤清晰明确、包含自动验证环节、要求完成后总结反馈
• 自定义命令将开发最佳实践固化为可复用的自动化流程，每次执行都能保持一致的质量标准