Claude Code /commit 命令实战：claude-howto 中基于动态上下文注入的 Conventional Commits 自动化提交指南

Claude Code /commit 命令实战：claude-howto 中基于动态上下文注入的 Conventional Commits 自动化提交指南

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

本文基于 claude-howto 仓库的 commit.md（日文版，其英文源文件为 01-slash-commands/commit.md）展开，讲透这个「带上下文的 git 提交」斜杠命令的完整实现：如何仅用一个 Markdown 文件，通过 frontmatter 权限声明、!`command`动态上下文注入和$ARGUMENTS参数替换三大机制，让 Claude Code 在提交前自动读取仓库实时状态，并按 Conventional Commits 规范生成提交信息。读完本文，你可以将该命令直接安装到自己的项目（技能或传统命令两种方式），并理解其背后的命令生命周期与安全边界。

一、/commit 命令定位：解决"无上下文提交"痛点

Claude Code 的自定义斜杠命令已并入技能体系：.claude/commands/下的传统命令文件仍可工作，但官方推荐方式是.claude/skills/<name>/SKILL.md。在 claude-howto 的 斜杠命令目录 中，/commit被列为八个示例命令之一，定位是「コンテキスト付きで git コミットを作成する」（创建带上下文的 git 提交）：它不是简单地把一条固定提示词丢给模型，而是在提示词真正送达模型之前，先把仓库的实时 git 状态"拍照"注入进来。

这与 pr.md（PR 准备清单）和 push-all.md（暂存、提交、推送全流程）同属"git 工作流"命令族，但/commit是三者中边界最小、副作用最克制的一个：它只做"分析变更 + 生成一条提交信息 + 创建一次提交"，不包含git push权限，也不做强制确认流程。

二、完整命令文件逐行解析

下面展示 ja/01-slash-commands/commit.md 的完整正文（去掉 i18n 元信息注释后与英文源文件一致）：

--- allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*) argument-hint: [message] description: コンテキスト付きで git コミットを作成する --- ## コンテキスト - 現在の git ステータス: !`git status` - 現在の git 差分: !`git diff HEAD` - 現在のブランチ: !`git branch --show-current` - 直近のコミット: !`git log --oneline -10` ## タスク 上記の変更内容に基づいて、単一の git コミットを作成する。 引数でメッセージが指定された場合はそれを使う: $ARGUMENTS そうでない場合は、変更内容を分析し、Conventional Commits 形式に従って適切なコミットメッセージを作成する: - `feat:` 新機能 - `fix:` バグ修正 - `docs:` ドキュメント変更 - `refactor:` コードのリファクタリング - `test:` テスト追加 - `chore:` メンテナンスタスク

整个文件可以分为三层：权限层（frontmatter）、上下文层（Context 小节）、任务层（タスク 小节）。下面逐层拆解。

2.1 frontmatter：最小权限声明

字段	取值	作用
allowed-tools	Bash(git add:*)、Bash(git status:*)、Bash(git commit:*)、Bash(git diff:*)	命令执行期间无需额外授权提示即可调用的工具白名单
argument-hint	[message]	在/自动补全菜单中显示参数提示，暗示可传入提交信息
description	コンテキスト付きで git コミットを作成する	命令用途说明（对应英文源文件的Create a git commit with context）

allowed-tools的设计值得注意：白名单里只有四条git子命令，且每条用:*通配参数。这意味着该命令执行时，Claude 免确认能做的只有暂存（git add）、查看状态与差异（git status/git diff）和提交（git commit）——没有git push，没有git reset，也没有任何非 git 命令。这与 03-skills 指南中 frontmatter 参考表对allowed-tools的定义一致：「許可プロンプトなしでスキルが利用可能なツールのカンマ区切りリスト」（无需权限提示即可使用的工具逗号分隔列表）。

对比同目录的 push-all.md 可以看到边界差异：/push-all的白名单额外包含Bash(git push:*)、Bash(git log:*)、Bash(git pull:*)，并在正文中要求检测到密钥文件时 STOP、提交前显式等待用户输入yes。/commit由于不触及远程仓库，权限面被刻意收窄到最小集。

2.2 Context 小节：!`command`动态上下文注入

命令正文的四个列表项使用了 Claude Code 的动态上下文注入语法：

- 現在の git ステータス: !`git status` - 現在の git 差分: !`git diff HEAD` - 現在のブランチ: !`git branch --show-current` - 直近のコミット: !`git log --oneline -10`

!`command`的语义是：在技能/命令内容送达 Claude 之前，先在 shell 中执行该命令，并把其输出原地替换到提示词中（默认使用bash执行，可通过 frontmatter 的shell字段切换为powershell）。执行时序如下：

1. !git status`` → 注入当前暂存区与工作区状态；
2. !git diff HEAD`` → 注入相对 HEAD 的未提交差异全文（这是提交信息的主要依据，英文源文件用git diff HEAD，而 ja/01-slash-commands/README.md 中的 commit 示例使用git diff HEAD与git log --oneline -5，本文件取 10 条最近提交，上下文更充分）；
3. !git branch --show-current`` → 注入当前分支名，让 Claude 知道提交落在哪个分支；
4. !git log --oneline -10`` → 注入最近 10 条提交的一行式摘要，用于对齐团队既有的提交风格与信息粒度。

这四个命令恰好与 frontmatter 白名单形成呼应：前三者（status、diff、branch）中有两条需要免授权（git status:*、git diff:*），第四条git log不在白名单内，从命令文件结构看，它属于上下文注入阶段的只读查询，注入动作发生在提示词构建时；而git add、git commit则留给任务执行阶段。这种"注入期查询 + 执行期变更"的分工，是理解该命令的关键。

