commit-hygiene

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Commit Hygiene Skill

Git提交规范技能

Load with: base.md

Purpose: Keep commits atomic, PRs reviewable, and git history clean. Advise when it's time to commit before changes become too large.

加载依赖：base.md

目的： 保持commit原子化、PR易于评审，以及git历史记录整洁。在变更内容过大前提醒用户进行提交。

Core Philosophy

核心原则

┌─────────────────────────────────────────────────────────────────┐
│  ATOMIC COMMITS                                                  │
│  ─────────────────────────────────────────────────────────────  │
│  One logical change per commit.                                  │
│  Each commit should be self-contained and deployable.            │
│  If you need "and" to describe it, split it.                     │
├─────────────────────────────────────────────────────────────────┤
│  SMALL PRS WIN                                                   │
│  ─────────────────────────────────────────────────────────────  │
│  < 400 lines changed = reviewed in < 1 hour                      │
│  > 1000 lines = likely rubber-stamped or abandoned               │
│  Smaller PRs = faster reviews, fewer bugs, easier reverts        │
├─────────────────────────────────────────────────────────────────┤
│  COMMIT EARLY, COMMIT OFTEN                                      │
│  ─────────────────────────────────────────────────────────────  │
│  Working code? Commit it.                                        │
│  Test passing? Commit it.                                        │
│  Don't wait for "done" - commit at every stable point.           │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  ATOMIC COMMITS                                                  │
│  ─────────────────────────────────────────────────────────────  │
│  每个commit对应一个逻辑变更。                                  │
│  每个commit应该是独立且可部署的。            │
│  如果需要用“和”来描述变更内容，就拆分它。                     │
├─────────────────────────────────────────────────────────────────┤
│  SMALL PRS WIN                                                   │
│  ─────────────────────────────────────────────────────────────  │
│  变更行数<400行 = 评审时间<1小时                      │
│  变更行数>1000行 = 可能会被草率批准或搁置               │
│  PR越小，评审速度越快，bug越少，回滚越容易        │
├─────────────────────────────────────────────────────────────────┤
│  COMMIT EARLY, COMMIT OFTEN                                      │
│  ─────────────────────────────────────────────────────────────  │
│  代码能运行了？Commit它。                                        │
│  测试通过了？Commit它。                                        │
│  不要等到“完全完成”——在每个稳定节点进行commit。           │
└─────────────────────────────────────────────────────────────────┘

Commit Size Thresholds

提交大小阈值

Warning Thresholds (Time to Commit!)

预警阈值（该提交了！）

Metric	Yellow Zone	Red Zone	Action
Files changed	5-10 files	> 10 files	Commit NOW
Lines added	150-300 lines	> 300 lines	Commit NOW
Lines deleted	100-200 lines	> 200 lines	Commit NOW
Total changes	250-400 lines	> 400 lines	Commit NOW
Time since last commit	30-60 min	> 60 min	Consider committing

指标	黄色预警区	红色预警区	操作建议
变更文件数	5-10个文件	>10个文件	立即Commit
新增行数	150-300行	>300行	立即Commit
删除行数	100-200行	>200行	立即Commit
总变更行数	250-400行	>400行	立即Commit
距离上次提交的时间	30-60分钟	>60分钟	考虑进行提交

Ideal Commit Size

理想的提交大小

┌─────────────────────────────────────────────────────────────────┐
│  IDEAL COMMIT                                                    │
│  ─────────────────────────────────────────────────────────────  │
│  Files: 1-5                                                      │
│  Lines: 50-200 total changes                                     │
│  Scope: Single logical unit of work                              │
│  Message: Describes ONE thing                                    │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  IDEAL COMMIT                                                    │
│  ─────────────────────────────────────────────────────────────  │
│  文件数：1-5个                                                      │
│  行数：总变更50-200行                                     │
│  范围：单一逻辑工作单元                              │
│  提交信息：仅描述一项内容                                    │
└─────────────────────────────────────────────────────────────────┘

Check Current State (Run Frequently)

检查当前状态（定期运行）

Quick Status Check

快速状态检查

