Commit Hygiene 指南：原子提交、PR审查与Git历史整洁的最佳实践

commit-hygiene by alinaqi/claude-bootstrap

141 周安装量

570 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/alinaqi/claude-bootstrap --skill commit-hygiene

开发代码规范版本控制

🇨🇳中文介绍

Commit Hygiene Skill

加载方式：base.md

目的： 保持提交的原子性、PR 的可审查性以及 git 历史的整洁。在变更变得过大之前，建议何时应该提交。

核心理念

┌─────────────────────────────────────────────────────────────────┐
│  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.           │
└─────────────────────────────────────────────────────────────────┘

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

警告阈值（是时候提交了！）

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

理想的提交大小

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

检查当前状态（经常运行）

# See what's changed (staged + unstaged)
git status --short

# Count files and lines changed
git diff --stat
git diff --cached --stat  # Staged only

# Get totals
git diff --shortstat
# Example output: 8 files changed, 245 insertions(+), 32 deletions(-)

# 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

提交前检查脚本

#!/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)"

# 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

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

触发条件	示例
测试通过	刚刚让一个测试变绿 → 提交
功能完成	完成了一个函数 → 提交
重构完成	跨文件重命名了变量 → 提交
Bug 修复	修复了问题 → 提交
切换上下文之前	即将处理其他事情 → 提交
编译/代码检查通过	代码编译/代码检查通过 → 提交
达到阈值	> 5 个文件或 > 200 行 → 提交

✅ 测试在失败后通过了
✅ 你即将进行一个"大改动"
✅ 你已经编码超过 30 分钟
✅ 你即将尝试一些有风险的操作
✅ 当前状态是"可工作的"

❌ "完美"的代码
❌ 所有功能完成
❌ 完整的测试覆盖率
❌ 来自你自己的代码审查
❌ 文档完成

良好的原子提交

✅ "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 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

策略 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"

策略 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"

策略 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)

策略 4：按风险级别拆分

Instead of:
  - Safe changes + risky changes together

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

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

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.          │
└─────────────────────────────────────────────────────────────────┘

# Check PR size before creating
git diff main --stat
git diff main --shortstat

# If too large, consider:
# 1. Split into multiple PRs (stacked PRs)
# 2. Create feature flag and merge incrementally
# 3. Use draft PR for early feedback

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

[optional body - wrap at 72 chars]

[optional footer]

类型	用于
`feat`	新功能
`fix`	Bug 修复
`refactor`	既不修复也不新增的代码变更
`test`	添加/更新测试
`docs`	仅文档
`style`	格式化，无代码变更
`chore`	构建、配置、依赖项

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

用于大小检查的预提交钩子

#!/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"

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

# 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

如果过大则取消暂存

# Unstage everything
git reset HEAD

# Unstage specific files
git reset HEAD path/to/file.ts

# Stage just what you need for THIS commit
git add -p

开发过程中的定期检查

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

# Quick status
git diff --shortstat HEAD

Claude 建议提交的阈值：

条件	Claude 操作

5 个文件变更 | 建议："考虑提交当前变更"
200 行变更 | 建议："变更正在变大，建议提交"
10 个文件或 > 400 行 | 警告："⚠️ 立即提交，以免变更变得难以管理"
测试刚刚通过 | 建议："好的检查点 - 提交这些通过的测试"
重构完成 | 建议："重构完成 - 在添加功能前提交"

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"

堆叠式 PR（用于大型功能）

当一个功能确实很大时，使用堆叠式 PR：

┌─────────────────────────────────────────────────────────────────┐
│  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                                   │
└─────────────────────────────────────────────────────────────────┘

# 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...

变更针对一个逻辑目的
测试通过（如果适用）
代码检查/类型检查通过
< 10 个文件变更
< 400 行总变更
提交信息描述一件事

总行数 < 400（理想情况 < 200）
所有提交都是原子的
没有 "WIP" 或 "fixup" 提交
PR 标题描述了变更
描述解释了原因，而不仅仅是做了什么

危险信号（停止并拆分）

❌ 提交信息需要用到"和"
❌ 一次提交 > 10 个文件
❌ 一次提交 > 400 行
❌ 混合了功能、修复和重构
❌ "我稍后会清理这个"

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

# Quick status
git diff --shortstat HEAD

# Detailed file list
git diff --stat HEAD

# Partial staging
git add -p

# Check before PR
git diff main --shortstat

✅ 测试刚刚通过
✅ > 200 行变更
✅ > 5 个文件变更
✅ 即将切换任务
✅ 当前状态是"可工作的"

🇺🇸English

Commit Hygiene Skill

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.

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.           │
└─────────────────────────────────────────────────────────────────┘

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

