The Risk of Changing Shared CLAUDE.md

When you change a shared CLAUDE.md and push to main, every developer on the team gets the new rules immediately. Claude Code re-reads CLAUDE.md from disk after compaction, so the change takes effect during active sessions. A rule that seems obvious to you might break another developer’s workflow or cause Claude to generate code that conflicts with their in-progress branch.

This is not hypothetical. A team that changes “use Express error middleware” to “use custom error handler from src/errors/” will see Claude suddenly generate code that does not compile for anyone still on the old error handler branch.

Strategy 1: Branch and Test First

Before merging CLAUDE.md changes to main, test them on a branch:

# Create branch for the rule change
git checkout -b claude-md/add-result-type-rules

# Edit CLAUDE.md
# Add your new rules

# Test: ask Claude to generate code affected by the new rule
# Verify the output matches your expectation
# Check that existing patterns still work

# Open PR with test results
git push origin claude-md/add-result-type-rules

In the PR, include specific examples of code Claude generated with the new rules. This gives reviewers concrete evidence that the change works as intended.

Strategy 2: Phased Rollout with Advisory Rules

For significant changes, introduce rules in two phases:

# Phase 1: Advisory (merge to main immediately)
## Migration: Result Types
- NEW: Service methods should return Result<T, AppError> instead of throwing
- Existing code using try/catch is still valid during migration
- New code should prefer Result types when practical

This phase informs Claude about the new pattern without forcing it. Claude will start suggesting Result types for new code but will not rewrite existing code.

# Phase 2: Mandatory (merge after 2-week grace period)
## Error Handling (MANDATORY)
- Service methods MUST return Result<T, AppError>
- NEVER use try/catch for expected error cases in services
- Reserve try/catch for unexpected failures only

Phase 2 removes the advisory language. By this point, the team has had time to migrate existing code and adjust their workflows.

Strategy 3: Backward-Compatible Additions

When adding new rules, ensure they do not contradict existing ones:

# Existing rule:
## Testing
- Use Jest for all tests
- Tests colocated with source files

# Safe addition (does not contradict):
## Testing
- Use Jest for all tests
- Tests colocated with source files
- Integration tests in tests/integration/ directory
- Use test containers for database tests

Adding test containers for database tests is backward-compatible because it adds a new convention without changing existing ones. No developer’s current tests break.

Risky additions that need phased rollout:

• Changing naming conventions (camelCase to snake_case)
• Switching test frameworks (Jest to Vitest)
• Changing architecture patterns (MVC to hexagonal)
• Modifying error handling strategy (throw to Result)

Strategy 4: Use .claude/rules/ for Scoped Changes

New rules that apply only to specific file types can go in .claude/rules/ without touching the root CLAUDE.md. This limits the blast radius:

# .claude/rules/api-v2.md
---
paths:
  - "src/api/v2/**/*.ts"
---

## API v2 Rules
- Use the new response envelope from src/responses/v2-envelope.ts
- Include pagination metadata in all list endpoints
- Validate with zod strict mode

This file affects only v2 API code. Developers working on v1 endpoints see no change in Claude’s behavior. When v2 is fully rolled out, move the rules to the root CLAUDE.md and remove the v1-specific patterns.

Communication Checklist

Before merging a CLAUDE.md change:

1. Open a PR with the change and tag affected team members
2. Include examples of Claude’s output with the new rules
3. Note whether the change is additive (safe) or modifying (needs migration)
4. Set a merge date that gives the team time to prepare
5. After merge, post in the team channel with a summary of what changed

Monitoring After Rollout

After merging, watch for these signals that the change caused problems:

• Team members report Claude generating unexpected code
• CI failures increase on branches created after the change
• Developers adding CLAUDE.local.md overrides to bypass new rules

If problems appear, revert the change immediately with git revert. Investigate the issue on a branch before re-introducing the rule.

Handling Emergency Rule Changes

Sometimes a rule change cannot wait for phased rollout. A security vulnerability, a breaking API change, or a compliance requirement might need immediate enforcement:

# Emergency: add security rule immediately
echo "" >> CLAUDE.md
echo "## EMERGENCY SECURITY RULE (added $(date +%Y-%m-%d))" >> CLAUDE.md
echo "- NEVER log request bodies containing authorization headers" >> CLAUDE.md
git add CLAUDE.md
git commit -m "security: emergency CLAUDE.md rule to prevent auth header logging"
git push origin main

For emergencies, skip the phased approach but still notify the team immediately. Add a comment with the date so the rule can be reviewed and integrated properly in the next regular CLAUDE.md audit.

For the full review workflow including CODEOWNERS setup, see the version control strategies guide. For resolving contradictions between instruction files, see the conflict resolution guide. For the foundational guide to how CLAUDE.md loads, see the complete guide.