bash

undefined

bash

undefined

See what's changed (staged + unstaged)

查看变更内容（已暂存+未暂存）

git status --short

Count files and lines changed

统计变更文件数和行数

git diff --stat git diff --cached --stat # Staged only

git diff --stat git diff --cached --stat # 仅查看已暂存内容

Get totals

获取总计数据

git diff --shortstat

Example output: 8 files changed, 245 insertions(+), 32 deletions(-)

示例输出：8 files changed, 245 insertions(+), 32 deletions(-)

undefined

undefined

Detailed Change Analysis

详细变更分析

bash

undefined

bash

undefined

Full diff summary with file names

包含文件名的完整差异摘要

git diff --stat HEAD

Just the numbers

仅获取数值统计

git diff --numstat HEAD | awk '{add+=$1; del+=$2} END {print "+"add" -"del" total:"add+del}'

Files changed count

变更文件数统计

git status --porcelain | wc -l

undefined

git status --porcelain | wc -l

undefined

Pre-Commit Check Script

提交前检查脚本

bash

#!/bin/bash

bash

#!/bin/bash

scripts/check-commit-size.sh

Thresholds

阈值设置

MAX_FILES=10 MAX_LINES=400 WARN_FILES=5 WARN_LINES=200

Get stats

获取统计数据

FILES=$(git status --porcelain | wc -l | tr -d ' ') STATS=$(git diff --shortstat HEAD 2>/dev/null) INSERTIONS=$(echo "$STATS" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo 0) DELETIONS=$(echo "$STATS" | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo 0) TOTAL=$((INSERTIONS + DELETIONS))

echo "📊 Current changes: $FILES files, +$INSERTIONS -$DELETIONS ($TOTAL total lines)"

echo "📊 当前变更：$FILES个文件，+$INSERTIONS -$DELETIONS（总计$TOTAL行）"

Check thresholds

检查阈值

if [ "$FILES" -gt "$MAX_FILES" ] || [ "$TOTAL" -gt "$MAX_LINES" ]; then echo "🔴 RED ZONE: Commit immediately! Changes are too large." echo " Consider splitting into multiple commits." exit 1 elif [ "$FILES" -gt "$WARN_FILES" ] || [ "$TOTAL" -gt "$WARN_LINES" ]; then echo "🟡 WARNING: Changes getting large. Commit soon." exit 0 else echo "🟢 OK: Changes are within healthy limits." exit 0 fi

---

if [ "$FILES" -gt "$MAX_FILES" ] || [ "$TOTAL" -gt "$MAX_LINES" ]; then echo "🔴 红色预警区：立即提交！变更内容过大。" echo " 建议拆分为多个commit。" exit 1 elif [ "$FILES" -gt "$WARN_FILES" ] || [ "$TOTAL" -gt "$WARN_LINES" ]; then echo "🟡 警告：变更内容正在变大，请尽快提交。" exit 0 else echo "🟢 正常：变更内容在健康范围内。" exit 0 fi

---

When to Commit

提交时机

Commit Triggers (Any One = Commit)

提交触发条件（满足任意一项即可提交）

Trigger	Example
Test passes	Just got a test green → commit
Feature complete	Finished a function → commit
Refactor done	Renamed variable across files → commit
Bug fixed	Fixed the issue → commit
Before switching context	About to work on something else → commit
Clean compile	Code compiles/lints clean → commit
Threshold hit	> 5 files or > 200 lines → commit

触发条件	示例
测试通过	刚让一个测试用例通过 → 提交
功能完成	完成一个函数开发 → 提交
重构完成	跨文件重命名变量 → 提交
Bug修复完成	修复了问题 → 提交
切换工作内容前	即将开始其他工作 → 提交
编译/检查通过	代码编译/代码检查无问题 → 提交
达到阈值	变更>5个文件或>200行 → 提交

Commit Immediately If

立即提交的场景

✅ Tests are passing after being red
✅ You're about to make a "big change"
✅ You've been coding for 30+ minutes
✅ You're about to try something risky
✅ The current state is "working"

