A commit message is the smallest unit of technical documentation. It is written once, but it is read hundreds of times: by your future self, by every teammate who runs git blame, by every tool that generates a changelog, and increasingly by AI agents that mine repository history to understand a codebase.
For most of git's lifetime, commit messages were written by humans who learned conventions the hard way. Two short essays shaped that conversation: Tim Pope's A Note About Git Commit Messages and Chris Beams' How to Write a Git Commit Message.
The problem: the people writing the majority of commits today are no longer human. AI coding agents now generate a large share of the commits in every repository, and if you have ever seen an agent-produced message like update stuff or fix, you know they do not absorb conventions by osmosis. They absorb them from instructions, and the natural home for those instructions is AGENTS.md.
The two essays that started it
Tim Pope's note, written in 2008, is short enough to read over coffee. Its rules have aged perfectly:
- Separate the subject from the body with a blank line.
- Limit the subject line to 50 characters.
- Capitalize the subject line.
- Do not end the subject line with a period.
- Use the imperative mood in the subject line: "Fix bug", not "Fixed bug" or "Fixes bug".
- Wrap the body at 72 characters.
- Use the body to explain what and why, not how.
The imperative mood matters because a commit is an instruction applied to a snapshot: "merge this feature", "remove this dependency". It also keeps git revert and git bisect output readable, since git itself uses the imperative in its own messages.
Chris Beams' guide, written a decade later, distills the same wisdom into seven rules with careful explanations. His central argument: a commit message shows whether a developer communicates well. He also notes that the "what and why, not how" rule deserves emphasis, because code changes can be obvious while the reasoning behind them is almost always invisible.
What aviation taught me
The third influence is less obvious: ASD-STE100 Simplified Technical English, the controlled language used to write aircraft maintenance documentation. STE100 restricts writers to a small approved vocabulary with one meaning per word, forbids synonyms and jargon, and demands short, single-clause sentences.
The goal is not style for its own sake. Aircraft manuals are read by technicians of every nationality and language background, often under time pressure, and the documentation must be unambiguous to the point where a mistake is impossible. A controlled vocabulary means there is exactly one way to read a sentence.
Commit messages face the same conditions in miniature. They are read by developers across language barriers, years after the code was written, without the author present. A constrained vocabulary forces the author to say precisely what changed, and it makes the message parseable by machines: changelog generators, git log filters, and the AI agents that will eventually read the history and form their model of your project.
The style guide for the body
The fourth influence is the Google developer documentation style guide, which covers the same ground from a professional writing angle: active voice, present tense, second person, imperative mood in headings and commands, and ruthless brevity. Its principles map cleanly onto commit bodies:
- Write the body in active voice: "Fix null pointer in retry path" instead of "null pointer has been fixed".
- Describe the change and its reason in one or two short sentences. If the body needs more than a few lines, the commit is probably too large.
- Do not restate the diff. The diff tells you what; the message must tell you why.
Why AGENTS.md, specifically
An AGENTS.md file is a set of instructions for AI agents working in a repository. Unlike a README or a CONTRIBUTING doc, it is loaded into the agent's context at the start of every session. That is exactly the property a commit standard needs.
Enforcement mechanisms like commit hooks and linters are after-the-fact: the message already exists by the time a hook rejects it, and a linter can check subject length but not whether the message says anything meaningful. AGENTS.md works at the source. When the agent starts a session, the standard is already in context, so the guidance shapes the message before it is written, not after.
This matters more every quarter, for two reasons:
- Agents write a growing share of all commits. Without explicit guidance, they produce the lowest-information messages, because nothing in their training guarantees repository-specific conventions.
- Agents read history too. Modern coding agents retrieve past commits to understand decisions, and a history written in controlled, imperative, well-structured English is dramatically easier for them to interpret than one full of
wipandstuff.
What it looks like
Here is the actual AGENTS.md section in this repository, technical writing and commit messages together:
### Technical writing style
Follow project-specific terminology and style first. Otherwise, use the
principles in ASD-STE100 Simplified Technical English and the Google developer
documentation style guide.
For technical documentation, plans, explanations, comments, and user-facing
instructions:
- Use US English, active voice, present tense, and direct language.
- Use the same term consistently for the same concept.
- Prefer short, common, precise words. Avoid slang, idioms, cliches, vague
jargon, figurative language, and culture-specific references.
- Define necessary acronyms and unfamiliar terms on first use.
- Put conditions before the instructions or results that depend on them.
- Write one instruction per sentence unless actions must occur together.
- Use imperative verbs for procedural steps.
- Keep procedural sentences at 20 words or fewer when clarity permits.
- Keep descriptive sentences at 25 words or fewer when clarity permits.
- Give each sentence and paragraph one main topic.
- Do not omit necessary words merely to shorten a sentence.
- Address the reader as "you" in explanatory text.
- Use numbered lists for sequences and bullets for non-sequential sets.
- Use sentence case for headings, meaningful link text, and alt text for
informative images.
- Do not describe a task as easy, simple, or quick.
- Use `must` for requirements, `can` for capability or permission, and `might`
for possibility. Avoid ambiguous uses of `should`.
- Use passive voice only when the actor is unknown or naming the actor would
reduce accuracy.
- Treat these as clarity rules, not a claim of formal ASD-STE100 compliance.
Formal compliance requires the current standard, its controlled dictionary,
and the project's approved technical terminology.
### Git commit messages
Follow the repository's required commit convention first.
- Separate the subject from the body with one blank line.
- Write an imperative, capitalized subject without a trailing period.
- Target 50 characters for the subject. Do not exceed 72 characters unless a
project convention or generated commit format requires it.
- Wrap body prose at 72 characters. Do not wrap URLs, code, generated text, or
machine-readable trailers.
- Explain what changed and why. Include non-obvious effects or tradeoffs.
- Do not restate implementation details that are clear from the diff.
- Put issue references and other metadata in trailers at the end.
- Prefer focused, atomic commits.
References:
- https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
- https://cbea.ms/git-commit/
- https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf
- https://developers.google.com/style
The commit rules stand alone: imperative subject lines, a 50-character target with a 72-character hard cap, bodies that say what and why, and trailers for metadata. The writing style section above it does the heavier lifting, because it shapes every artifact the agent produces, from comments to plans to commit bodies.
The payoff
None of this is about pedantry. It is about the fact that a repository's history is its longest-lived documentation, and its quality compounds or decays exactly like code quality. A well-formed history means git bisect runs are easy to interpret, git blame reads like a design journal, onboarding consists of reading the last month of commits, and agents working on the codebase start from a history that tells them what happened and why.
The next time an agent opens your repository, give it the standard before it writes its first commit. The instruction costs a few dozen lines in AGENTS.md, and every message it produces from then on inherits decades of writing conventions distilled into something even a machine can follow.