Turn the changes produced by this task into clean, semantically clear commits. Core goal: make every git log record understandable within ten seconds—"what changed, and what kind of change it is".
Safety boundaries (highest priority)
- Never commit automatically. Execute only if the user has explicitly said "提交/commit" in this conversation; a vague "finish it first" does not count. This is consistent with the constraints in the global CLAUDE.md.
- Never
git push。 This skill stops at commit. Push only when the user separately and explicitly requests a push. - Never
git add -A/git add .。 Explicitly add file by file (adding an entire directory is allowed withgit add <目录>/), to avoid accidentally committing unrelated files. - If suspected sensitive files (keys,
.env, credentials, production configs containing passwords) or junk files (__pycache__、.venv, temporary artifacts, editor backups) appear in the pending commit list: stop, point this out to the user and confirm how to handle it; do not commit silently.
Workflow
1. Determine which changes are "the changes for this task"
Commit scope = the changes caused by this task, not everything dirty in the working tree.
git status --short # 全貌:哪些文件被改/新增/未跟踪(首列为 M 表示已暂存)
git diff --cached --stat # 暂存区是否已有内容
Determine each file's ownership against the conversation context. The working tree often contains leftover changes unrelated to this task (made by the user, or left over from a previous task)—leave thoseuntouched, keep them in the working tree, and mention "the following files were not included in the commit" in the final report.
- The staging area already contains content unrelated to this task: stop and confirm with the user how to handle it (
git restore --staged <文件>unstage it, or commit it separately),do not let it be swept into this commit。 - A single file contains both this task's changes and unrelated user changes: confirm with the user first, and after the user agrees, use
git add -pto stage only this task's hunks. - When unsure whether a file should be committed, ask; do not guess.
2. Decide whether to split into multiple commits
If this task is executed in multiple stages, each with an independent, clear goal (for example: first "optimize report SQL performance", then "update metric definition docs"; or "first fix the bug, then add the export feature"), thensplit into multiple commits by stage, adding the files involved in each stage separately before committing. Criteria:
- After splitting, can each commit clearly describe one thing on its own? If it can be split, split it.
- Do the two batches of files serve two different intents (one fix, one feat)? Split them.
- Are they related modifications incidentally produced by one logical change (e.g., changing a metric definition and updating the corresponding docs at the same time)?Do not split; put them in the same commit.
3. Write the commit message
Format:类型: 一句话简述(Chinese; a full-width colon is also acceptable; follow the repository's existing style—first run git log --oneline -5 to take a look).
Type selection:
| Type | Used for |
|---|---|
feat |
new features, new reports, new scripts, new metrics |
fix |
Fix bugs, correct incorrect definitions, fix SQL logic errors |
refactor |
Changes that do not alter external behavior: renaming, structural reorganization, column name adjustments |
perf |
Performance optimization (e.g., slow SQL optimization, index adjustments) |
docs |
Documentation/definition clarification changes only |
chore |
Chores: configuration, ignore rules, dependency upgrades, etc. |
test |
Test-only changes |
Summary requirements:
- One sentence, verb-object structure, directly state what was done. About 30 characters or fewer is appropriate.
- Accurately cover the content but do not list details: report-related changes should include report numbers (e.g., "reports 162/147/148"); do not write "modified 3 files".
- No empty phrases ("updated code", "some modifications", "improved functionality"); no long body paragraphs; no extraneous information.
Examples:
Input: This time, a collection recovery rate metric column was added to report 31, and the corresponding definition documentation was updated in sync
Output: feat: 报表31新增催回率指标列及口径文档同步
Input: Fixed the issue where the repayment plan query failed to exclude canceled bills, causing overdue statistics to be too high
Output: fix: 修复已取消账单未排除导致逾期统计偏高
Input: The task has two phases—first optimize the slow SQL of report 11, then separately organize the parameter validation of the export script Output (two entries):
perf: 报表11渠道流量监控SQL性能优化
fix: 导出脚本补充批次参数校验
4. Execute commit
For each commit unit:
git add <文件1> <文件2> ... # 显式逐个列出(整目录新增可用 `git add <目录>/`)
git diff --cached --stat # 核对暂存内容与本次意图一致
git commit -m "类型: 一句话简述"
When there are multiple commit units, loop "add → verify → commit", keeping the staging area clean each time and containing only the files for that phase.
5. Final report
After committing, briefly report to the user:
git log --onelineList the commits just created;- Leftover files in the working tree not included in the commit (if any);
- Clearly statepush was not executed。
Exception handling
- Working tree is clean (no changes from this task): inform the user there is nothing to commit and do not touch git.
- Commit is blocked by a pre-commit hook (lint/commitlint checks, lock files, etc.): truthfully report the error content,without the user's explicit request, do not use
--no-verifyto bypass。 - Repository has conflicts, is in a merge intermediate state, or detached HEAD: stop and report the current state, waiting for user instructions.
- A file specified by the user does not exist in git status: truthfully explain, do not fabricate a commit.
- Accidentally added a file: use
git restore --staged <文件>to unstage it; do not usegit reset --hardor other destructive commands to revert.