2.3 タスク 小节：参数分支与 Conventional Commits 约束

任务定义只有三条规则：

1. 基于注入的上下文创建"单个" git 提交——"単一"（single）是显式约束，防止 Claude 把一批混杂变更拆成多个提交；
2. 若通过参数提供了消息，则直接使用：$ARGUMENTS是占位符，调用/commit fix: handle null user in auth时，$ARGUMENTS会被替换为fix: handle null user in auth，Claude 原样采用；argument-hint: [message]中的方括号表示参数可选；
3. 未提供参数时，分析变更并按 Conventional Commits 格式生成消息，类型限定为六种：

前缀	适用场景
feat:	新功能
fix:	缺陷修复
docs:	文档变更
refactor:	代码重构
test:	测试新增
chore:	维护性任务

这与 pr.md 第 5 步的提交信息规范完全一致（两者共享同一套类型表），也覆盖了 push-all.md 扩展列表（feat/fix/docs/style/refactor/test/chore/perf/build/ci）中的核心子集。选择收窄到六种，是因为/commit只处理"本次工作区变更"这一单一场景，六种类型足以覆盖日常提交。

三、命令执行生命周期

结合 ja/01-slash-commands/README.md 中的「コマンドのライフサイクル」时序图，/commit的完整执行路径为：

1. 用户输入/commit [message]，Claude Code 在.claude/skills/与.claude/commands/中查找同名定义（同名时技能优先）；
2. 解析 frontmatter，建立工具白名单；
3. 依次执行四条!`git ...`命令，收集输出并内联到提示词；
4. 替换$ARGUMENTS（有参则用用户消息，无参则留空触发"自行分析"分支）；
5. 组装后的完整提示词发送模型，模型按タスク 小节执行git add+git commit，白名单内的调用不触发权限弹窗。

四、安装方式：技能（推荐）与传统命令

两种安装方式来自 ja/01-slash-commands/README.md 的「インストール」章节，命令文件内容完全相同，只是落盘位置不同。

方式一：作为技能安装（当前标准）

mkdir -p .claude/skills/commit # 将仓库中的 commit.md 复制为 SKILL.md

即把 01-slash-commands/commit.md 的内容放入.claude/skills/commit/SKILL.md。技能方式的额外收益：可将脚本、模板等配套文件放进技能目录、支持context: fork隔离执行、支持按paths限制触发范围。

方式二：作为传统命令安装

# 项目级（团队共享，随仓库提交） mkdir -p .claude/commands # 将 01-slash-commands/commit.md 复制到 .claude/commands/commit.md # 个人级（仅本机生效） mkdir -p ~/.claude/commands

两种位置的项目级安装均建议放入团队仓库，使整个团队获得一致的提交信息规范。

五、纵深扩展：与 pre-commit 钩子配合构成提交门禁

单靠提示词约束，Claude 仍可能在测试失败时提交。claude-howto 仓库提供了一个可落地的补强手段：ja/06-hooks/pre-commit.sh——一个 PreToolUse 钩子（matcher: Bash），其逻辑是：

• 当 Claude 即将执行git commit类命令时，按项目类型（Node.js / Python / Go / Rust）分别运行npm test、pytest、go test ./...、cargo test；
• 测试失败时exit 2阻断本次工具调用，stderr 作为阻断理由回传给模型；
• 脚本注释明确强调：退出码 2 才会真正 block，其他非零值只是"不阻断的错误"，提交会照常继续。

将/commit（智能生成提交信息）与pre-commit.sh（测试门禁）组合，就得到"信息质量 + 代码质量"双保障的提交流水线：前者保证写出来的提交信息符合规范，后者保证提交进来的代码通过测试。

六、最佳实践与常见故障

以下要点来自 ja/01-slash-commands/README.md 的「ベストプラクティス」与「トラブルシューティング」章节，结合/commit场景归纳：

做	不做
动态上下文用!前缀显式注入	假设 Claude 已经知道当前仓库状态
有副作用的命令收敛权限（如本例仅四条 git 命令）	在白名单里放宽泛的Bash(git *)
单一任务聚焦（只提交，不推送）	在一个命令里塞入暂存、提交、推送、通知等复合逻辑

命令不生效时：确认文件位于.claude/skills/commit/SKILL.md或.claude/commands/commit.md；确认 frontmatter 的name（若显式给出）与目录名/文件名一致；重启会话后用/help查看可用命令。

执行不符合预期时：检查allowed-tools是否覆盖了实际要执行的 bash 命令；先用简单变更（如一次docs:级修改）验证流程。

提交分支选择：/commit注入的git branch --show-current让 Claude 知晓当前分支，但它不会主动拒绝在main/master上提交——这与 push-all.md 中"正确分支（main/master 给出警告）"的检查形成对比，因此在主干分支上使用/commit前，建议自行确认分支策略。

七、小结

claude-howto 的/commit命令是一个结构极简但机制完整的模板：frontmatter 声明最小工具权限 →!`command`在提示词送达前注入git status/git diff HEAD/当前分支/最近 10 条提交四类实时上下文 → 任务层按"参数优先、否则按 Conventional Commits 六种类型自拟"的规则生成单次提交。它没有硬编码任何逻辑，全部"智能"来自对动态上下文与占位符替换机制的编排，这正是 Claude Code 命令/技能体系的设计哲学：用声明式 Markdown 描述工作流，让权限、上下文、参数三者在执行前就被精确约束。相关文件可继续参阅 ja/01-slash-commands/commit.md、01-slash-commands/commit.md、ja/03-skills/README.md 与 ja/06-hooks/README.md。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto