From 756bc95fab131867e55d754ab2b917532bf46a04 Mon Sep 17 00:00:00 2001
From: Felix Weinberger <fweinberger@anthropic.com>
Date: Fri, 16 Jan 2026 10:01:50 +0100
Subject: [PATCH] docs: add breaking changes guidance to CLAUDE.md

---
 CLAUDE.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index cc2d360602..e8d82ffc42 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,6 +51,17 @@ This document contains critical information about working with this codebase. Fo
 - NEVER ever mention a `co-authored-by` or similar aspects. In particular, never
   mention the tool used to create the commit message or PR.
 
+## Breaking Changes
+
+When making breaking changes, document them in `docs/migration.md`. Include:
+
+- What changed
+- Why it changed
+- How to migrate existing code
+
+Search for related sections in the migration guide and group related changes together
+rather than adding new standalone sections.
+
 ## Python Tools
 
 ## Code Formatting