Enforce Semantic Versioning in Your Projects with Free AI Assistant Rules

Tired of inconsistent commit messages? Confused about when to bump MAJOR vs MINOR versions? Wish your AI coding assistant could help enforce best practices?

We've got you covered.

Today, we're releasing free, downloadable rule files for Cursor, GitHub Copilot, Claude Code, and Windsurf that automatically enforce semantic versioning, conventional commits, and proper git tagging in your projects.

---

The Problem: Version Chaos

We've all been there:

git log --oneline
a3f2b9c updated stuff
7d8e1f2 fix
3c9a4b1 WIP - don't merge
5e2f8d9 Fixed the bug

And then comes release time:

"Should this be v1.6.0 or v2.0.0?"
"What changed since the last release?"
"Why don't we have any tags?"

Sound familiar?

---

The Solution: AI-Enforced Best Practices

What if your AI coding assistant could:

✅ Format commit messages automatically using Conventional Commits
✅ Suggest version bumps based on your changes
✅ Guide you through tagging with proper annotations
✅ Catch mistakes before they make it into your history
✅ Explain the rules when you ask

That's exactly what these rule files do.

Related: Automate branch promotions with GitHub Actions to complete your release workflow.

---

What You Get

🎯 Cursor Rules (.mdc format)

Download: cursor-rules.mdc

A comprehensive rule file for Cursor AI that includes:

• Conventional Commits enforcement - No more vague commit messages
• Semantic Versioning decision trees - Clear MAJOR/MINOR/PATCH guidance
• Git tagging protocols - Annotated tags with proper messages
• Code style preferences - TypeScript, React, and API conventions
• Release workflow steps - Complete release process
• Common scenarios - Examples for hotfixes, features, breaking changes

Installation:

mkdir -p .cursor/rules
mv cursor-rules.mdc .cursor/rules/80-versioning.mdc

Restart Cursor, and you're done!

🤖 GitHub Copilot Instructions

Download: copilot-instructions.md

Custom instructions for GitHub Copilot that help with:

• Commit message templates - Copilot suggests proper formats
• Versioning explanations - Context-aware guidance
• Tag creation commands - Proper git tag commands
• Code style guidance - Best practices for TypeScript and React
• Troubleshooting help - Common issues and solutions

Installation:

mkdir -p .github
mv copilot-instructions.md .github/copilot-instructions.md
git add .github/copilot-instructions.md
git commit -m "docs: add GitHub Copilot instructions"

Or install personally in VS Code settings.

🧠 Claude Code Rules (.mdc format)

Download: claude-code-rules.mdc

Comprehensive rules for Claude Code (terminal and IDE) that provide:

• Interactive commit guidance - Claude helps you write proper commit messages
• Version bump explanations - Step-by-step reasoning for version decisions
• Real-time validation - Catch mistakes before they're committed
• Scenario-based examples - Learn from practical situations
• Full automation support - Integration with semantic-release and tools

Installation:

For terminal use:

# Claude Code automatically reads from your codebase
# Place rules in your project for context
mkdir -p .claude
mv claude-code-rules.mdc .claude/versioning-rules.mdc

For VS Code extension:

• Open VS Code
• Install Claude Code extension
• Rules are automatically detected in your workspace

🌊 Windsurf Rules (.mdc format)

Download: windsurf-rules.mdc

Streamlined rules for Windsurf/Cascade that include:

• Concise commit format guide - Quick reference for Conventional Commits
• Version bump quick reference - Fast decision-making
• Common scenarios - Real-world examples
• Troubleshooting shortcuts - Fix issues quickly
• Integration best practices - Works with your release workflow

Installation:

# Add to Windsurf rules directory
mkdir -p .windsurf
mv windsurf-rules.mdc .windsurf/versioning-rules.mdc

Windsurf Cascade will automatically apply these rules in your project.

---

Real-World Examples

Before: Chaos

git commit -m "updated auth"
git commit -m "fix"
git commit -m "more changes"
git tag v1.2.3

Problems:

• ❌ Unclear what changed
• ❌ Can't generate changelogs
• ❌ Don't know if it's breaking
• ❌ Lightweight tag (no metadata)

After: Clarity

git commit -m "feat(auth): add OAuth2 authentication

Implemented OAuth2 flow with GitHub provider.
Includes token refresh and scope management.

Closes #123"

git tag -a v1.6.0 -m "Release v1.6.0: Add OAuth2 authentication

- Add OAuth2 support
- Add token refresh
- Improve security"

Benefits:

• ✅ Clear what changed
• ✅ Automated changelog generation
• ✅ Version bump is obvious (MINOR)
• ✅ Annotated tag with context
• ✅ Perfect for ReleaseRay! 🚀

---

Semantic Versioning Refresher

Quick reminder of the rules:

