Effective Workflow for Using AI — Generate

Keeping a changelog current is one of those tasks that developers consistently neglect until release day arrives. The problem is straightforward: writing changelogs requires context about what changed, why it changed, and who it affects. AI tools can handle much of this workload, but only when you provide the right inputs and establish a consistent workflow.

This guide covers a practical workflow for using AI to generate and maintain changelog documentation without the typical headaches.

Setting Up Your Changelog Workflow

The foundation of an effective AI-powered changelog workflow starts with structured commit messages. AI models work best when they have clear, consistent input data. Raw git logs are noisy and inconsistent across teams, making AI output equally unreliable.

Configure your team to use conventional commits with a simple format:

<type>(<scope>): <description>

[optional body]

A commit like feat(auth): add OAuth2 login support for Google gives AI tools clear signals about what changed and in which area. The type prefix (feat, fix, docs, refactor) allows AI to categorize changes automatically.

Tools like Commitizen or husky can enforce this format through git hooks. Once your commit history follows a consistent pattern, AI can parse and transform this data into useful changelog entries.

Generating Changelog Entries with AI

With structured commits in place, you can prompt AI to generate changelog content. The key is providing context along with the raw data.

For a CLI-based approach using a tool like GitHub CLI with AI assistance:

# Get commits since last release
git log --pretty=format:"%s%n%b" v1.2.0..main > commits.txt

# Feed to AI with a clear prompt
cat commits.txt | claude -p "Convert these commits into changelog entries grouped by type (Features, Bug Fixes, Breaking Changes). Use user-friendly language, not technical jargon."

This produces organized output that requires minimal editing. The AI translates technical commit messages into descriptions that users can understand.

For teams using GitHub, the AI code review tools integrated into pull request workflows can also generate preliminary changelog entries. During code review, ask AI to summarize the changes:

“Write a changelog entry for these changes. Focus on user-facing behavior changes. Skip implementation details.”

Maintaining Changelog Quality

AI excels at generating initial drafts, but human oversight remains essential for accuracy. Establish a review step where someone verifies:

Accuracy: Does the description correctly represent what changed?
Audience: Will users understand this description?
Completeness: Are any important changes missing?

A practical pattern is using AI to generate a draft, then having a developer review and refine before merging. This hybrid approach captures the efficiency benefits of AI while maintaining the quality standards users expect.

For ongoing maintenance, schedule regular reviews. Monthly or quarterly changelog audits catch drift between what was shipped and what is documented. AI can compare the current changelog against git history to identify gaps:

# Python script to find undocumented changes
import subprocess
import re

def get_commits_since_release(tag):
    result = subprocess.run(
        ['git', 'log', '--pretty=format:%s', f'{tag}..HEAD'],
        capture_output=True, text=True
    )
    return result.stdout.strip().split('\n')

def extract_types(commits):
    types = {}
    for commit in commits:
        match = re.match(r'^(\w+)(\(.+\))?:', commit)
        if match:
            t = match.group(1)
            types[t] = types.get(t, 0) + 1
    return types

commits = get_commits_since_release('v1.2.0')
types = extract_types(commits)
print(f"Undocumented changes: {types}")

This script identifies what has been committed but might not yet appear in your changelog, giving you a clear action list for updates.

Automating the Workflow

For teams ready to fully automate, integrate AI changelog generation into your release pipeline. GitHub Actions can run on tag creation:

name: Generate Changelog
on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate changelog
        run: |
          git log --pretty=format:"%s%n%b" ${{ github.ref_name }}~1..${{ github.ref_name }} > changes.txt
          # Pipe to AI for formatting
          cat changes.txt | ai-tool --format=changelog > CHANGELOG.md.new
      - name: Review and commit
        run: |
          # Human review step could pause here
          cat CHANGELOG.md.new

The key is inserting a manual review gate before the changelog reaches users. Fully automated changelogs without review often contain inaccuracies that damage user trust.

Practical Example

Consider a team shipping a payment processing update. Using the workflow described:

