- Updated: March 12, 2026
- 5 min read
Contextual Commits: Enhancing Commit Messages with Project Context
Contextual Commits: Capturing the “Why” Behind Every Git Change
Contextual Commits is an extension of the Conventional Commits specification that adds a structured commit‑body section to record the reasoning, decisions, and contextual signals behind each change. By embedding the “why” directly into the Git history, teams gain instant traceability, and AI coding agents can retrieve the missing context without separate documentation.
When developers stare at a diff weeks after a feature lands, the what is obvious—but the why often evaporates. The original Substack post that introduced Contextual Commits illustrates this exact pain point and proposes a simple, standards‑based remedy.
What Are Contextual Commits and Why Do They Matter?
Traditional commit messages follow the Conventional Commits format: a concise type(scope): description line that tells the team what changed. While this is excellent for automation (changelog generation, semantic versioning), it leaves out the narrative that explains *why* a particular implementation was chosen.
- Reduced knowledge decay: The rationale stays alongside the code, preventing “context loss” as team members rotate.
- Better AI‑agent collaboration: Coding assistants like Claude or ChatGPT can read the body and produce more accurate suggestions.
- Streamlined audits: Security and compliance reviews can instantly see the decision‑making trail.
How Contextual Commits Extend Conventional Commits
Contextual Commits retain the familiar subject line but require a structured body composed of action lines. Each line follows a verb(scope): description pattern, mirroring the subject’s syntax while focusing on intent.
feat(auth): implement Google OAuth provider
intent(auth): users need social login, starting with Google before GitHub and Apple
decision(oauth-library): passport.js over auth0-sdk — better multi‑provider flexibility
rejected(oauth-library): auth0-sdk locks us into their session model
learned(passport-google): requires explicit offline_access scope for refresh tokens
In this example:
- Subject line tells the what – a new feature.
- Body lines capture the why – intent, design decisions, rejections, and lessons learned.
The body is not a free‑form paragraph; it is a machine‑readable list that can be parsed by scripts, LLMs, or custom workflow automation studios. This design keeps the commit history both human‑friendly and programmatically actionable.
Real‑World Use Cases and Impact on Development Workflow
Adopting Contextual Commits reshapes several everyday scenarios:
1. Onboarding New Engineers
New hires can run git log --grep=decision to instantly see past architectural choices, reducing the time spent hunting through tickets or Slack archives.
2. AI‑Powered Code Review Assistants
When an AI reviewer encounters a complex change, it can query the commit body for “intent” or “decision” tags, allowing it to surface relevant guidelines or suggest alternative implementations.
3. Continuous Compliance Audits
Regulatory checks often require justification for data‑handling changes. A simple grep for rejected or decision lines provides a ready‑made audit trail.
4. Automated Release Notes with Context
Traditional release notes list features; Contextual Commits enable tools to append a “Why this feature matters” section automatically, improving stakeholder communication.
5. Knowledge Capture for Coding Agents
Agents like Claude or the ChatGPT and Telegram integration can retrieve the “learned” lines to adapt their prompts, resulting in fewer “hallucinations” and more precise code generation.
Key Insight from the Specification’s Author
“The commit body has always been there. Completely underutilised. By turning the body into a structured context log, we eliminate the need for separate documentation files and let Git do what it was built for – be an immutable, append‑only ledger of both actions and reasoning.” – Veselin Dimitrov
Getting Started with Contextual Commits on UBOS
UBOS makes it effortless to adopt the specification across your CI/CD pipeline. Here’s a quick roadmap:
- Enable the commit‑body hook: Install the UBOS templates for quick start that include a pre‑commit script enforcing the body format.
- Integrate with AI agents: Use the OpenAI ChatGPT integration to automatically generate the “intent” and “decision” lines from your PR description.
- Leverage the workflow studio: Build a Workflow automation studio step that validates each commit before push, ensuring compliance.
- Monitor adoption: Dashboards on the UBOS platform overview can track the ratio of contextual commits versus plain commits.
For teams that need a visual editor, the Web app editor on UBOS provides a UI for crafting commit bodies, reducing friction for non‑CLI users.
Why UBOS Is the Ideal Home for Contextual Commits
UBOS’s Enterprise AI platform already powers AI‑enhanced development pipelines. By embedding Contextual Commits into its core, UBOS delivers:
- Seamless AI‑agent access to commit context.
- Zero‑code integration via the Chroma DB integration for vector‑searchable commit bodies.
- Scalable governance that respects the same append‑only guarantees Git provides.
Whether you’re a startup exploring the UBOS for startups program or an SMB looking at UBOS solutions for SMBs, the added transparency of Contextual Commits can accelerate delivery while keeping knowledge intact.
Call to Action
Ready to make every commit a knowledge capsule? Explore the following UBOS resources:
- UBOS blog – deep dives on version‑control best practices.
- UBOS features – see how AI agents interact with commit data.
- About UBOS – learn our mission to empower developers with intelligent tooling.
- UBOS pricing plans – find a tier that fits your team’s size.
Adopt Contextual Commits today and turn every Git entry into a living document of intent, decision, and learning. Your future self – and your AI assistants – will thank you.