✅ 测试从失败变为通过
✅ 即将进行“重大变更”
✅ 编码已超过30分钟
✅ 即将尝试有风险的改动
✅ 当前代码状态“可正常运行”

Don't Wait For

无需等待的场景

❌ "Perfect" code
❌ All features done
❌ Full test coverage
❌ Code review from yourself
❌ Documentation complete

❌ “完美”代码
❌ 所有功能全部完成
❌ 完整的测试覆盖率
❌ 自我代码评审完成
❌ 文档编写完成

Atomic Commit Patterns

原子提交模式

Good Atomic Commits

良好的原子提交示例

✅ "Add email validation to signup form"
   - 3 files: validator.ts, signup.tsx, signup.test.ts
   - 120 lines changed
   - Single purpose: email validation

✅ "Fix null pointer in user lookup"
   - 2 files: userService.ts, userService.test.ts
   - 25 lines changed
   - Single purpose: fix one bug

✅ "Refactor: Extract PaymentProcessor class"
   - 4 files: payment.ts → paymentProcessor.ts + types
   - 180 lines changed
   - Single purpose: refactoring

✅ "Add email validation to signup form"
   - 3个文件：validator.ts, signup.tsx, signup.test.ts
   - 变更120行
   - 单一目的：邮箱验证

✅ "Fix null pointer in user lookup"
   - 2个文件：userService.ts, userService.test.ts
   - 变更25行
   - 单一目的：修复一个Bug

✅ "Refactor: Extract PaymentProcessor class"
   - 4个文件：payment.ts → paymentProcessor.ts + types
   - 变更180行
   - 单一目的：代码重构

Bad Commits (Too Large)

不良提交示例（过大）

❌ "Add authentication, fix bugs, update styles"
   - 25 files changed
   - 800 lines changed
   - Multiple purposes mixed

❌ "WIP"
   - Unknown scope
   - No clear purpose
   - Hard to review/revert

❌ "Updates"
   - 15 files changed
   - Mix of features, fixes, refactors
   - Impossible to review properly

❌ "Add authentication, fix bugs, update styles"
   - 变更25个文件
   - 变更800行
   - 混合多个目的

❌ "WIP"
   - 范围不明确
   - 无清晰目的
   - 难以评审/回滚

❌ "Updates"
   - 变更15个文件
   - 混合功能、修复、重构
   - 无法正常评审

Splitting Large Changes

拆分大型变更

Strategy 1: By Layer

策略1：按分层拆分

Instead of one commit with:
  - API endpoint + database migration + frontend + tests

Split into:
  1. "Add users table migration"
  2. "Add User model and repository"
  3. "Add GET /users endpoint"
  4. "Add UserList component"
  5. "Add integration tests for user flow"

不要用一个commit包含：
  - API端点 + 数据库迁移 + 前端 + 测试

拆分为：
  1. "Add users table migration"
  2. "Add User model and repository"
  3. "Add GET /users endpoint"
  4. "Add UserList component"
  5. "Add integration tests for user flow"

Strategy 2: By Feature Slice

策略2：按功能切片拆分

Instead of one commit with:
  - All CRUD operations for users

Split into:
  1. "Add create user functionality"
  2. "Add read user functionality"
  3. "Add update user functionality"
  4. "Add delete user functionality"

不要用一个commit包含：
  - 用户的所有CRUD操作

拆分为：
  1. "Add create user functionality"
  2. "Add read user functionality"
  3. "Add update user functionality"
  4. "Add delete user functionality"

Strategy 3: Refactor First

策略3：先重构再提交

Instead of:
  - Feature + refactoring mixed

Split into:
  1. "Refactor: Extract validation helpers" (no behavior change)
  2. "Add email validation using new helpers" (new feature)

不要：
  - 功能开发与重构混合

拆分为：
  1. "Refactor: Extract validation helpers"（无行为变更）
  2. "Add email validation using new helpers"（新功能）

Strategy 4: By Risk Level

策略4：按风险等级拆分

Instead of:
  - Safe changes + risky changes together

Split into:
  1. "Update dependencies" (safe, isolated)
  2. "Migrate to new API version" (risky, separate)