Commits follow conventional format: fix(payments): resolve race condition in refund processing, feat(payments): add support for Apple Pay
AI generates: “Bug Fixes: Resolved an issue where refund requests could fail during high traffic. New Features: Added Apple Pay support for faster checkout.”
Developer reviews, adjusts tone, adds context about which versions are affected
Final entry published in release notes

This approach reduces changelog writing from a 30-minute manual task to a 5-minute review, while maintaining or improving quality through consistent formatting and clear descriptions.

Using AI Tools Effectively for Changelog Tasks

Different AI tools excel at different aspects of changelog work. Claude handles large commit batches well and can organize them by semantic meaning. ChatGPT produces changelog entries that read more conversationally. GitHub Copilot works best for interactive prompt-and-response iterations where you refine the output live.

The key is matching the tool to your workflow. For teams that ship infrequently (quarterly releases), a simple Claude prompt suffices. For teams shipping weekly, integrating changelog generation into your CI/CD pipeline prevents accumulated work from piling up.

Tools and Integrations

Several tools can reduce changelog friction:

Conventional Commits + Commitizen: Enforces structure at commit time.

Git Hooks: Pre-commit checks ensure your team follows the format before pushing.

Release-It: Automates changelog generation and versioning.

Lerna: For monorepos, manages changelogs across packages.

Semantic Release: Fully automated releases with AI-generated changelog entries.

These tools chain together: structured commits → AI-generated draft → human review → published changelog.

Addressing Common Pitfalls

Many teams encounter issues when first automating changelog generation:

Over-aggregation: AI sometimes combines related features into a single entry when they should remain separate. This happens when commits are vague or when multiple features affect the same code path. The fix: ensure your commit messages scope each feature clearly.

Grouping problems: AI might categorize a refactor as a breaking change if it involved changing an internal API. Provide explicit context about which APIs are public vs. internal.

Version context loss: When changelog entries don’t mention which release fixed an issue, users cannot determine if they need to upgrade. Always include version markers or ask AI to include them.

Incomplete migration notes: For major version upgrades, changelog entries should link to migration guides. Ask AI to suggest migration documentation alongside breaking changes.

Typos and grammatical errors: AI occasionally generates entries with syntax errors or awkward phrasing. Always include a spell-check step, ideally automated.

Scaling Across Teams

As teams grow, centralized changelog management becomes essential. Teams shipping hundreds of features annually cannot review every changelog entry manually.

Establish a changelog schema your team follows. This might specify:

Format for feature entries (one or two sentences, no jargon)
Format for breaking changes (clear migration path, affected APIs)
Format for deprecations (deadline for removal, suggested replacement)

AI tools can learn these patterns from examples. Provide 5-10 well-written entries as training examples, then ask AI to follow the same style.

Integration with Release Notes

Changelogs and release notes serve different audiences. Changelogs target developers; release notes target end users. A single AI generation pass cannot satisfy both.

Use a two-pass approach: first, generate a developer-focused changelog from commits. Then, have AI translate key entries into user-friendly language for release notes. This ensures consistency between internal and external documentation.

# Generate changelog from commits
git log --pretty=format:"%s%n%b" v1.2.0..v1.3.0 > commits.txt

# Pass to Claude with two prompts
# Prompt 1: Generate technical changelog
# Prompt 2: Translate entries to user-facing release notes

Maintenance and Long-Term Viability

Changelogs drift over time. Entries become outdated, links break, and version numbers shift. Schedule quarterly audits to verify:

All referenced URLs still exist
Version numbers match your actual releases
Feature descriptions remain accurate
Breaking changes have not been forgotten

AI can help with this audit process. Feed it your changelog and git history, then ask it to identify inconsistencies:

# Audit script: Find inconsistencies
import subprocess
import re

def audit_changelog(changelog_file, repo_path):
    with open(changelog_file) as f:
        changelog = f.read()

    # Check for broken patterns
    missing_versions = find_entries_without_version(changelog)
    outdated_urls = check_links(changelog)

    return {
        'issues': missing_versions + outdated_urls,
        'recommendations': suggest_fixes(changelog)
    }

audit_changelog('CHANGELOG.md', '.')

This creates a feedback loop where AI assists with maintenance, reducing the friction of keeping changelogs current over years.

Built by theluckystrike — More at zovo.one