MAJOR.MINOR.PATCH

v2.3.1
│ │ └─ PATCH: Bug fixes (backward compatible)
│ └─── MINOR: New features (backward compatible)
└───── MAJOR: Breaking changes (NOT backward compatible)

Commit Types → Version Bumps

Commit Type	Version Impact	Example
feat:	MINOR ↑	v1.5.3 → v1.6.0
fix:	PATCH ↑	v1.5.3 → v1.5.4
feat!: or BREAKING CHANGE:	MAJOR ↑	v1.5.3 → v2.0.0
docs:, chore:, etc.	No bump	Stay at v1.5.3

Simple, right?

---

How AI Assistants Help

These rule files enable your AI coding assistant to guide you through versioning best practices. Here's how:

Scenario 1: Writing a Commit Message

You type:

git commit -m "added OAuth"

Your AI suggests:

feat(auth): add OAuth2 authentication

Implemented OAuth2 flow with GitHub provider.
Includes token refresh and scope management.

You learn: The proper format and get better commit messages instantly.

Scenario 2: Creating a Tag

You ask: "Help me create a tag for the new OAuth feature"

Your AI responds:

# This is a new feature (feat:), so MINOR bump
git tag -a v1.6.0 -m "Release v1.6.0: Add OAuth2 authentication"
git push origin v1.6.0

You learn: When to bump versions and how to tag properly.

Scenario 3: Breaking Change

You write:

git commit -m "refactor: change auth API"

Your AI asks: "Is this a breaking change? If so, add ! or BREAKING CHANGE:"

You learn: Breaking changes need special marking for MAJOR bumps.

---

Tool-Specific Features

Cursor AI

• Real-time suggestions as you type commit messages
• Context-aware guidance based on your codebase
• Integrated with Cursor's chat and composer features
• Applies rules automatically across your project

GitHub Copilot

• Inline commit message formatting
• Chat-based versioning explanations
• Integration with VS Code's git interface
• Repository-level or personal instructions

Claude Code

• Interactive terminal guidance for git operations
• Step-by-step explanations of versioning decisions
• Can analyze your commit history to suggest versions
• Works both in terminal and VS Code extension

Windsurf Cascade

• Flow-based commit message assistance
• Quick version bump reference
• Integrated with Cascade's multi-file edit capabilities
• Streamlined for fast decision-making

---

Why This Matters for Release Notes

Consistent versioning and commits make automated release note generation actually work.

With proper tags and commit messages, tools like ReleaseRay can:

1. Define release ranges - Select v1.5.0 → v1.6.0
2. Analyze commits - Categorize by type (features, fixes, breaking)
3. Generate notes - AI creates persona-specific release notes
4. Publish everywhere - GitHub Releases, Intercom, changelog, Slack

Garbage in, garbage out. These rules ensure quality input for quality output.

---

Installation Guide

For Cursor Users

1. Download the file:

   curl -O https://releaseray.com/downloads/cursor-rules.mdc
   

2. Install:

   mkdir -p .cursor/rules
   mv cursor-rules.mdc .cursor/rules/80-versioning.mdc
   

3. Restart Cursor - That's it!

For Copilot Users

Repository-Level (Recommended)

# Download
curl -O https://releaseray.com/downloads/copilot-instructions.md

# Install
mkdir -p .github
mv copilot-instructions.md .github/copilot-instructions.md

# Commit
git add .github/copilot-instructions.md
git commit -m "docs: add GitHub Copilot instructions"
git push

Personal-Level (Your Account Only)

1. Open VS Code
2. Press Cmd/Ctrl + Shift + P
3. Type "GitHub Copilot: Edit Personal Instructions"
4. Paste the contents of copilot-instructions.md
5. Save

For Claude Code Users

Terminal Use

# Download
curl -O https://releaseray.com/downloads/claude-code-rules.mdc

# Install in project (recommended)
mkdir -p .claude
mv claude-code-rules.mdc .claude/versioning-rules.mdc

# Claude Code will automatically detect rules in your project

VS Code Extension

1. Install the Claude Code extension from VS Code marketplace
2. Download claude-code-rules.mdc
3. Place in your workspace root or .claude/ directory
4. Rules are automatically loaded when Claude Code is active

For Windsurf Users

# Download
curl -O https://releaseray.com/downloads/windsurf-rules.mdc

# Install
mkdir -p .windsurf
mv windsurf-rules.mdc .windsurf/versioning-rules.mdc

# Windsurf Cascade will automatically apply these rules

---

Customization

Both files are plain text and fully customizable:

Cursor Rules (.mdc format)

The file uses frontmatter for configuration:

---
description: Your custom description
globs: "**/*" # Which files to apply to
alwaysApply: true # Always enforce or not
---

Copilot Instructions (.md format)

Just markdown - edit any section:

