用 ship 命令统一 Git 工作流：从分支创建到 Pull Request 提交的完整实践（openstatus 仓库示例）

用 ship 命令统一 Git 工作流从分支创建到 Pull Request 提交的完整实践openstatus 仓库示例【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatus导读本文以 openstatus 仓库中的 Claude Code slash command 定义文件 .claude/commands/ship.md 为主体系统讲解如何将一个从新建分支、格式检查、规范提交到推送并创建 Pull Request的完整提交流程封装为一条可复用的命令。读完本文你将掌握该类命令文件的 frontmatter 结构、git/gh 命令行自动化要点、Conventional Commits 消息规范以及如何将这一工作流与 openstatus 这类 pnpm turbo 管理的 monorepo 工程实践相结合。一、ship 命令是什么一条命令走完整个提交流程ship是 Claude Code 的 slash command斜杠命令其description字段明确定义了它的职责Create a new git branch, commit changes, and create a pull request即创建新分支 → 提交变更 → 创建 Pull Request。在 Claude Code 交互环境中开发者只需在对话中调用该命令AI 便会按照文档中固化的流程逐步执行把原本分散在多个终端步骤中的操作收敛为一次命令调用。该文件由两部分组成YAML frontmatter文件头部的---包裹区域提供命令的元数据description命令用途的简短说明供工具/Agent 识别调用意图allowed-tools声明允许使用的工具白名单此处限定为Bash(git:*)与Bash(gh:*)即只允许执行 git 与 GitHub CLI 相关命令从工具层面收紧权限边界防止 AI 在提交流程中越权操作。Markdown 正文即命令的执行脚本# Current Git State通过!前缀将命令输出动态注入文档让 AI 在执行前自动获知当前分支git branch --show-current、工作区状态git status --porcelain与最近提交记录git log --oneline -5# Arguments声明命令可选的$ARGUMENTS参数即用户可显式传入分支名# Workflow分步执行的完整流程# Error Handling失败时的兜底策略。这种frontmatter 描述意图 正文固化流程 动态命令注入的结构是 Claude Code slash command 的典型写法任何仓库都可以参照它定制自己的提交流程。二、Step 1提交前的校验Validate命令执行的第一步是先验证、后动手共包含四项检查确认存在未提交变更依据上方注入的git status --porcelain输出判断若无任何变更流程立即终止避免产生空提交或空 PR。确认当前分支若当前不在main分支上需先征询用户同意再继续。这一设计避免在特性分支上误开新分支也避免污染他人正在协作的分支。警告敏感文件若工作区中会出现.env或凭据类文件被暂存的情况必须显式提示。这对应仓库安全实践——openstatus 根目录下确实存在 env.ts、各子包中的env.ts以及.env类配置文件提交流程对这类文件保持敏感是必要的。运行格式修复在仓库根目录执行pnpm format:fix保证提交的代码通过工程统一格式。关于第 4 点结合 openstatus 根目录的 package.json 可以看出该工程的格式化工具链项目使用oxfmt格式化与oxlintlint双工具脚本定义如下package.json 第 9-29 行lint: oxlint, lint:fix: oxlint --fix, format: oxfmt oxlint --fix, format:check: oxfmt --check oxlint, verify: pnpm format:check pnpm check:docs pnpm check注意当前仓库根脚本中并未定义format:fix而是将职责拆分为formatoxfmt oxlint --fix与lint:fixoxlint --fix。因此在 openstatus 中实际等价于格式化并修复的命令是pnpm format或pnpm lint:fixship命令中引用的pnpm format:fix属于通用的命令名约定。此外仓库还提供了verify这一提交前全量校验脚本依次执行格式检查、文档引用检查check-doc-refs.mts与全量 check是比单纯格式化更严格的落地门禁。三、Step 2创建分支Create Branch分支名优先使用调用者传入的$ARGUMENTS若未提供则由 AI 依据任务上下文自动生成并遵循两套命名规则Conventional 前缀feat/、fix/、chore/、refactor/、docs/kebab-case 命名单词间以短横线连接。随后执行git checkout -b branch-name分支名即元数据。前缀声明了本次变更的类型kebab-case 保证可读性与跨平台兼容性。对 openstatus 这种含apps/、packages/等多子包的 monorepo 来说规范的特性分支名还能与 turbo 的--affected等按变更范围筛选的能力配合参见根 package.json 中的verify:test脚本turbo run test --affected --concurrency1让 CI 更精准地只测试受影响的工作区。四、Step 3编写提交Commit提交环节是该命令的灵魂其核心原则是消息写在结果层outcome level而非实现层implementation level。命令要求 AI 先git diff通读全部变更再思考用户想达成什么目标、这个变更解决了什么问题最后起草提交消息。4.1 Conventional Commits 格式提交消息必须以feat:、fix:、chore:、docs:、refactor:等 Conventional Commits 前缀开头。文档给出了正反示例直观展示了结果层与实现层的差异反面实现层change timeout from 5000 to 10000 in checker/monitor.go正面结果层increase monitor check timeout to handle slow API responses前者罗列了文件和数值改动读者无法得知动机后者直接说明变更意图——提高监控检查超时以应对慢响应 API这正是该文档强调的Why优于What/Where。4.2 暂存与提交命令暂存时只选择与本次任务相关的文件明确排除.env与凭据文件提交使用 heredoc 格式保证多行消息与署名信息不被 shell 解释git commit -m $(cat EOF message Co-Authored-By: Claude Opus 4.6 noreplyanthropic.com EOF )heredoc 的EOF单引号形式可防止消息中的特殊字符被 shell 展开。提交完成后需执行git status验证提交是否成功。五、Step 4推送与创建 PRPush Create PR5.1 推送git push -u origin branch-name-u建立本地分支与远程分支的跟踪关系之后可直接git push推送。5.2 使用 gh CLI 创建 PRPR 的标题沿用提交消息的高层表述Summary 同样要求描述outcomes结果而非文件变更文档再次给出对照反面AddedgetMonitorStatus()to monitor.ts, updatedMonitortype正面Status pages now reflect real-time monitor degradation states创建命令同样采用 heredoc 传递多行正文gh pr create --title title --body $(cat EOF ## Summary - outcome 1 - outcome 2 Generated with Claude Code EOF )最终命令需要将生成的 PR URL 返回给调用者便于用户直接跳转评审。这种提交消息与 PR 描述同源的做法保证了 commit 与 PR 的叙事一致性评审者从标题到正文看到的是同一套结果导向的表达。六、错误处理失败即停命令的最后一部分是明确的失败策略If any step fails, report the error and stop. Dont proceed to the next step.即任何一步失败都应报告错误并停止绝不带病进入下一步。这个设计至关重要分支创建失败时强行提交、推送失败时强行建 PR都会把一次性问题升级为仓库状态污染而失败即停保证了整个流程的可重入性——修复问题后重新执行命令即可。七、在 openstatus 中落地该工作流的工程配套将 ship 命令放入仓库后它并非孤立存在而是与 openstatus 现有的工程设施形成配套包管理器与工具链仓库声明packageManager: pnpm12.3.4package.json并基于 turbo 构建build/dev/check均走turbo run格式化与 lint 由oxfmt、oxlint承担格式门禁提交前的pnpm format:fix在 openstatus 中对应 package.json 的format/lint:fix脚本与 CI 中的pnpm verifyformat:check check:docs check构成前后两道关卡确保本地与 CI 的格式判断一致monorepo 与 CI 联动ship 命令产生的规范前缀分支名配合turbo run test --affected可在 PR 阶段仅测试受变更影响的子包减少全量测试开销多语言子项目仓库同时包含 Go 探针apps/checker、apps/private-location各自维护justfile与go.mod与 TypeScript 应用apps/dashboard、apps/server等ship 命令只负责 git/gh 层面的流程编排不干预各子项目自身的构建工具因此对混合技术栈仓库同样适用。八、结语ship.md 的价值不在于命令本身有多复杂而在于它将提交质量这一工程共识固化成可重复、可审计的流程校验前置、分支规范、结果导向的提交消息、与 PR 叙事一致的描述以及失败即停的兜底策略。参照该文件的结构frontmatter 动态状态注入 分步 Workflow Error Handling任何团队都能在 Claude Code 中沉淀出符合自身规范分支命名、commit 前缀、PR 模板的提交流程命令让每次合并请求都自带清晰、一致的上下文。【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考