CLAUDE.md: Principle of minimal diffs between chained branches documented

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

diff --git a/CLAUDE.md b/CLAUDE.md
index 9c1eb4f1cdaa61926426ec0e5272498f284bcdd2..e3679bc9cba4f2e8b5c15f487a2f4eab4209f149 100644 (file)
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -136,6 +136,17 @@ Always return to `scripting` after bulk operations — scripts `git checkout scr
 
 ## Commit Conventions
 
+### Minimal Diffs Between Chained Branches
+
+When introducing changes in a branch, deliberate care is taken to keep the diff against the parent branch as small as possible. The goal is that a diff between a later branch and one of its ancestors shows **only what the later branch actually adds** — no noise from unrelated reformatting or restructuring.
+
+This is essential for two reasons:
+
+1. **Overview**: The author can always clearly see what a branch changes relative to its origin.
+2. **Teaching**: The diff is used directly in exercises — for example to show participants exactly which boilerplate disappears when Spring Boot or Spring Kafka features are activated step by step.
+
+**Implication for rebases**: When an improvement is introduced in an early branch (e.g. removing the `Dockerfile` and obsolete Maven plugins), all downstream branches must adopt this improvement consistently. An `-- ALIGN` commit must **not** re-introduce removed elements. It should contain only the branch-specific changes (e.g. updating `mainClass` from `ExampleProducer` to `ExampleConsumer` in the Jib configuration).
+
 ### MOVE / ALIGN Split
 
 When a class or file is moved to a new branch (or a new spin-off is created from an existing class), the change is always split into exactly two commits: