Principled Git Commit

Commit Conventions

Universal commit conventions derived from Conventional Commits 1.0.0 + Tim Pope + awesome-copilot/git-commit + a 200-commit empirical study. Project-specific dialect (domain proper nouns, custom trailers, workflow integrations like PDCA) lives in the project's docs/references/COMMIT.md — see §15 Dialect Loading.

TL;DR: type(scope): summary (≤100 chars, lowercase, imperative) + 1-2 line context + - bullets (avg 16 lines). No ## headers. English body by default. Atomic + leaves-repo-green + why-over-what.

0. Principles

A commit must satisfy four readers — humans and AI:

1. git log --oneline scanner — wants context from a single line (most common reader)
2. git blame <file> tracer — wants to know "why is this line here?" while debugging
3. git bisect hunter — wants to isolate the exact commit that broke production
4. AI agent — rebuilds context after /clear, reviews PRs, generates changelogs, answers natural-language history queries. Depends on grep + embedding search + consistent structure. Atomic units, domain keywords, English body, and explicit trailers are decisive.

The five principles below are the minimum that satisfies all four readers simultaneously. Return here when in doubt.

0.1 Atomic — one commit, one intent

Bundle exactly one logical change. Never mix "fix + style + docs" in one commit.

→ Bisect, revert, and cherry-pick all assume atomic units. Mixed commits also confuse AI summarization — the LLM grabs one intent and hallucinates the rest as a single coherent change.

Test: "If I had to revert this commit, would I drag along unrelated changes?" If yes, split.

0.2 Leaves repo green — every commit builds clean

