AI Rules for Branch Naming

Branch Naming Format for AI Tools

The standard branch naming format: AI rule: 'Branch names follow the pattern: type/ticket-slug. Types: feat (feature), fix (bug fix), refactor (refactoring), test (test additions), docs (documentation), chore (maintenance). Ticket: the issue tracker ID (PROJ-123, #456). Slug: 2-4 word description in kebab-case. Examples: feat/PROJ-123-user-notifications, fix/PROJ-456-login-timeout, refactor/PROJ-789-auth-middleware.' The AI: creates branches with consistent, descriptive names when instructed to create a branch for a task.

Why branch naming rules matter for AI-assisted development: when AI tools create branches as part of agentic workflows (Claude Code can create branches, commit, and push), the branch names default to generic patterns ('claude-code-changes', 'update-1', 'patch-20260329'). With rules: the AI creates branches that match the team's convention. The branch name: visible in PR lists, git log, and CI/CD pipelines. A well-named branch: communicates the change's purpose before anyone reads a line of code.

Preventing common AI branch naming mistakes: AI rule additions: 'No spaces in branch names (use hyphens). No uppercase letters (use lowercase only). Maximum length: 60 characters. No special characters except hyphens and forward slashes. Never name a branch main, master, develop, or release (these are reserved).' These constraints: prevent the AI from generating branch names that break CI/CD pipelines, confuse git commands, or conflict with protected branches. AI rule: 'Branch naming rules take 30 seconds to write and prevent every branch the AI creates from needing a manual rename. The rule: applied once. The benefit: every branch, every developer, every AI tool session.'

Type Prefixes and Their Conventions

Type prefix alignment with commit types: AI rule: 'Branch type prefixes match commit message types. feat/ branches contain feat: commits. fix/ branches contain fix: commits. This alignment: creates a consistent narrative from branch to commit to PR.' The AI: uses the same vocabulary for branches and commits. The team: reads 'feat/PROJ-123-user-notifications' and knows the branch contains feature commits, the PR is a feature PR, and the changelog entry will be under Features.

Additional type prefixes for specialized workflows: AI rule: 'hotfix/ — urgent production fix (bypasses normal review process). release/ — release preparation (version bumps, changelog updates). experiment/ — exploratory code that may not merge (prototypes, spikes). deps/ — dependency updates (library upgrades, security patches).' The specialized types: communicate branch intent beyond the standard feat/fix/refactor. The AI: selects the correct prefix based on the task description. The CI/CD pipeline: can apply different rules based on the prefix (hotfix branches: expedited review, experiment branches: no blocking CI).

Type prefix automation: AI rule: 'Branch type determines: CI pipeline behavior (feat → full test suite, hotfix → smoke tests only), review requirements (feat → 1 approval, hotfix → 2 approvals), and deployment targets (feat → staging, hotfix → production).' The automation: reads the branch prefix and applies the correct workflow. The AI: knows these implications and chooses the correct prefix. The developer: communicates intent through the branch name, and automation handles the workflow. AI rule: 'Type prefixes are not just naming conventions — they are workflow triggers. The prefix tells CI/CD what to do, the ticket tells project management what is being worked on, and the slug tells developers what changed. Three pieces of information in one branch name.'

Ticket Reference Integration

Linking branches to issue trackers: AI rule: 'All branches include the issue tracker ticket ID. Format: type/PROJ-123-description. The ticket ID: enables automatic linking between the branch, PR, and issue tracker (Jira, Linear, GitHub Issues). When the PR is merged: the issue tracker automatically updates the ticket status.' The AI: includes the ticket ID when creating a branch for a tracked task. The project manager: sees automatic status updates without manual effort.

Multi-ticket branches: AI rule: 'If a branch addresses multiple tickets: use the primary ticket. Reference secondary tickets in the PR description, not the branch name. If a branch has no ticket: use the format type/no-ticket-description (only for unplanned work like urgent fixes or tech debt).' The rule: handles the common scenario where work does not perfectly map to one ticket. The AI: asks for the primary ticket when creating a branch, or uses no-ticket when appropriate.

Ticket reference validation: AI rule: 'The ticket ID in the branch name must match an active ticket in the issue tracker. CI validates this: a pre-push hook checks that the ticket exists and is in an active state (not closed, not cancelled). Branches with invalid ticket IDs: rejected by the hook.' The validation: prevents orphaned branches that reference non-existent tickets. The AI: creates branches with valid ticket references because the rules specify the format and CI enforces it. AI rule: 'Ticket integration transforms branch names from developer conventions into project management automation. The branch name: the single source of truth linking code changes to business requirements. The AI: maintains this link automatically.'

Descriptive Slug Conventions

Slug writing rules: AI rule: 'The slug describes the change in 2-4 words. Use kebab-case. Use nouns and verbs that describe the feature or fix, not the implementation. Good: user-notifications, login-timeout, auth-middleware. Bad: update-code, fix-bug, change-file. The slug: should be meaningful to someone who has not read the ticket.' The AI: generates descriptive slugs from the task description. The branch list: readable and informative.

Slug length and readability: AI rule: 'Minimum slug length: 2 words. Maximum slug length: 4 words (keep it scannable in git branch listings). If the feature needs more than 4 words to describe: summarize to the most important concept. "Add email notification preferences management UI" becomes: email-notification-prefs. "Fix race condition in concurrent payment processing" becomes: payment-race-condition.' The AI: summarizes long descriptions into concise slugs. The branch list: clean and scannable.

Slug uniqueness: AI rule: 'Branch slugs should be unique enough to distinguish from other active branches. If two developers are working on notifications: feat/PROJ-123-notification-preferences and feat/PROJ-456-notification-delivery. The ticket ID: provides uniqueness. The slug: provides context. Together: each branch is uniquely identifiable in any branch listing.' The AI: ensures slugs are specific enough to distinguish branches. The team: never confuses two notification branches because the slugs describe different aspects. AI rule: 'Descriptive slugs make the branch listing a project dashboard. Each branch name: a summary of what is being built, linked to a ticket, categorized by type. The AI generates this metadata automatically from the task description — zero developer overhead.'

Branch Naming Rules Quick Reference

Quick reference for AI coding branch naming rules.

• Format: type/TICKET-ID-descriptive-slug (e.g., feat/PROJ-123-user-notifications)
• Types: feat, fix, refactor, test, docs, chore — matches commit message types
• Special types: hotfix (urgent), release (version prep), experiment (prototype), deps (updates)
• Ticket ID: required, matches active issue tracker ticket, validated by CI pre-push hook
• Slug: 2-4 words, kebab-case, describes the feature/fix not the implementation
• Constraints: lowercase only, no spaces, max 60 chars, no reserved branch names
• Automation: type prefix triggers CI behavior (test suite, review requirements, deploy target)
• Key benefit: branch name communicates purpose, links to ticket, and triggers correct workflow