mcpField
G
git-best-practices

git-best-practices

github.com/alleneubank开发50261 次安装18 周前更新
代码仓库

关于 git-best-practices

git-best-practices 是一项为 Agent 的 Git 操作提供流程与安全规范的技能，适用于分支、提交、推送和 PR 工作。它涵盖分支发现、显式暂存、规范提交，以及改写历史和强制推送的保护步骤。

主要功能

  1. 01操作前发现分支结构
  2. 02按 Conventional Commits 编写提交
  3. 03按文件名显式暂存
  4. 04强制推送前征求确认
  5. 05使用 --force-with-lease 保护历史
  6. 06提供分支、合并与 PR 流程

适用场景

  1. 01为功能或修复创建分支
  2. 02准备整洁且可审查的提交
  3. 03在改写历史后安全推送
  4. 04创建含摘要和测试计划的 PR

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alleneubank/claude-code --skill git-best-practices

安装后在 Claude Code 中输入/git-best-practices确认已加载。

附带文件git-examples.md

详细介绍

Git 最佳实践

始终遵循的原则

加载此技能后，所有 Git 操作都必须遵循以下指令：

  1. 先发现，再行动 — 在创建分支、合并或开启 PR 之前，先运行分支发现命令，确定仓库的默认分支和生产分支
  2. 遵循 Conventional Commits — 每次提交都使用 type(scope): description 格式
  3. 明确暂存 — 按名称添加文件，确保只提交预期的更改
  4. 保护共享历史记录 — 强制推送时使用 --force-with-lease；进行任何强制推送前都必须先征得用户确认

Agent Git 工作流

  1. 检查状态 — 运行 git status 和 git diff HEAD
  2. 发现分支 — 确定默认分支、当前分支和（可选的）生产分支名称（参见“分支发现”）
  3. 按名称暂存 — 对每个文件运行 git add path/to/file；使用 git status 验证
  4. 编写 Conventional Commit — 使用 type(scope): description 格式，可添加正文
  5. 安全推送 — 默认进行常规推送；仅在用户确认后，对重写过的历史记录运行 git push --force-with-lease origin {branch}
检查点提交

Agent 可以在耗时较长的任务期间创建 WIP 检查点提交，并在创建 PR 前清理。

  • 使用 wip: 前缀或标准的 Conventional Commit 格式
  • 即使处于 WIP 状态，也要按逻辑分组更改
  • 开启 PR 前运行 /rewrite-history，整理出清晰的提交记录
提交规范
  • 按名称明确暂存文件：git add src/auth.ts src/auth.test.ts
  • 提交前使用 git status 验证已暂存的内容
  • 不要将密钥、.env 文件、凭据和大型二进制文件纳入提交；如果暂存文件看起来包含敏感内容，请提醒用户
  • 最终 PR 就绪状态下，每次提交只包含一项逻辑更改
强制推送

只能使用 --force-with-lease，以避免覆盖上游更改：

git push --force-with-lease origin feat/my-branch

无论针对哪个分支，任何强制推送前都必须先征得用户确认。

重设一组分支的基点

重设其他分支以某个分支为基础构建的分支基点时（例如分阶段的 NN-description 分支链），请使用 git rebase --update-refs，让后续分支跟随重写后的提交，而不是成为旧提交上的孤立分支。--update-refs 只会移动本地引用；移动过的分支如果也存在于远程，仍需在获得用户确认后分别使用 --force-with-lease 推送；而在其他工作树中已检出的分支则会跳过。有关完整的冲突解决和安全工作流，请使用 git-rebase-sync 技能。

Conventional Commits

格式：type(scope): description

主题行规则：

  • 使用小写和祈使语气，末尾不加句点
  • 少于 72 个字符
  • 范围可选；存在明确的子系统时，建议填写

常见类型：

类型用途
feat新增功能
fix修复错误
docs仅修改文档
refactor重构，不改变行为
perf提升性能
chore维护、依赖项、工具
test添加或更新测试
ciCI/CD 流水线更改
build构建系统更改
style格式、空白字符（不改变逻辑）
提交正文

正文为可选内容，仅在更改原因确实不明显时添加。主题行说明“做了什么”，正文解释“为什么”。

以下情况应添加正文：

  • 动机或权衡不明显
  • 多部分更改适合用项目符号列表说明
  • 需要外部上下文（链接、问题引用、根本原因）

有关提交消息示例，请参阅 git-examples.md。

分支发现

创建分支或开启 PR 之前，请先发现仓库的分支拓扑。运行以下命令并保存结果：

# Default branch (PR target for most repos)
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

# Current branch
git branch --show-current

# Production branch (if different from default)
git branch -r --list 'origin/main' 'origin/master' 'origin/production'

如果 gh 不可用或仓库没有远程，请参阅 git-examples.md 中的备用命令。

保存发现的分支名称，并在后续操作中引用。后续命令都要使用实际分支名称。

分支命名

优先遵循仓库的分支命名约定。如果未记录任何约定，请使用：

格式：type/description-TICKET-ID

示例：

  • feat/add-login-SEND-77
  • fix/pool-party-stall-SEN-68
  • chore/update-deps
  • hotfix/auth-bypass

存在问题单时，请包含问题单 ID。没有问题单时，请省略。

分支流程

优先遵循仓库的分支流程策略。如果未记录相关策略，常见的基准做法是：

{production-branch} (production deploys)
 └── {default-branch} (staging/testnet deploys, PR target)
      ├── feat/add-feature-TICKET
      ├── fix/bug-description-TICKET
      └── hotfix/* (branches off production branch for hotfixes)
  • 功能和修复分支从默认分支创建
  • 热修复分支从生产分支创建
  • 除非仓库采用单分支流程，否则 PR 以默认分支为目标
  • 默认分支和生产分支相同时，所有 PR 都直接以该分支为目标
合并策略

优先遵循仓库的合并策略（许多组织要求遵守）。

如果没有相关策略，以下默认做法较为合理：

PR 目标策略理由
功能分支 → 默认分支Squash 合并保持历史记录整洁，每项功能对应一个提交
默认分支 → 生产分支合并提交保留发布边界；部署节点清晰可见
热修复分支 → 生产分支Squash 合并在生产环境中进行单次原子修复

PR 工作流

规模

优先采用务实的规模划分，而非武断的限制。无论 PR 大小如何，每个提交都应表达清晰的内容。PR 应当作为一个完整单元便于审查——如果审查者无法在脑中把握完整的变更，请考虑拆分。

创建 PR

使用仓库原生的 PR 工具（gh pr create、GitLab CLI 或 Web UI），并包含：

  • 70 个字符以内的简短标题
  • 包含 1-3 个项目符号的摘要部分
  • 以项目符号清单形式列出的测试计划
创建 PR 前重写历史记录

对于包含杂乱 WIP 历史记录的分支，使用 /rewrite-history 来：

  1. 备份分支
  2. 重置到基分支的最新提交
  3. 将变更重新提交为清晰连贯的序列
  4. 验证与备份逐字节一致
  5. 在强制推送重写后的历史记录前征得用户确认
  6. 打开 PR，并附上备份分支的链接

每个重写后的提交都引入一个连贯的想法，并以前一个提交为基础逐步构建——就像教程一样，带领读者了解功能的构建过程。

评论

支持 Markdown