CLAUDE.md Is Code — Version It Like Code

Your CLAUDE.md controls how Claude Code generates and modifies your project’s source code. A bad rule change can cause Claude to generate incorrect patterns across your entire codebase. This makes CLAUDE.md changes as consequential as changes to your linter config, CI pipeline, or build system – they deserve the same review rigor.

Branch Strategy for CLAUDE.md Changes

Treat CLAUDE.md changes as infrastructure changes, not documentation updates:

# Create a branch for the rule change
git checkout -b claude-md/add-api-versioning-rules

# Make the change
# Edit CLAUDE.md to add API versioning rules

# Commit with clear intent
git add CLAUDE.md
git commit -m "feat(claude-md): add API versioning rules for v2 migration"

# Open PR for team review
git push origin claude-md/add-api-versioning-rules

The branch naming convention claude-md/ makes it easy to filter these changes in PR lists and set up CODEOWNERS rules.

PR Review Workflow for CLAUDE.md

CLAUDE.md changes need review by developers who will be affected. Set up CODEOWNERS:

# .github/CODEOWNERS
CLAUDE.md                    @team-lead @senior-devs
.claude/rules/security.md    @security-team
.claude/rules/api-design.md  @platform-team
.claude/skills/              @team-lead

In the PR description, include:

## CLAUDE.md Change

### What changed
Added API versioning rules to enforce /api/v1/ prefix and deprecation headers.

### Why
We are starting the v2 migration next sprint. Claude needs to generate
v1-compatible code by default and flag breaking changes.

### Testing
Asked Claude to generate a new API endpoint with these rules loaded.
Verified it used /api/v1/ prefix and included versioning headers.

Tracking Changes Over Time

Git log on CLAUDE.md shows the evolution of your project’s conventions:

# View CLAUDE.md change history
git log --oneline --follow CLAUDE.md

# See what changed in each commit
git log -p --follow CLAUDE.md

# View history of all instruction files
git log --oneline -- CLAUDE.md .claude/rules/ .claude/skills/

This history is valuable during onboarding. New team members can read the commit messages to understand not just what the rules are, but why they were added and when.

Handling CLAUDE.md Conflicts

When multiple developers change CLAUDE.md simultaneously, git merge conflicts occur. The fix is straightforward because CLAUDE.md is structured as independent sections:

<<<<<<< HEAD
## Error Handling
- Return Result types from services
- Log errors at WARN level for 4xx
=======
## Error Handling
- Return Result types from services
- Log errors at ERROR level for 5xx
- Include request ID in all error logs
>>>>>>> feature/error-logging

Resolution: keep both non-contradictory additions. If rules conflict, discuss in the PR. Claude concatenates all rules and picks arbitrarily on contradictions, so conflicts must be resolved by humans.

Rules Directory Version Control

The .claude/rules/ directory should also be committed:

.claude/
  rules/
    testing.md            # committed — team testing standards
    api-design.md         # committed — API conventions
    security.md           # committed — security requirements
  settings.json           # committed — team tool permissions
  settings.local.json     # gitignored — personal permissions

Each rules file has its own change history. Security rules might change weekly. Testing rules might be stable for months. Separate files mean separate review and change tracking.

Migration Strategy for Rule Changes

When adding a rule that affects existing code, use a phased approach:

# Phase 1: Add the rule as advisory (week 1)
## New: API Response Envelope
- Starting next sprint, all new API endpoints use the response envelope
- Existing endpoints will be migrated gradually

# Phase 2: Make it mandatory (week 3)
## API Response Envelope (MANDATORY)
- ALL API endpoints use the response envelope from src/responses/envelope.ts
- No exceptions for new code
- Legacy endpoints tracked in docs/migration/envelope-migration.md

This prevents Claude from rewriting working code to match new rules before the team is ready.

Rollback

If a CLAUDE.md change causes problems, revert it like any code change:

# Revert a specific CLAUDE.md commit
git revert <commit-hash>

Because Claude re-reads CLAUDE.md from disk after compaction, the reverted rules take effect in the current session without restarting.

Automated Validation in CI

Add CI checks that validate CLAUDE.md integrity on every PR:

# .github/workflows/claude-md-check.yml
name: CLAUDE.md Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check line count
        run: |
          LINES=$(wc -l < CLAUDE.md)
          if [ "$LINES" -gt 200 ]; then
            echo "::error::CLAUDE.md exceeds 200 lines ($LINES)"
            exit 1
          fi

      - name: Check for contradictions
        run: |
          # Flag if same keyword appears in multiple instruction files
          for topic in indent export error naming; do
            COUNT=$(grep -rl "$topic" CLAUDE.md .claude/rules/ 2>/dev/null | wc -l)
            if [ "$COUNT" -gt 1 ]; then
              echo "::warning::Topic '$topic' appears in $COUNT instruction files"
            fi
          done

This prevents the most common version control problems: files growing too long and contradictions introduced by concurrent edits.

Tagging Major Changes

For significant CLAUDE.md revisions (new architecture rules, framework migrations), use git tags:

git tag claude-md-v2.0 -m "Major: switched to Result types for error handling"

Tags let you correlate Claude’s behavior changes with instruction changes. If Claude starts generating different patterns after a deploy, you can check which CLAUDE.md version was active.

For the foundational guide to CLAUDE.md files, see the complete guide. For deciding what goes in shared versus personal files, see the team vs personal guide. For sharing standards across multiple repositories, see the cross-team sharing guide.