## Commit Message Format

When suggesting commit messages, always use...

Pro tip: Start with our defaults, then customize for your team's workflow.

---

Beyond the Rules: Full Automation

These rule files are just the beginning. For complete automation, consider:

1. Git Hooks (Husky + commitlint)

Enforce commit format before accepting commits:

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

2. CI/CD (semantic-release)

Automatically determine versions, create tags, and publish:

npm install --save-dev semantic-release
# Configure in .releaserc.json

On every push to main:

1. ✅ Analyzes commits
2. ✅ Determines version bump
3. ✅ Generates changelog
4. ✅ Creates git tag
5. ✅ Publishes release

3. Release Notes (ReleaseRay)

Generate AI-powered, persona-specific release notes:

1. Select tag range (e.g., v1.5.0 → v1.6.0)
2. AI analyzes all commits
3. Generate notes for:
   • Engineers - Technical details, migration guides
   • Customers - User-facing changes, benefits
   • Internal/CSM - What to tell customers
4. Publish to GitHub, Intercom, changelog, Slack

See our complete automation guide for setup instructions.

---

Common Questions

Q: Do I need all these files?

A: Depends on your tools:

• Using Cursor? Download cursor-rules.mdc
• Using VS Code + Copilot? Download copilot-instructions.md
• Using Claude Code (terminal or VS Code)? Download claude-code-rules.mdc
• Using Windsurf? Download windsurf-rules.mdc
• Using multiple tools? Download all applicable files! They work together seamlessly.

Q: Will this slow down my workflow?

A: No! These rules speed up your workflow by:

• Auto-formatting messages (no more manual typing)
• Catching mistakes early (no more fixing history)
• Providing instant guidance (no more googling)
• Teaching best practices (you'll learn as you go)

Q: Can I customize for my team?

A: Absolutely! Both files are plain text. Edit them to match your:

• Commit scopes (e.g., feat(api), feat(ui))
• Version strategy (maybe you use different rules)
• Code style preferences
• Release workflow

Q: What about existing projects?

A: Works great! Install the rules and:

1. New commits will follow the format
2. Old commits stay as-is (don't rewrite history)
3. Start tagging properly going forward
4. Use ReleaseRay for release notes from now on

The next release will be much cleaner!

Q: Does this work with monorepos?

A: Yes! Place the Cursor rules in .cursor/rules/ at the root, or in each package. For Copilot, use repository-level instructions.

Q: What if I forget the rules?

A: That's the beauty - you don't need to remember! Your AI assistant will:

• Suggest the correct format
• Explain the rules when asked
• Catch mistakes automatically
• Guide you through the process

---

What Developers Are Saying

"Finally! No more 'fix' and 'updated stuff' commits from my team."
— Sarah, Engineering Manager

"I love that Cursor now suggests proper commit messages. It's like having a code review before I even commit."
— Mike, Senior Developer

"These rules + ReleaseRay = zero effort release notes. Game changer."
— Alex, DevOps Lead

---

Get Started Today

1. Download the Files

Cursor: Download cursor-rules.mdc
Copilot: Download copilot-instructions.md
Claude Code: Download claude-code-rules.mdc
Windsurf: Download windsurf-rules.mdc

2. Install in Your Project

Follow the installation guide above.

3. Read the Full Guide

Our complete versioning guide covers:

• Semantic Versioning in depth
• Conventional Commits specification
• Manual and automated workflows
• Troubleshooting common issues
• Integration with ReleaseRay

4. Try ReleaseRay

Ready for automated release notes? Sign up for ReleaseRay and:

• Connect your repository
• Select a tag range
• Generate AI-powered release notes
• Publish to GitHub, Intercom, and more

Free tier available!

---

Open Source

All four rule files are free and open source. Use them in any project, commercial or personal.

Want to contribute? Submit improvements via GitHub or share your customizations with the community.

---

Conclusion

Consistent versioning isn't just about following rules - it's about:

✅ Clear communication - Everyone understands what changed
✅ Automated workflows - Tools can generate changelogs and release notes
✅ Better collaboration - Teams follow the same conventions
✅ Faster releases - No more manual version decisions
✅ Professional quality - Your project looks polished

These rule files make it effortless to maintain that quality.

Download them today and never worry about version confusion again.

---

Resources

• Downloads: Get the files
• Full Guide: Versioning guide
• Semantic Versioning: semver.org
• Conventional Commits: conventionalcommits.org
• ReleaseRay: Generate release notes

---

Related Posts

• Automate Branch Promotions with GitHub Actions
• Why Multi-Persona Release Notes Matter
• Getting Started with ReleaseRay

---

Questions? Drop a comment below or reach out on Twitter.

Found this helpful? Share it with your team! ⭐

---

Published by the ReleaseRay Team on November 4, 2025