不要：
  - 安全变更与高风险变更混合

拆分为：
  1. "Update dependencies"（安全、独立）
  2. "Migrate to new API version"（高风险、独立）

PR Size Guidelines

PR大小指南

Optimal PR Size

最优PR大小

Metric	Optimal	Acceptable	Too Large
Files	1-10	10-20	> 20
Lines changed	50-200	200-400	> 400
Commits	1-5	5-10	> 10
Review time	< 30 min	30-60 min	> 60 min

指标	最优	可接受	过大
文件数	1-10	10-20	>20
变更行数	50-200	200-400	>400
Commit数	1-5	5-10	>10
评审时间	<30分钟	30-60分钟	>60分钟

PR Size vs Defect Rate

PR大小与缺陷率

┌─────────────────────────────────────────────────────────────────┐
│  RESEARCH FINDINGS (Google, Microsoft studies)                  │
│  ─────────────────────────────────────────────────────────────  │
│  PRs < 200 lines: 15% defect rate                               │
│  PRs 200-400 lines: 23% defect rate                             │
│  PRs > 400 lines: 40%+ defect rate                              │
│                                                                 │
│  Review quality drops sharply after 200-400 lines.              │
│  Large PRs get "LGTM" rubber stamps, not real reviews.          │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  研究结果（谷歌、微软研究）                  │
│  ─────────────────────────────────────────────────────────────  │
│  PR<200行：15%缺陷率                               │
│  PR 200-400行：23%缺陷率                             │
│  PR>400行：40%+缺陷率                              │
│                                                                 │
│  评审质量在200-400行后急剧下降。              │
│  大型PR会被“LGTM”草率批准，而非真正评审。          │
└─────────────────────────────────────────────────────────────────┘

When PR is Too Large

当PR过大时

bash

undefined

bash

undefined

Check PR size before creating

创建PR前检查大小

git diff main --stat git diff main --shortstat

If too large, consider:

如果过大，考虑：

1. Split into multiple PRs (stacked PRs)

1. 拆分为多个PR（堆叠式PR）

2. Create feature flag and merge incrementally

2. 使用功能标志并逐步合并

3. Use draft PR for early feedback

3. 创建草稿PR获取早期反馈

---

---

Commit Message Format

提交信息格式

Structure

结构

<type>: <description> (50 chars max)

[optional body - wrap at 72 chars]

[optional footer]

<类型>: <描述>（最多50字符）

[可选正文 - 每行不超过72字符]

[可选页脚]

Types

类型说明

Type	Use For
`feat`	New feature
`fix`	Bug fix
`refactor`	Code change that neither fixes nor adds
`test`	Adding/updating tests
`docs`	Documentation only
`style`	Formatting, no code change
`chore`	Build, config, dependencies

类型	适用场景
`feat`	新功能
`fix`	Bug修复
`refactor`	既非修复也非新增功能的代码变更
`test`	添加/更新测试
`docs`	仅变更文档
`style`	格式调整，无代码逻辑变更
`chore`	构建、配置、依赖更新

Examples

示例

feat: Add email validation to signup form

fix: Prevent null pointer in user lookup

refactor: Extract PaymentProcessor class

test: Add integration tests for checkout flow

chore: Update dependencies to latest versions

feat: Add email validation to signup form

fix: Prevent null pointer in user lookup

refactor: Extract PaymentProcessor class

test: Add integration tests for checkout flow

chore: Update dependencies to latest versions

Git Workflow Integration

Git工作流集成

Pre-Commit Hook for Size Check

提交前大小检查钩子

bash

#!/bin/bash

bash

#!/bin/bash

.git/hooks/pre-commit

MAX_LINES=400 MAX_FILES=15

FILES=$(git diff --cached --name-only | wc -l | tr -d ' ') STATS=$(git diff --cached --shortstat) INSERTIONS=$(echo "$STATS" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo 0) DELETIONS=$(echo "$STATS" | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo 0) TOTAL=$((INSERTIONS + DELETIONS))

