Analyze the current changes and generate a Conventional Commits-style commit message; only when the diff is large or spans multiple concerns, enable read-only subagents as needed to assist with clustering and risk analysis.
Usage
/ac-commit [options]
References
references/conventional-commits.md— Conventional Commits specification
Options
| Options | Description |
|---|---|
--no-verify |
Skip Git hooks (only when explicitly specified by the user) |
--all |
Stage all changes |
--amend |
Amend the previous commit (only when explicitly specified by the user) |
--signoff |
Add signature |
--emoji |
Include emoji prefix |
--scope <scope> |
Specify scope |
--type <type> |
Specify commit type |
Role division of labor
| Role | Responsibility |
|---|---|
| Claude (main thread) | Perform Git checks, collect diffs, decide whether to enable subagents, generate the commit message, and execute the commit |
| subagents | Read-only analysis of clustering results, splitting suggestions, and risk points for large diffs; does not perform Git write operations |
Execution constraints
Working directory:
- Use the current Git repository root directory as the root directory for commit analysis
- If the user has added multiple workspaces via
/add-dirfirst determine the repository to actually commit to - If it cannot be determined, use
AskUserQuestionto ask the user to select the target repository
Conditions for using subagents:
- Applicable: the diff is very large, spans multiple top-level directories, or mixes multiple types of concerns (source code/tests/docs/configuration)
- Preference: use read-only subagents for change clustering, splitting suggestions, and risk scanning
- Not applicable: small changes, a single feature point, or scenarios where the main thread can determine directly by looking at the diff
Important:
- All Git write operations (
git add、git commit, write.git/COMMIT_EDITMSG, write.context/history/*) are performed only by the main thread - Subagents must not perform Git write operations such as staging, committing, rewriting history, or skipping hooks
- For diff analysis content already delegated to subagents, the main thread should not analyze it again
- Respect Git hooks by default; they may be skipped only when the user explicitly passes
--no-verifyOnly then can it be skipped - Only when the user explicitly passes
--amendis amending the previous commit allowed
Execution workflow
🔍 Phase 1: Repository validation
[模式:检查]
- Verify that the current directory is a Git repository
- Detect intermediate states and conflicts such as rebase / merge / cherry-pick
- Read the current branch and HEAD status
📋 Phase 2: Change detection
[模式:分析]
- Obtain staged and unstaged changes
- If the staging area is empty:
- The user explicitly passes
--all→ stage all changes - Otherwise prompt the user to choose whether staging is needed
- The user explicitly passes
- Collect:
git status --shortgit diff --cached- If necessary
git diff
🧩 Phase 3: Splitting suggestions and on-demand parallel analysis
[模式:建议]
- The main thread first quickly determines the scale of changes and concerns
- If the changes are relatively small, the main thread directly clusters them along the following dimensions:
- Concerns (source code vs docs/tests)
- File patterns (different directories/packages)
- Change type (addition vs. deletion)
- If one of the following conditions is detected, start read-only subagents in parallel as needed:
- Changes exceed about 300 lines
- Span multiple top-level directories
- Include multiple categories of changes such as features, tests, documentation, and configuration at the same time
- Typical ways to split subagents:
- Change clustering: determine which files should be grouped into the same atomic commit
- Risk scanning: identify breaking changes, configuration risks, large numbers of deletions, and test gaps
- After the main thread summarizes, decide:
- Whether to recommend splitting the commit
- The best type / scope / subject for the current commit
✍️ Phase 4: Generate commit message
[模式:生成]
Format:[emoji] <type>(<scope>): <subject>
- First line ≤ 72 characters
- Imperative mood
- Message body: motivation, implementation points, impact scope
- Language: determine Chinese/English based on the recent commit style and current repository conventions
If subagents are enabled, combine their clustering and risk analysis results to generate a more accurate commit message.
📦 Phase 5: Context auto-archiving (if .context/ exists)
[模式:上下文归档]
Pre-check:
- If the
.context/directory does not exist → automatically create the.context/history/、.context/current/branches/directory structure, initialize emptycommits.jsonlandcommits.md, then continue with archiving - If
.context/exists → perform the following steps
Automatically generate ContextEntry from git diff:
- Get the current branch name:
git branch --show-current - Get staged changes:
git diff --cached --stat+git diff --cached - Analyze diff to generate ContextEntry:
summary: take the first line from the commit message generated in Phase 4decisions: analyze key changes in the diff (new dependencies, architecture adjustments, interface changes, configuration modifications) and infer the decision rationalebugs: if the commit type isfix, extract the bug symptoms, root cause, and fix method from the diffchanges.files: fromgit diff --cached --name-onlyextracttests: if the changes include test files, record test-related information
- If
.context/current/branches/<branch>/session.logexists and is non-empty, merge the manual records in it into decisions / bugs, then clearsession.log - Desensitization: scan token / key / password / secret patterns → replace with
[REDACTED] - Append: append ContextEntry as one line to
.context/history/commits.jsonl - Regenerate: update
.context/history/commits.mdhuman view - Stage:
git add .context/history/ - Trailer: add to the commit message
Context-Id: <uuid>trailer
Failure fallback: if an error occurs during archiving, do not block the commit. Write a minimal ContextEntry (summary + files only) and continue with the normal commit.
✅ Phase 6: Execute commit
[模式:执行]
git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG
Type and Emoji mapping
| Emoji | Type | Description |
|---|---|---|
| ✨ | feat |
New feature |
| 🐛 | fix |
Bug fix |
| 📝 | docs |
Documentation update |
| 🎨 | style |
Code formatting |
| ♻️ | refactor |
Refactor |
| ⚡️ | perf |
Performance optimization |
| ✅ | test |
Test-related |
| 🔧 | chore |
Build/tooling |
| 👷 | ci |
CI/CD |
| ⏪️ | revert |
Revert |
Example
/ac-commit
/ac-commit --all
/ac-commit --emoji
/ac-commit --scope ui --type feat --emoji
/ac-commit --amend --signoff
Key rules
- Git write operations only on the main thread – Submission, staging, and writing commit messages are all done by the main thread of the current session
- subagents only perform large diff analysis – Used as needed, not enabled by default, and does not perform Git write operations
- Respect hooks – Executed by default, only when the user explicitly specifies
--no-verifycan it be skipped - Atomic commits – One commit does only one thing
- Do not modify source code – This process does not modify product code, and only handles Git and context archive files