Conventional Commit Message Generation Prompt Template

This prompt is designed for platform teams and AI coding agents that need to enforce a consistent commit history across a repository. The primary job-to-be-done is to transform a raw code diff into a single, well-structured commit message that strictly adheres to the Conventional Commits specification. The ideal user is a developer who has just staged a change or an automated CI/CD pipeline that needs to generate a squash commit message for a pull request. The required context is a unified diff of the changes, and optionally, any linked issue tracker IDs or co-author information.

Do not use this prompt for generating release notes, changelogs, or pull request descriptions, as those require a broader synthesis of multiple commits and a different audience. This prompt is also unsuitable for repositories that do not follow the Conventional Commits standard, or for commits that represent multiple unrelated logical changes; in those cases, the changes should be split into smaller, atomic commits first. The prompt assumes the input diff is a complete and final representation of a single logical change. It will not interrogate the diff for correctness or test coverage, only describe it.

Before integrating this prompt into a production harness, you must define clear evaluation criteria. The generated message must pass a strict schema check: the type must be from the allowed list, the description must be in the imperative mood, the first line must not exceed 72 characters, and any breaking change must be declared in the footer with a BREAKING CHANGE: token. If your team uses a custom scope list or extended footer fields, add those as explicit constraints in the prompt's [CONSTRAINTS] placeholder. The next step is to build a validation harness that can parse the output and provide immediate, actionable feedback to the developer if the message fails any of these rules.

This prompt template is the core instruction set for an AI coding agent to generate a commit message that strictly follows the Conventional Commits specification. It is designed to be dropped into a system prompt or a user message within your AI harness. The template uses square-bracket placeholders for all dynamic inputs, ensuring you can wire it directly into your CI pipeline, pre-commit hook, or IDE plugin. The prompt instructs the model to analyze a provided diff, determine the correct type and scope, and structure the output with a description, body, and footer for breaking changes.

textCopy
You are a commit message generator that strictly follows the Conventional Commits specification.

Analyze the provided code diff and generate a single commit message.

## Input
- **Diff:** [DIFF]
- **Repository Context (Optional):** [REPO_CONTEXT]
- **Team Convention Overrides (Optional):** [CONVENTION_OVERRIDES]

## Output Schema
Generate a commit message with the following structure:
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

## Constraints
- **Type:** Must be one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, or `revert`.
- **Scope:** A noun in parentheses describing the section of the codebase (e.g., `auth`, `api`, `parser`). Omit if the change is global.
- **Description:** Use the imperative, present tense (e.g., "add" not "added" or "adds"). Start with a lowercase letter. Do not end with a period. Keep it under 72 characters.
- **Body:** Optional. Use the imperative, present tense. Explain the motivation for the change and contrast it with the previous behavior. Wrap lines at 72 characters.
- **Footer:**
  - **Breaking Changes:** If the diff introduces a breaking change, the footer MUST start with `BREAKING CHANGE: ` followed by a description of what changed, why, and migration notes.
  - **Issue References:** If the diff relates to any issues, include a footer line like `Closes #123` or `Refs #456`.
- **Formatting:** Separate the header from the body and each footer with a single blank line. Do not include any text before or after the commit message.

## Examples
### Example 1: Simple fix
Diff: `- return user.name + ' ' + user.surname;` `+ return `${user.name} ${user.surname}`;`
Commit Message:

fix(user-utils): correct string concatenation in display name

codeCopy

### Example 2: Feature with breaking change
Diff: `... changes to an API function signature ...`
Commit Message:

feat(api)!: send confirmation email on user registration

The registration endpoint now accepts an email field and triggers a confirmation email. Previously, only a username was required.

BREAKING CHANGE: the registerUser function now requires an email parameter in the options object. Update all callers to include a valid email address.

Closes #421

codeCopy

## Task
Generate the commit message for the provided diff.

To adapt this template, replace the [DIFF] placeholder with the actual unified diff output from your version control system. The [REPO_CONTEXT] placeholder can be populated with relevant file paths, directory structures, or package names to help the model infer an accurate scope. The [CONVENTION_OVERRIDES] placeholder allows you to inject team-specific rules, such as allowed custom types or required co-author footers, without rewriting the core prompt. For high-risk repositories, consider adding a final instruction that forces a [HUMAN_REVIEW] flag in the output if the model's confidence in the breaking change detection is low, ensuring a developer always validates potentially destructive changes before they are pushed.

This prompt is designed to be called programmatically, not pasted into a chat window. The primary integration points are a pre-commit hook, a CI job in a merge queue, or an AI coding agent's post-edit workflow. In all cases, the harness should capture the raw diff (via git diff --staged or the PR's unified diff), inject it into the [DIFF] placeholder, and parse the model's structured output. The prompt's [OUTPUT_SCHEMA] should request a JSON object with fields for type, scope, description, body, footer, and breaking_change boolean, making it straightforward to validate before the message is written to a commit or PR.

A production implementation requires a validation layer before the generated message is accepted. Write a post-generation validator that checks: (1) the type field matches an allowed list (e.g., feat, fix, docs, style, refactor, perf, test, chore, ci); (2) the description is in imperative mood (a simple heuristic is checking the first word is not past tense, but a stronger approach is a second LLM call with a binary classifier prompt); (3) the description does not exceed 72 characters; (4) if breaking_change is true, the footer contains a BREAKING CHANGE: token or the type/scope includes a !; and (5) the body wraps at 72 characters. If validation fails, the harness should retry once by feeding the validation errors back into the [CONSTRAINTS] or [OUTPUT_SCHEMA] section of the prompt, asking the model to correct the specific violations. If the retry also fails, the harness should log the failure and fall back to a human-authored message rather than silently accepting a non-compliant commit.

For model choice, a capable but cost-effective model like claude-3-5-haiku or gpt-4o-mini is sufficient for most diffs. Reserve larger models for complex, multi-file diffs where the body and footer require nuanced synthesis. The harness should log every generation attempt—including the raw diff, the model's output, validation results, and the final accepted message—to a structured logging system (e.g., JSON lines to a file or an observability platform). This audit trail is critical for debugging prompt drift, model regressions, or false-positive validation failures over time. For high-compliance repositories (e.g., SOC 2, FedRAMP), add a human approval step for any commit message where the model's breaking_change flag is true or where the diff touches files in a sensitive directory (e.g., auth/, billing/, migrations/). The harness should post the generated message to a review channel (Slack, a PR comment, or an internal tool) and block the commit until a human approves. Finally, avoid wiring this prompt directly into a post-commit hook that rewrites history; always generate the message before the commit is finalized so the developer can edit it.