Agent Commits
A specification for AI-authored commit messages that enables human reviewers to understand why changes were made, not just what changed.
The Problem
When AI agents write code, traditional commit messages become inadequate:
- ✗"Add feature X" doesn't explain why the agent chose this approach
- ✗"Fix bug in Y" doesn't reveal the agent's understanding of the problem
- ✗Reviewers can't distinguish between intentional decisions and potential misunderstandings
- ✗No audit trail of what the human requested vs. what the agent delivered
The Solution
Agent Commits is a structured commit message format that captures:
Intent
What the human asked for
Plan
How the agent decided to accomplish it
Changes
What files were modified and why
Verification
How the changes were tested
Example
[agent] feat: Add user authentication with JWT tokens Intent: User requested login functionality with session persistence Plan: - Add JWT library for token generation - Create auth middleware for protected routes - Add login/logout endpoints - Store refresh tokens in httpOnly cookies Changes: - src/auth/jwt.ts: Token generation and validation utilities - src/middleware/auth.ts: Route protection middleware - src/routes/auth.ts: Login, logout, and refresh endpoints - package.json: Added jsonwebtoken dependency Verified: All auth tests passing, manual login flow tested
Quick Start
For Claude Code Users
Add the Agent Commits skill to generate compliant commit messages automatically:
/add-skill https://agentcommits.com/skill.md
Manual Usage
Follow the specification to format your AI-assisted commits, or check out real-world examples.
Why This Matters
For Reviewers
- • Understand the original request
- • Verify plan aligns with intent
- • Spot misunderstandings early
- • Trust but verify AI changes
For Teams
- • Maintain audit trails
- • Clear accountability
- • Enable better tooling
- • Build institutional knowledge
For Agents
- • Structured format reduces ambiguity
- • Clear expectations
- • Enables self-verification
- • Supports iteration
Get Started
Read the full specification or start using Agent Commits today.