Ideal Commit Size

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

Check Current State (Run Frequently)

Quick Status Check

# See what's changed (staged + unstaged)
git status --short

# Count files and lines changed
git diff --stat
git diff --cached --stat  # Staged only

# Get totals
git diff --shortstat
# Example output: 8 files changed, 245 insertions(+), 32 deletions(-)

Detailed Change Analysis

# 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

Pre-Commit Check Script

#!/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)"

# 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

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

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"

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

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

Splitting Large Changes

Strategy 1: By Layer

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"

Strategy 2: By Feature Slice

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"

Strategy 3: Refactor First

Instead of:
  - Feature + refactoring mixed

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

Strategy 4: By Risk Level

Instead of:
  - Safe changes + risky changes together

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

PR Size Guidelines

Optimal PR Size

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

PR Size vs Defect Rate

┌─────────────────────────────────────────────────────────────────┐
│  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.          │
└─────────────────────────────────────────────────────────────────┘

When PR is Too Large

# Check PR size before creating
git diff main --stat
git diff main --shortstat

# If too large, consider:
# 1. Split into multiple PRs (stacked PRs)
# 2. Create feature flag and merge incrementally
# 3. Use draft PR for early feedback

Commit Message Format

Structure

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

[optional body - wrap at 72 chars]

[optional footer]

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

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

Git Workflow Integration

Pre-Commit Hook for Size Check

#!/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"

Partial Staging (Split Large Changes)

# 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

Unstage If Too Large

# Unstage everything
git reset HEAD

# Unstage specific files
git reset HEAD path/to/file.ts

# Stage just what you need for THIS commit
git add -p

Claude Integration

Periodic Check During Development

Claude should run this check after every significant change:

# 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"

Claude Commit Reminder Messages

📊 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"

Stacked PRs (For Large Features)

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                                   │
└─────────────────────────────────────────────────────────────────┘

Creating Stacked PRs

# 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

Changes are for ONE logical purpose
Tests pass (if applicable)
Lint/typecheck pass
< 10 files changed
< 400 lines total
Commit message describes ONE thing

Before Creating PR

Total lines < 400 (ideal < 200)
All commits are atomic
No "WIP" or "fixup" commits
PR title describes the change
Description explains why, not just what

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"

Quick Reference

Thresholds

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

Commands

# Quick status
git diff --shortstat HEAD

# Detailed file list
git diff --stat HEAD

# Partial staging
git add -p

# Check before PR
git diff main --shortstat

Commit Now If

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

Weekly Installs

Repository

alinaqi/claude-bootstrap

GitHub Stars

531

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode78

gemini-cli73

codex71

cursor71

claude-code67

github-copilot63

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

120,000 周安装

Commit Hygiene 指南：原子提交、PR审查与Git历史整洁的最佳实践

🇨🇳中文介绍

Commit Hygiene Skill

核心理念

相关 Skills

提交大小阈值

警告阈值（是时候提交了！）

理想的提交大小

检查当前状态（经常运行）

快速状态检查

详细变更分析

提交前检查脚本

何时提交

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

立即提交如果

不要等待

原子提交模式

良好的原子提交

不良提交（过大）

拆分大型变更

策略 1：按层拆分

策略 2：按功能切片拆分

策略 3：先重构

策略 4：按风险级别拆分

PR 大小指南

最佳 PR 大小

PR 大小与缺陷率

当 PR 过大时

提交信息格式

结构

类型

示例

Git 工作流集成

用于大小检查的预提交钩子

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

如果过大则取消暂存

Claude 集成

开发过程中的定期检查

Claude 提交提醒消息

堆叠式 PR（用于大型功能）

创建堆叠式 PR

检查清单

每次提交前

创建 PR 前

危险信号（停止并拆分）

快速参考

阈值

命令

立即提交如果

🇺🇸English

Commit Hygiene Skill

Core Philosophy

Commit Size Thresholds

Warning Thresholds (Time to Commit!)

Ideal Commit Size

Check Current State (Run Frequently)

Quick Status Check

Detailed Change Analysis

Pre-Commit Check Script

When to Commit

Commit Triggers (Any One = Commit)

Commit Immediately If

Don't Wait For

Atomic Commit Patterns

Good Atomic Commits

Bad Commits (Too Large)

Splitting Large Changes

Strategy 1: By Layer

Strategy 2: By Feature Slice

Strategy 3: Refactor First

Strategy 4: By Risk Level

PR Size Guidelines

Optimal PR Size

PR Size vs Defect Rate

When PR is Too Large

Commit Message Format

Structure

Types

Examples

Git Workflow Integration