if [ "$TOTAL" -gt "$MAX_LINES" ]; then echo "❌ Commit too large: $TOTAL lines (max: $MAX_LINES)" echo " Consider splitting into smaller commits." echo " Use 'git add -p' for partial staging." exit 1 fi

if [ "$FILES" -gt "$MAX_FILES" ]; then echo "❌ Too many files: $FILES (max: $MAX_FILES)" echo " Consider splitting into smaller commits." exit 1 fi

echo "✅ Commit size OK: $FILES files, $TOTAL lines"

undefined

MAX_LINES=400 MAX_FILES=15

if [ "$TOTAL" -gt "$MAX_LINES" ]; then echo "❌ 提交过大：$TOTAL行（最大值：$MAX_LINES）" echo " 考虑拆分为更小的commit。" echo " 使用'git add -p'进行部分暂存。" exit 1 fi

if [ "$FILES" -gt "$MAX_FILES" ]; then echo "❌ 文件过多：$FILES个（最大值：$MAX_FILES）" echo " 考虑拆分为更小的commit。" exit 1 fi

echo "✅ 提交大小正常：$FILES个文件，$TOTAL行"

undefined

Partial Staging (Split Large Changes)

部分暂存（拆分大型变更）

bash

undefined

bash

undefined

Stage specific hunks interactively

交互式暂存特定代码块

git add -p

Stage specific files

暂存特定文件

git add path/to/specific/file.ts

Stage with preview

带预览的暂存

git add -N file.ts # Intent to add git diff # See what would be added git add file.ts # Actually add

undefined

git add -N file.ts # 标记为待添加 git diff # 查看将被添加的内容 git add file.ts # 实际添加

undefined

Unstage If Too Large

取消暂存（如果过大）

bash

undefined

bash

undefined

Unstage everything

取消所有暂存

git reset HEAD

Unstage specific files

取消特定文件的暂存

git reset HEAD path/to/file.ts

Stage just what you need for THIS commit

仅暂存当前commit需要的内容

git add -p

---

git add -p

---

Claude Integration

Claude集成

Periodic Check During Development

开发期间定期检查

Claude should run this check after every significant change:

bash

undefined

Claude应在每次重大变更后运行此检查：

bash

undefined

Quick status

快速状态

git diff --shortstat HEAD


**Thresholds for Claude to advise committing:**

| Condition | Claude Action |
|-----------|---------------|
| > 5 files changed | Suggest: "Consider committing current changes" |
| > 200 lines changed | Suggest: "Changes are getting large, commit recommended" |
| > 10 files OR > 400 lines | Warn: "⚠️ Commit now before changes become unmanageable" |
| Test just passed | Suggest: "Good checkpoint - commit these passing tests" |
| Refactoring complete | Suggest: "Refactoring done - commit before adding features" |

git diff --shortstat HEAD


**Claude建议提交的阈值：**

| 条件 | Claude操作 |
|-----------|---------------|
| 变更>5个文件 | 建议：“考虑提交当前变更” |
| 变更>200行 | 建议：“变更内容正在变大，建议提交” |
| 变更>10个文件 或 >400行 | 警告：“⚠️ 立即提交，避免变更内容失控” |
| 测试刚通过 | 建议：“良好的检查点 - 提交这些通过的测试” |
| 重构完成 | 建议：“重构完成 - 添加新功能前先提交” |

Claude Commit Reminder Messages

Claude提交提醒消息示例

📊 Status: 7 files changed, +180 -45 (225 total)
💡 Approaching commit threshold. Consider committing current work.

---

📊 Status: 12 files changed, +320 -80 (400 total)
⚠️ Changes are large! Commit now to keep PRs reviewable.
   Suggested commit: "feat: Add user authentication flow"

---

📊 Status: 3 files changed, +85 -10 (95 total)
✅ Tests passing. Good time to commit!
   Suggested commit: "fix: Validate email format on signup"

📊 状态：7个文件变更，+180 -45（总计225行）
💡 接近提交阈值，考虑提交当前工作。

---

