Merge Strategies

CLAUDE.md merge conflicts are inevitable on active teams. Two developers add rules in the same section, or one developer reorders while another adds, and git cannot resolve the difference. The standard git merge conflict resolution — pick one side, discard the other — is particularly dangerous for CLAUDE.md because discarding a rule is not a cosmetic loss. It is removing a constraint that might prevent a production bug.

The structural solution is sectioned ownership. Divide CLAUDE.md into clearly delimited sections with markdown headers, and assign each section an owner. The architecture section is owned by the tech lead. The build commands section is owned by the DevOps engineer. The gotchas section is owned by whoever encountered the gotcha most recently. When merge conflicts arise, the section owner resolves them.

A more robust approach for larger teams is to use the .claude/ directory structure. Instead of one monolithic CLAUDE.md, create multiple files: .claude/rules/security.md, .claude/rules/architecture.md, .claude/rules/conventions.md. Claude loads all files in the .claude/ directory, so the behavior is identical. But now two developers can edit different rule files simultaneously without merge conflicts. The root CLAUDE.md becomes a lightweight index that points to the rule files and establishes loading order.

This pattern also enables code review on rules. A PR that modifies .claude/rules/security.md automatically routes to the security team for review. A PR that modifies .claude/rules/architecture.md routes to the tech lead. The rules get the same review rigor as the code they govern.