Entry/Exit
- Entry: Need to commit code or create a branch during build
- Exit: Clean, separable commit history for review
- Points to: Continue build or enter
verify-workflow-review - Preload: CANON.md
- Output path: Commit history →
verify-workflow-reviewreview
When not to use
- Only reading history, checking status, or explaining Git concepts, without creating commits/branches
- The current task explicitly requires not committing or not changing version history
- When unowned changes need to be cleaned up but the source cannot be determined, ask the human partner first
Iron Law
Core principles
1. Trunk-Based Development (recommended)
main ────○────○────────○────○── (经常合并小改动)
\ /
feature ○──○──○──○ (短生命周期分支,< 2 天)
Rules:
- Branch lifetime < 2 days
- Rebase onto latest main before merging
- Small PRs (100-300 lines) > large PRs
- Commit directly to main only for documentation fixes, configuration adjustments, and other non-behavioral changes
2. Atomic commits — one change per commit
Good:
1a2b3c feat: add Task.create() with validation
4d5e6f test: add unit tests for Task.create()
7f8g9h refactor: extract validateTask to shared module
Bad:
abc123 feat: add task creation, tests, refactor validation, fix typo in README
Each commit is independently understandable, revertible, and bisectable.
3. Descriptive commit messages
<type>: <简短摘要(< 50 字符)>
<详细说明 —— 为什么改,不是什么(可选,如有必要)>
Type: feat / fix / refactor / test / docs / chore / perf / security
Commit messages should state why, not what.git diff already shows what.
Good:
fix: prevent race condition when two users complete same task
The task status check and update were not atomic, allowing two
concurrent requests to both mark a task as completed.
Bad:
fix: update task service
4. Separation of concerns
- Formatting changes → separate formatting commit
- Renaming/moving files → separate commit (do not mix with behavioral changes)
- Behavioral changes → separate commit
Never mix formatting changes and behavioral changes in one commit.
5. Change size
| Size | Lines | Review difficulty |
|---|---|---|
| Small | < 100 lines | Easy to review, fast to merge |
| Medium | 100-300 lines | Regular PR, can be completed in one review session |
| Large | 300-1000 lines | Needs splitting or more careful review |
| XL | > 1000 lines | Must be split |
Goal: about 100 lines per commit. Over 300 lines → decide whether to split.
Save Point mode
Commit frequently, push often. A commit = a save point, not a final product.
实现 Task A 实现 Task B 格式化 Rebase 到 main
│ │ │ │
▼ ▼ ▼ ▼
commit + push commit + push commit + push git pull --rebase
│
push + merge
Safety net: Commit after completing each logical unit (one function, one test, one refactoring step). If you mess up later, rollback is cheap.
Worktree isolation
Create isolated environments for unrelated work:
# 创建隔离工作区
git worktree add -b feature/x ../project-feature-x main
# 在隔离区工作
cd ../project-feature-x
# 完成 → 合并 → 清理
git worktree remove ../project-feature-x
When to use worktree:
- Handle multiple unrelated tasks at the same time
- Need to quickly switch back to main to verify some behavior without losing current progress
- Run long scripts (tests, builds) without blocking
Pre-Commit Hygiene
Before committing, check:
git diff --staged # 审查你实际要提交的变更
git diff --staged --check # 检查空白字符错误
npm test # 运行测试(如果项目有预提交钩子则自动)
Never:
git add -Aorgit add .— manually select files to avoid accidentally committing secrets or binary filesgit push --forceto a shared branch — it rewrites someone else's baseline--no-verifyskip hooks — unless the hooks are broken and there is a sufficient reason- Commit
.env、credentials.json、node_modules, build artifacts
Git Debugging Tools
git bisect start HEAD <known-good-commit> # 二分查找引入 bug 的提交
git log -- path/to/file # 看文件变更历史
git blame -L 10,30 path/to/file # 看特定行是谁改的
git grep "pattern" $(git rev-list --all) # 在所有提交中搜索
Common Excuses
| Excuse | Reality | Consequence |
|---|---|---|
| "Put all changes in one commit" | A giant commit cannot be reviewed, cannot be reverted, and cannot be bisected. Split it up. | When reverting a giant commit, you are forced to discard all changes rather than reverting a single point; when using bisect to locate a bug, you cannot narrow it down to a specific step, making debugging time 5-10x longer. |
| "Commit messages don't matter, the code speaks for itself" | Commit messages are for your colleague 2 years from now. The code shows what, the commit message explains why. | Commit history without why → future maintainers cannot understand the motivation behind decisions → repeated discussion of already-ruled-out approaches or accidental modification of critical logic. |
| "Wait until everything is done before committing" | Frequent commits = safety net. When something goes wrong, the revert scope is small. | When a single large commit goes wrong, the revert scope = all changes; when frequent commits go wrong, the revert scope = the last logical unit, a loss difference of 10-50x. |
| "force-push doesn't matter, I'm the only one on this branch" | CI may be running on the branch, and force-push will interrupt CI. Even if you are the only one,--force-with-lease > --force。 |
force-push to a shared branch → rewrites others' baseline → team members' subsequent merges fail or work is lost, with a fix cost of > 1 hour/person. |
| "No need for worktree, just open two clones" | Two clones do not share an object store, wasting disk space and requiring two copies of npm install。 |
Two clones → double disk usage + double install time (~5 minutes) vs worktree sharing an object store (< 1 minute to create). |
| "Just run the tests once with formatting changes and behavior changes mixed together" | When reverting a behavior change, you are forced to also revert the formatting. Always separate them. | Mixed commit reverting a behavior change → formatting is also lost → reformatting + re-review, an extra 30-60 minutes. |
Red Flags — STOP
- More than 10 staged files that do not belong to the same change
- Commit message = "fix", "update", "WIP" (zero information)
git add -Astaging unrelated files together- Branch alive for more than 3 days with a diff over 500 lines
- Formatting changes and behavior changes appear in the same staged set
- force-push to
main/master(rewriting shared history) - staged includes
.envor key files - When resolving merge conflicts, using
--theirsto resolve whole blocks instead of checking one by one
Verification Checklist
- Each commit is a single logical unit
- Commit messages use the
<type>: <summary>format, explaining why - Changes are separated by concern (formatting vs behavior vs renaming)
- No accidentally committed keys, binary files, or generated files
- Branch is based on the latest main/master
- Tests pass before committing
- No force-push to shared branches
Handling Verification Failures
| Failure Scenario | Handling Method |
|---|---|
| Too many staged files (>10 and not part of the same change) | STOP. Split by concern: commit behavior changes, formatting, and renames separately. Do not force them into one package. |
| Commit message is vague (fix/update/WIP) | Force a rewrite of the commit message. Use <type>: <summary> format, write why not what. |
| Secret key or .env file accidentally staged | STOP。git reset HEAD <文件> to unstage. Never commit secrets. If already committed, use git filter-branch to purge from history. |
Merge conflict resolved with --theirs as a whole block |
STOP. Check each conflict block one by one, understand both sides' intent, then choose or manually merge. Do not blindly accept either side. |
| Branch alive > 3 days and diff > 500 lines | Split into multiple small PRs. Short branch + small diff = fast review + fast merge. |
| force-push to main/master | STOP. This rewrites shared history. Fix with revert or a new commit, do not rewrite. |
Good and bad examples
Good — atomic commit sequence
1a2b3c feat: add Task.create() with validation
4d5e6f test: add unit tests for Task.create()
7f8g9h refactor: extract validateTask to shared module
→ Each commit is a single logical unit, independently revertible, bisectable
Bad — giant mixed commit
abc123 feat: add task creation, tests, refactor validation, fix typo in README
→ Problem: 4 changes mixed together → reverting task creation forces reverting tests, refactoring, and typo fixes too → Problem: cannot narrow the scope when using bisect to locate the bug → debugging time 5-10x
Output template
The commit sequence should follow the format below (check each commit):
## Commit Checklist
- [ ] 提交类型: feat/fix/refactor/test/docs/chore/perf/security
- [ ] 提交摘要 < 50 字符,描述 why
- [ ] 变更行数 < 300(超过需拆分)
- [ ] 格式化/重命名/行为变更已分离
- [ ] 无密钥、二进制、生成文件误提交
- [ ] 测试在提交前已通过