📊 状态：12个文件变更，+320 -80（总计400行）
⚠️ 变更内容过大！立即提交以保持PR可评审性。
   建议提交信息："feat: Add user authentication flow"

---

📊 状态：3个文件变更，+85 -10（总计95行）
✅ 测试通过，是提交的好时机！
   建议提交信息："fix: Validate email format on signup"

Stacked PRs (For Large Features)

堆叠式PR（针对大型功能）

When a feature is genuinely large, use stacked PRs:

┌─────────────────────────────────────────────────────────────────┐
│  STACKED PR PATTERN                                             │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  main ─────────────────────────────────────────────────────────│
│    └── PR #1: Database schema (200 lines) ← Review first       │
│         └── PR #2: API endpoints (250 lines) ← Review second   │
│              └── PR #3: Frontend (300 lines) ← Review third    │
│                                                                 │
│  Each PR is reviewable independently.                           │
│  Merge in order: #1 → #2 → #3                                   │
└─────────────────────────────────────────────────────────────────┘

当功能确实较大时，使用堆叠式PR：

┌─────────────────────────────────────────────────────────────────┐
│  堆叠式PR模式                                             │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  main ─────────────────────────────────────────────────────────│
│    └── PR #1: Database schema (200 lines) ← 优先评审       │
│         └── PR #2: API endpoints (250 lines) ← 其次评审   │
│              └── PR #3: Frontend (300 lines) ← 最后评审    │
│                                                                 │
│  每个PR均可独立评审。                           │
│  按顺序合并：#1 → #2 → #3                                   │
└─────────────────────────────────────────────────────────────────┘

Creating Stacked PRs

创建堆叠式PR

bash

undefined

bash

undefined

Create base branch

创建基础分支

git checkout -b feature/auth-schema

... make changes ...

... 进行变更 ...

git commit -m "feat: Add users table schema" git push -u origin feature/auth-schema gh pr create --base main --title "feat: Add users table schema"

Create next branch FROM the first

基于第一个分支创建下一个分支

git checkout -b feature/auth-api

... make changes ...

... 进行变更 ...

git commit -m "feat: Add authentication API endpoints" git push -u origin feature/auth-api gh pr create --base feature/auth-schema --title "feat: Add auth API endpoints"

And so on...

以此类推...

---

---

Checklist

检查清单

Before Every Commit

每次提交前

Before Creating PR

创建PR前

Red Flags (Stop and Split)

危险信号（停止并拆分）

❌ Commit message needs "and"
❌ > 10 files in one commit
❌ > 400 lines in one commit
❌ Mix of features, fixes, and refactors
❌ "I'll clean this up later"

❌ 提交信息需要用“和”连接
❌ 一个commit变更>10个文件
❌ 一个commit变更>400行
❌ 混合功能、修复和重构
❌ “我之后再清理”

Quick Reference

快速参考

Thresholds

阈值

Files:  ≤ 5 = 🟢  |  6-10 = 🟡  |  > 10 = 🔴
Lines:  ≤ 200 = 🟢  |  201-400 = 🟡  |  > 400 = 🔴
Time:   ≤ 30min = 🟢  |  30-60min = 🟡  |  > 60min = 🔴

文件数： ≤5个 = 🟢  |  6-10个 = 🟡  |  >10个 = 🔴
行数： ≤200行 = 🟢  |  201-400行 = 🟡  |  >400行 = 🔴
时间： ≤30分钟 = 🟢  |  30-60分钟 = 🟡  |  >60分钟 = 🔴

Commands

命令

bash

undefined

bash

undefined

Quick status

快速状态

git diff --shortstat HEAD

Detailed file list

详细文件列表

git diff --stat HEAD

Partial staging

部分暂存

git add -p

Check before PR

PR前检查

git diff main --shortstat

undefined

git diff main --shortstat

undefined

Commit Now If

立即提交的场景

✅ Tests just passed
✅ > 200 lines changed
✅ > 5 files changed
✅ About to switch tasks
✅ Current state is "working"

✅ 测试刚通过
✅ 变更>200行
✅ 变更>5个文件
✅ 即将切换任务
✅ 当前状态“可正常运行"