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.mdPR 准备清单和 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-toolsBash(git add:*)、Bash(git status:*)、Bash(git commit:*)、Bash(git diff:*)命令执行期间无需额外授权提示即可调用的工具白名单argument-hint[message]在/自动补全菜单中显示参数提示暗示可传入提交信息descriptionコンテキスト付きで git コミットを作成する命令用途说明对应英文源文件的Create a git commit with contextallowed-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。执行时序如下!git status → 注入当前暂存区与工作区状态!git diff HEAD → 注入相对 HEAD 的未提交差异全文这是提交信息的主要依据英文源文件用git diff HEAD而 ja/01-slash-commands/README.md 中的 commit 示例使用git diff HEAD与git log --oneline -5本文件取 10 条最近提交上下文更充分!git branch --show-current → 注入当前分支名让 Claude 知道提交落在哪个分支!git log --oneline -10 → 注入最近 10 条提交的一行式摘要用于对齐团队既有的提交风格与信息粒度。这四个命令恰好与 frontmatter 白名单形成呼应前三者status、diff、branch中有两条需要免授权git status:*、git diff:*第四条git log不在白名单内从命令文件结构看它属于上下文注入阶段的只读查询注入动作发生在提示词构建时而git add、git commit则留给任务执行阶段。这种注入期查询 执行期变更的分工是理解该命令的关键。2.3 タスク 小节参数分支与 Conventional Commits 约束任务定义只有三条规则基于注入的上下文创建单个 git 提交——単一single是显式约束防止 Claude 把一批混杂变更拆成多个提交若通过参数提供了消息则直接使用$ARGUMENTS是占位符调用/commit fix: handle null user in auth时$ARGUMENTS会被替换为fix: handle null user in authClaude 原样采用argument-hint: [message]中的方括号表示参数可选未提供参数时分析变更并按 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的完整执行路径为用户输入/commit [message]Claude Code 在.claude/skills/与.claude/commands/中查找同名定义同名时技能优先解析 frontmatter建立工具白名单依次执行四条!git ...命令收集输出并内联到提示词替换$ARGUMENTS有参则用用户消息无参则留空触发自行分析分支组装后的完整提示词发送模型模型按タスク 小节执行git addgit 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考