Show HN：Agentic Commits – 適用於 AI 代理工作流程的提交規範

Agentic Commits

A commit format that AI agents and humans can read, understand, and act on

visit project

Agentic Commits

A commit format that AI agents and humans can read, understand, and act on

visit project

A specification for commit messages that AI agents can read, understand, and act on.

Plus a skill that implements hunk-splitting and atomic commit workflows.

Like Conventional Commits, but optimized for agent capabilities: Resume, Review, Handoff, and Code Review.

The Problem

Your git history has all the information. But no one can use it:

Agents can't Resume

👤 Continue where we left off

What would you like me to help you with today? 🤖

Without → next, the agent doesn't know where you left off.

Agents can't Review

👤 Why did we add refresh tokens?

I don't have context from previous sessions. 🤖

Without (why), the decision rationale is lost.

New developers can't Handoff

👤 What's been done so far?

I see 127 commits but the messages are 'fix', 'wip', 'updates'... 🤖

Without structured history, meaningful summaries are impossible.

Reviewers can't Code Review effectively

👤 Is a null check the right fix here?

Commit: "fix: add null check" 📝

Without (why), reviewers can't evaluate if the solution fits the problem.

The Solution

Structure your commits so anyone - agent or human - can read them and take action.

Four Capabilities

Capability

Reads

Agent

Human

Resume

→ next

Continue after crash

Remember after vacation

Review

(why)

Explain past decisions

Understand why code exists

Handoff

Full history

New agent takes over

New developer onboarding

Code Review

(why) + diff

AI evaluates approach

Reviewer understands intent

The Format

Elements

Element

Purpose

Required

type

Categorize: feat, fix, wip, refactor, test, docs, chore

Always

Scope

Locate: file name or component

Always

what

Describe: imperative action

Always

(why)

Explain: motivation - enables Review & Code Review

Always

→ next

Continue: tasks - enables Resume

WIP only

Types

Type

Use

Needs → next?

feat

Completed feature

No

wip

Work in progress

Yes

fix

Bug fix

No

refactor

Code restructure

No

test

Tests

No

docs

Documentation

No

chore

Config, dependencies

No

Examples

Code Review: Why (why) Matters

Without (why), reviewers can only check:

Is the code syntactically correct? Yes

Are there obvious bugs? Yes

Is this the right approach for the problem? No

Is there a better solution? No

With (why), reviewers can evaluate:

Now the reviewer can ask: "Is a null check the best fix for users crashing on empty forms? Or should we validate earlier?"

Atomic Commits

Agents and reviewers parse commits one by one. Make each one self-contained:

One logical change per commit - Don't mix unrelated changes

One file per commit - Different files = separate commits (unless directly dependent)

Hunk-level splitting - Same file can have multiple commits if changes are independent

Commit order - fixes → refactors → features

How Hunk Splitting Works

A hunk is a contiguous block of changes in a file. When one file has multiple unrelated changes, the skill splits them into separate commits:

Each commit contains only related lines, even from the same file. Reviewers see focused changes instead of mixed diffs.

Different Files, Same Type

Benchmark

We tested agent comprehension across multiple AI models on Vite PR #21235.

Format Comparison

Format

Agent Accuracy

Plain commits

38.7%

Conventional commits

48.0%

• WHY (reason)

51.5%

• WHY + NEXT + Scope

76.6%

What Each Element Adds

Element

Enables

Impact

→ next

Resume

+12%

(why)

Review, Code Review

+3.5%

Atomic

All capabilities

Clean history

FAQ

Why not just read the code?

For many tasks, reading the codebase is enough. But some information only exists in commits:

Information

In codebase?

In commits?

What code does

Yes

No

Why it was written

No (sometimes comments)

Yes (why)

What's next

No

Yes → next

Is it finished?

No (guess)

Yes wip vs feat

Commits are metadata about your code. They complement reading code, not replace it.

How is this different from Conventional Commits?

Agentic Commits extends Conventional Commits with two additions:

Element

Conventional

Agentic

(why)

Optional in body

Required in title

→ next

Not defined

Required for WIP

Is this only for AI agents?

No. All four capabilities benefit both agents and humans. See the capabilities table above.

What if I forget to add (why)?

The commit loses value for Review and Code Review. Without (why):

Reviewers can't evaluate if the solution fits the problem

Future developers (or agents) can't understand the motivation

You're back to guessing from code alone

Should I use commit body?

Title-only format is usually enough. Our benchmark showed no accuracy difference between title-only and title+body formats. Use body only for complex changes that need extra context.

Can I use → next on non-WIP commits?

No. → next is only for wip commits. Completed work (feat, fix, etc.) shouldn't have next steps - if there are next steps, it's not done yet.

What if the implementing and committing agents are different?

This affects Resume capability only. The agent writing commits must have implementation context to know → next.

Capability

Different agents?

Reason

Resume

Needs same agent

→ next requires knowing the plan

Review

Works

(why) can be inferred from diff

Handoff

Works

Full history is visible

Code Review

Works

(why) + diff is enough

Rule: Never guess → next. If you don't have implementation context, use feat instead of wip.

Can I apply this to an existing project?

Yes. Start using the format for new commits. You don't need to rewrite history. Over time, your recent commits will be agent-readable while older ones remain as-is.

How atomic should my commits be?

One logical change, one file (unless directly dependent). If you're tempted to write "and" in your commit message, split it into two commits.

Install

Choose your agent below. The full skill includes hunk-splitting workflows and atomic commit automation. For a quick start, see Specification Only at the bottom.

Claude Code

1. Marketplace (recommended)

2. Manual - Project-level (tracked in git, team-wide)

3. Manual - User-level (all your projects)

Then add to CLAUDE.md: Use the agentic-commit skill for all commits.

Codex

1. Repo-level

2. User-level

Invoke with /skills or $agentic-commit. Add to AGENTS.md for automatic invocation.

Cursor

1. Remote Rule (Settings)

Settings → Rules → Add Rule → Remote Rule (GitHub) → deligoez/agentic-commits

2. Manual - Project-level

3. Manual - User-level

Skills auto-discovered at startup. Invoke manually with / in Agent chat. Also supports .claude/skills/.

Amp

1. Workspace-level

2. User-level

Add guidance to AGENTS.md. Amp auto-loads skills via load_skill tool.

Antigravity

1. Workspace-level

2. Global

Auto-discovered from .agent/skills/.

OpenCode

1. Project-level

2. User-level

Skills loaded on-demand. Also supports .claude/skills/.

Other Agents / Specification Only

Add to your config file (CLAUDE.md, AGENTS.md, .cursorrules, or system prompt):

Summary

Agent

Best Method

Project Path

Config

Claude Code

Marketplace

.claude/skills/

CLAUDE.md

Codex

Manual

.codex/skills/

AGENTS.md

Cursor

Remote Rule

.cursor/skills/

.cursorrules

Amp

Manual

.agents/skills/

AGENTS.md

Antigravity

Manual

.agent/skills/

OpenCode

Manual

.opencode/skill/