AI contributions are traced through git metadata, not separate commits
Introduction
As AI tools become a standard part of how we build, we need a consistent way to record where AI contributed to our work. Claude Code and Codex are now woven into everyday development, and human and AI work are interleaved within a single session. A traceability convention lets PMs, architects, and devs audit AI use in deliverables, answer client and governance questions, and onboard new team members into the practice without guesswork.
Decision
AI contributions are recorded through git metadata. There are two requirements. On any commit where an AI tool contributed, add git trailers in the commit message:
AI-assisted: trueAI-tools: claude-code, codex
List the tools that actually contributed in the AI-tools trailer (for example claude-code, codex). In the pull request description, disclose which AI tools were used via the AI tool disclosure field in the PR template.
We do not require separate commits for AI-generated code.
Context
This is done for three main reasons:
- AI and human code are interleaved in every session. Splitting AI-generated code into its own commits would be artificial, hard to enforce, and would not reflect how the work actually happens.
- The auditability requirement from leadership is satisfied at the commit and PR level, where the history already lives.
- Git trailers are lightweight and machine-readable. They travel with the commit, survive rebases when handled normally, and can be queried directly from the log.
Consequences
- AI use in any deliverable can be audited from git history without a separate tracking system.
- The auditability requirement is met without changing how devs write code.
- Trailers are queryable, for example
git log --grep "AI-assisted: true", which supports reporting and review. - Projects gain a consistent, documented signal that connects to our existing "all code undergoes review" standard.
- Adoption depends on devs remembering to add trailers, so the practice needs to be reinforced through the ops project and PR template defaults rather than relying on memory alone.
Exceptions
- Trivial single-line autocomplete does not require a trailer. Use judgment: the trailer is meant to flag meaningful AI contribution, not every keystroke.
- Automated or templated commits (for example dependency bumps and generated config) follow the tool's own conventions and do not need the trailers.
- If a project has a client contract or governance requirement that mandates a stricter or different disclosure format, that requirement takes precedence and the deviation is documented in the project's ops configuration.
Additional Resources
None