Each commit, taken on its own, must pass tsc --noEmit + lint + build (or your project's equivalent green-build set). No "WIP, next commit will fix this."

→ Bisect signal integrity. A broken-state commit in the middle of history poisons git bisect results — the bisect ends up blaming the wrong commit. AI-driven regression analysis suffers the same way.

0.3 Why over what — body explains motivation, not changes

The diff already shows what changed. The body's job is why — the motivation, the trade-off, the alternative you rejected, the constraint that forced this approach.

→ Answers the 6-month-later blame question directly. AI can extract intent from the body without re-deriving it from the diff (diff inference is expensive and prone to misinterpretation).

❌ Body: "modify foo.ts to add bar method"        (diff already shows this)
✅ Body: "extract bar() out of inline closure —    (the WHY)
        prevents re-allocation on every render
        causing useMemo deps invalidation"

0.4 Imperative mood — "If applied, this commit will..."

Summary is in imperative mood. Matches git's own internal messages (Merge, Revert, Initial commit).

→ Consistent verb pattern. Auto-changelog tooling and AI classification (type inference, change summarization) both depend on stable verb forms.

✅ add idempotency-key support to /v1/payments     (If applied, this commit will add ...)
✅ fix double-render in <Modal> on focus return
✅ migrate auth hashing from bcrypt to argon2id
❌ added idempotency-key support                   (past tense)
❌ adding idempotency-key support                  (gerund)
❌ idempotency-key support added                   (passive)

0.5 Searchable — keyword-rich summary and body

Name domain nouns, function names, file paths, SoT names, and component names explicitly. Vague verbs (improve, update, enhance, cleanup) must be paired with a concrete noun.

→ Targets git log --grep and AI embedding search. Six months later, a query like "where did we add idempotency keys to the payments endpoint?" should hit exactly one commit. Vague keywords cause AI hallucination; concrete keywords get pinpoint accuracy.

❌ feat(api): improve checkout
✅ feat(api/payments): add Idempotency-Key header support with 24h replay window

❌ refactor: cleanup auth helpers
✅ refactor(auth): replace bcrypt with argon2id (memory-hard against GPU attackers)

Keyword checklist: scope path / function or component name / pattern name / SoT name / domain enum.

1. Format

type(scope): summary

[optional 1-2 line context — why]

- bullet: concept- or file-level change
- bullet: ...

[optional Verification: block]
[optional trailers — Refs / BREAKING CHANGE / project-dialect trailers]

1.1 Summary line

1.2 Body

• - bullets dominate. In the 200-commit study: 981 bullets vs 5 ## headers — headers are an outlier and therefore noise.
• Section labels in plain text: Verification: / Server: / Plan + Design: (not ## Verification).
• path: change pattern (server/src/foo.service.ts: rewrite).
• Average 16 lines. Anything past 80 lines indicates a missed split — the commit probably bundles two intents (see §0.1).
• English-default; switch to native language only when nuance is irretrievable in English.

1.3 Three commit surfaces (commit / PR title / squash message)

A commit message can be authored at three different surfaces depending on workflow. They all follow the same §0 principles but differ in audience and constraints:

Trunk-based teams (no long-running branches): only the individual commit surface matters. The other two are absent.

PDCA / Linear / Jira teams with feature branches that pre-merge or fast-forward: the individual commit surface is canonical; PR title is informational.

Practical: if your team squash-merges, lint the PR title against §1.1 at PR creation (GitHub Action), and lint the PR description against §1.2. CI rejection at PR-creation time costs less than rejection at merge time.

2. Types

Project may not use every type. If perf/ci/build are unused, document the omission in the project dialect.

3. Scopes

3.1 Single scope

feat(client): add ...
fix(server): handle ...
docs(refs): add ...

3.2 Sub-scope — slash-separated

When a domain has internal modules, use / to drill down:

refactor(packages/ui/Table): split row-renderer out of Table component
refactor(apps/dashboard/billing): extract invoice form into a hook
refactor(server/auth): unify session cookie attribute setters
fix(api/search): handle empty filter array in query builder

3.3 Multi-scope — comma-separated

When one commit spans multiple domains (≤3 recommended):

docs(claude,ui): document RHF / error / sticky bar / 3-zone patterns
docs(claude,refs): document server phone SoT after unification cycle

3.4 Feature-scope

Long-running features with their own document chain (PDCA-style cycles, multi-week migrations) can use the feature name directly as scope:

feat(auth-rewrite-2026-q2): M1 — replace bcrypt with argon2id verifier
feat(acme-pay-launch): wire Stripe Issuing webhook handler

The scope catalog is project-specific — projects should record their actual high-frequency scopes in the dialect (see §15.2).

3.5 Non-Conventional formats are also valid

Conventional Commits is the dominant format in modern web/JS projects but not the only valid format. The §0 founding principles (atomic, leaves-repo-green, why-over-what, imperative, searchable) apply equally to projects using:

This skill defaults to Conventional Commits because it's the most common in the surrounding ecosystem (skills.sh users, Claude/Copilot integrations, npm package conventions). But your dialect file (§13) can declare a different format — the principles still apply, only the surface vocabulary changes.

If your project uses non-Conventional format, document it in dialect §1 alongside the regex/grammar your CI enforces. Consumers of git interpret-trailers and changelog generators may need wrapper scripts.

4. Body Length Sweet Spot

Past 80 lines, you almost certainly should have split (§0.1).

5. Markdown in Body

git log displays the body as raw text. GitHub UI renders markdown but raw output is the primary consumer.

6. Breaking Changes

API / SoT / response shape / DB column / env var changes that break callers. Use either or both notations.

6.1 ! notation

feat(api)!: rename /v1/users to /v1/people
refactor(shared)!: move stripPhone to @namespace/shared/phone (server inline removed)

The ! after type/scope is itself a breaking-change signal. Searchable via git log --grep='!:'.

6.2 BREAKING CHANGE: footer

refactor(shared): migrate phone SoT to @namespace/shared/phone

- 24 server inline calls swapped for stripPhone() import
- DTO @Matches replaced with @IsKoreanPhone() decorator

BREAKING CHANGE: server-side direct imports from @/lib/utils/phone
no longer exist — only @namespace/shared/phone exports the helpers.
Update all import paths.

6.3 When to flag

• ✅ DTO request/response shape change
• ✅ shared workspace export removal/rename
• ✅ DB schema column drop / NOT NULL added
• ✅ env var rename
• ✅ public API URL change
• ❌ internal implementation change (callers unaffected)
• ❌ optional field addition
• ❌ default value addition with backwards compatibility

7. Commit Workflow

The five-step flow that produces a green-build atomic commit.

7.1 Inspect the diff first

Stage and type decisions both flow from this. Don't guess — read the diff.

7.2 Staging strategy

❌ git add -A / git add . — risks unrelated changes and secrets, violates §0.1.

Tip: git add -p is the standard tool when one file accidentally accumulates two unrelated changes. Stage the hunks for intent A, commit, then stage hunks for intent B and commit again.

7.3 Type decision tree

After §7.1 diff inspection:

When ambiguous, follow the largest impact (e.g., refactor plus an incidental fix is refactor).

7.4 Secrets blocklist

.gitignore is not enough — a freshly-created secret file may slip in. Verify before commit:

Verification command:

git diff --staged --name-only | grep -iE '\.(env|pem|key|p12|pfx|jar|properties)$|credentials\.|id_rsa'
# Must be 0 hits before commit.

7.5 Pre-commit mental checklist

After §7.1-§7.4 pass, do a final sanity sweep:

[ ] Atomic — one commit = one intent (no split required)              §0.1
[ ] Leaves repo green:                                                §0.2
    - tsc --noEmit (or your typechecker)
    - lint (zero errors on changed files)
    - build (when in doubt)
[ ] Why-over-what — body doesn't restate the diff                     §0.3
[ ] Imperative mood — summary in command form                         §0.4
[ ] Searchable — concrete nouns / paths / function names              §0.5
[ ] No secrets (§7.4 grep returns 0)
[ ] No console.log / debugger statements
[ ] Explicit path stage (not `git add -A`)                            §7.2
[ ] Subject ≤100 chars, body avg 16 lines, zero `##` headers          §1, §5
[ ] BREAKING CHANGE annotated if compatibility broken                 §6
[ ] Hook failure → fix and create NEW commit (do not amend)           §9

8. Trailers (Footers)

Last block of the body, separated by one blank line. Format Token: value. Parseable via git interpret-trailers --parse.

8.1 Standard trailers

8.2 Project dialect trailers

Projects often define their own trailers — examples seen in real codebases:

• Flag: billing-invoice-pdf-v2 — LaunchDarkly / GrowthBook feature flag named
• Storybook: components-button--all-variants — Storybook story link
• Rollout: 5% → 50% → 100% — phased rollout plan
• Plan SC: ABC-001~004 — PDCA-style success-criteria reference
• Design Ref: §2.1 — design-document section pointer
• Match Rate: 98% — gap-analysis match score
• Reported-by: <name> — kernel-style report attribution
• Fixes: <hash> — kernel-style fix-of-prior-commit pointer

These are not parsed by stock git tooling but are grep-friendly. Define yours in the project's docs/references/COMMIT.md and use them consistently.

8.3 Conventions

• One blank line between body and trailer block
• No blank lines inside the trailer block — tokens run consecutively
• Signed-off-by: only when the project enforces DCO

8.4 AI co-authoring (Claude / Copilot / Cursor / Gemini)

When an AI assistant materially shapes a commit, attribute via Co-authored-by: so credit and traceability survive in git log and git shortlog. This is increasingly common practice as agentic tools take a larger share of authorship.

When to add the trailer:

Common identities (use whichever your tool documents — the email is canonical for GitHub coauthor rendering):

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: GitHub Copilot <copilot@github.com>
Co-authored-by: Cursor <noreply@cursor.com>
Co-authored-by: Gemini Code Assist <noreply@google.com>

Multiple AI tools or pair-with-AI: list all coauthors, one per line:

Co-authored-by: Alex Kim <alex@example.com>
Co-authored-by: Claude <noreply@anthropic.com>

Why this matters for AI agents reading history: the Co-authored-by: trailer is one of the strongest signals for an AI agent rebuilding context after /clear to know that another agent shaped a commit. It informs review weight, debugging hypotheses ("hallucination might be the bug source"), and credit attribution. Skipping the trailer when AI authored substantial work is misleading to the next AI reader as much as to humans.

Org policy: some companies require explicit AI attribution for compliance / IP review; some require it stay out of public history for IP-cleanroom reasons. Check your company policy and bake it into the project dialect.

9. Amend / Fixup Rules

--amend is dangerous. Stay strict:

9.1 fixup! / squash! autosquash flow (optional)

Pre-merge interactive rebase:

git commit --fixup=<hash>           # message: "fixup! original summary"
git rebase -i --autosquash <base>

Use only on unpublished commits. Once pushed, treat history as immutable.

10. Reverts

Use git revert <hash> and keep the auto-generated message — but always add the reason.

10.1 Format

revert: feat(api): add idempotency keys to /v1/payments

This reverts commit 8a3b9c2d... .

Reason: idempotency-key TTL of 24h, combined with a Redis cluster
failover at 03:42 UTC, caused all replays in the 5-minute window
after failover to bypass deduplication and produce duplicate charges
(post-mortem #INC-2031). The fix is to persist replay records to
durable storage rather than Redis-only, which requires a schema
migration. Reverting until the durable-storage variant lands.

Refs: 8a3b9c2
Refs: #INC-2031

10.2 Rules

• Summary: revert: <original summary> (type=revert)
• First body line: This reverts commit <full-hash>.
• Then mandatory reason — what failed, why we backed out
• Original hash as Refs: trailer for cross-link

11. Anti-patterns

12. Quick Reference

✅ § Principles (4 readers: log-scanner / blame / bisect / AI agent)
   atomic / leaves-repo-green / why-over-what / imperative / searchable

✅ § Format
   type(scope): summary           ← lowercase, ≤100 chars, imperative
   <blank>
   1-2 line context (why)
   <blank>
   - bullet (concept-level)
   - bullet
   <blank>
   Verification: ...              ← optional
   <blank>
   Token: value                   ← trailers (Refs / BREAKING CHANGE / dialect tokens)

✅ § Workflow (5-step)
   1. Inspect diff (git diff / --staged / status --porcelain)
   2. Stage (explicit path / glob / -p hunks / directory)
   3. Decide type (§7.3 tree)
   4. Secrets grep (§7.4)
   5. Pre-commit checklist (tsc + lint + build + console.log + atomic)

✅ § Auto-commit boundary signals (project-defined)
   Project dialect declares phase boundaries (e.g., PDCA Plan/Design/Do/Check/Act).
   Push / force / rebase / branch deletion remain user-triggered.

❌ ## headers / 80+ line single-module / "update"·"wip" / mixed concerns
❌ amending published commits / --no-verify / git add -A
❌ WHAT-only body / past tense summary / missing BREAKING annotation

13. Project Dialect

This skill provides the universal layer. Project-specific extensions live in <project>/docs/references/COMMIT.md (the dialect file).

13.1 What goes in the dialect

• Domain proper nouns — terms that should not be translated (product names, native-language identifiers, regulatory references)
• Custom scope catalog — actual high-frequency scopes derived from the project's own git log (use scripts/analyze-history.sh)
• Custom trailers — e.g., Refs:, Closes:, Flag:, Storybook:, Rollout:, Plan SC:, Design Ref:, Match Rate:, kernel-style Fixes: / Reported-by:. Whatever your team uses consistently.
• Workflow integrations — auto-commit boundary signals (PDCA phase completion, Linear ticket close, Jira transition, etc.)
• Project-specific examples — annotated commits from this repo's actual log
• Type usage policy — if perf/ci/build are unused, document it
• Default language + explicit inverse rule — if the dialect whitelists any native-language terms, state the default in the same section: "everything outside §1 is English." Whitelist-alone invites LLM over-generalization (§11 anti-pattern: partial native-language drift). Applies symmetrically to Korean / Japanese / Chinese / Spanish / German / Portuguese / any non-English domain vocabulary. The templates/DIALECT.template.md from v0.1.5 onward models this pairing as the §1 / §1.1 split — adopt that structure when authoring a new dialect.

13.2 What does NOT go in the dialect

• Anything in this skill's §0-§12 — the universal layer is the source of truth
• New principles — if you find a generalizable principle, contribute it back to the skill instead

13.3 Generating a dialect

~/.claude/skills/principled-git-commit/scripts/scaffold-dialect.sh

Interactive prompt:

1. Project name
2. Domain proper nouns (comma-separated)
3. Run analyze-history.sh to extract scope catalog from git log?
4. Workflow integration (PDCA / Linear / Jira / none)
5. Custom trailers

Drops docs/references/COMMIT.md populated from templates/DIALECT.template.md.

13.4 Loading order at runtime

When this skill triggers:

1. Load SKILL.md (this file) — universal layer
2. Detect <project>/docs/references/COMMIT.md — if present, load and apply on top
3. If no dialect exists and the user is about to commit substantial work, offer to scaffold

13.5 Org-level dialects (multi-repo organizations)

Companies with N repos that share trailers / scopes / workflow conventions can layer three levels instead of two:

~/.claude/skills/principled-git-commit/SKILL.md   ← universal (this skill)
$ORG_HOME/COMMIT.md                               ← org-level dialect (intranet / template repo)
<project>/docs/references/COMMIT.md               ← project-level dialect

How to set up:

1. Maintain an acme-eng/commit-dialect GitHub repo (or similar) with the org-wide COMMIT.md.
2. New repos clone that file into docs/references/COMMIT.md as a starting template, then add project-specific extensions on top.
3. Org changes (e.g., "we now require Refs: for all features") propagate via PRs that copy the updated COMMIT.md into each repo.

What goes in org-level dialect:

• Common trailers all repos use (e.g., Linear ticket prefix, security-review trailer, AI co-author policy)
• Universal scope catalog (e.g., apps/, packages/, infra/ shape if monorepo standard)
• AI attribution policy (when Co-authored-by: is required org-wide)
• Squash-merge policy if uniformly adopted

What stays project-level:

• Domain proper nouns specific to this product
• Scope catalog from this repo's actual git log
• Project-specific examples and anti-patterns

Override rules: project-level beats org-level beats universal. Each layer adds, never silently removes — if a project disables an org rule, it documents the disable explicitly in §5 Type Usage Policy or the relevant section.

13.6 Verifying dialect enforcement

Even with the structure in §13.1 (whitelist + inverse rule paired), the rules only matter if (a) commits actually follow them and (b) the LLM doesn't silently drift between sessions. Three-layer verification:

1. Static check — does the dialect have the inverse rule at all?

   # From repo root. Exits 0 if pattern found.
   grep -Ei "(default.*english|english.*default|whitelist.*only|inverse rule)" docs/references/COMMIT.md
   

   Missing → add the §1 / §1.1 split per templates/DIALECT.template.md.

2. Runtime check — recent commits for drift symptoms.

   # Show last 30 commit subjects; flag rows with non-ASCII (likely native-language drift).
   git log --format='%h %s' -30 | LC_ALL=C grep -P '[^\x00-\x7f]' || echo "(all ASCII — no drift)"
   

   Hits are not all violations (whitelisted proper nouns are fine) — review each to confirm it's 친구톡-style and not 책임 분리-style prose. Patterns recurring without whitelist hits indicate drift.

3. Hook layer (project-local, optional) — a .claude/hooks/ UserPromptSubmit hook that injects a reminder when "commit"-class keywords appear in user prompts. Reminder-only (exit 0), no blocking. Pairs the SKILL invocation requirement with the dialect language rule so the LLM cannot bypass either by reading recent git log alone. See references/ for an example template.

The static check belongs in CI when team size > 1; the runtime check is a periodic audit (monthly or per release); the hook is per-developer.

14. Source Attribution

• Conventional Commits 1.0.0 — type/scope/body format, ! and BREAKING CHANGE: notation
• Tim Pope, "A Note About Git Commit Messages" — imperative mood, summary/body structure
• github/awesome-copilot@git-commit (29.6K installs) — workflow steps, type detection, secrets blocklist
• Empirical 200-commit study (private codebase, 2026-05) — length sweet spots (avg 71-char summary, 16-line body), ##-header outlier observation (5/200 = 2.5% of corpus), sub-scope (/) and multi-scope (,) conventions, module-tag pattern in long-running cycles

Version