CLAUDE.md für Claude Code hinzugefügt

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

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644 (file)
index 0000000..24aaf4a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Purpose
+
+This is a **Kafka training repository** used for teaching Apache Kafka concepts. It uses a branch-per-exercise model where each exercise lives on its own Git branch. The `scripting` branch (current) contains only management scripts — actual exercise code lives on other branches.
+
+## Branch Structure
+
+Branches follow a naming convention that encodes their role:
+
+| Suffix | Meaning |
+|--------|---------|
+| *(none)* | Solution / Musterlösung |
+| `--vorlage` | Exercise template for students to start from |
+| `--livecoding` | Live-coding demo starting point |
+| `--livecoding--schritte` | Step-by-step increments of a live-coding session |
+
+Branch name prefixes group exercises by topic:
+- `grundlagen/*` — Plain Java Kafka client basics
+- `producer/*` — Producer-focused exercises (advanced)
+- `consumer/*` — Consumer-focused exercises (advanced)
+- `springkafka/*` — Spring Kafka API exercises
+- `config/*` — Docker/infrastructure configuration examples
+
+Each branch variable in `BRANCHES.sh` has a corresponding `__ROOT` variable that defines its rebase parent, forming a directed dependency chain of exercises.
+
+## Each Exercise Branch
+
+A typical exercise branch contains:
+
+- `README.sh` — the canonical way to run the exercise (builds, starts Docker Compose, runs demo)
+- `docker/docker-compose.yml` — local Kafka cluster setup
+- `pom.xml` and/or `build.gradle` — Maven/Gradle build (Java 21, Spring Boot 4.0.2)
+- `src/` — Java source code (group `de.juplo.kafka`)
+
+Run an exercise:
+```bash
+git checkout <branch>
+./README.sh           # start and demo
+./README.sh build     # build only
+./README.sh cleanup   # tear down Docker, clean build artifacts
+```
+
+## Scripting Branch Scripts
+
+All scripts source `BRANCHES.sh` first, which defines the full branch list and parent relationships.
+
+| Script | Purpose |
+|--------|---------|
+| `BRANCHES.sh` | Defines all branch names and their `__ROOT` parents |
+| `REBASE.sh` | Rebases every branch onto its `__ROOT` parent |
+| `BUILD.sh` | Checks out each branch and builds with Maven + pushes Docker image |
+| `GRADLE.sh` | Same as BUILD.sh but using Gradle |
+| `MAVEN.sh` | `mvn clean install` + `mvn docker:push` for all branches |
+| `PUSH.sh` | Force-pushes all branches to origin (creates timestamped backup tags first) |
+| `RESET.sh` | Resets all branches to `origin/<branch>` or to a tag prefix (`./RESET.sh <prefix>`) |
+| `TAG.sh` | Tags all branches as `<branch>--<prefix>` and pushes tags (`./TAG.sh <prefix>`) |
+| `DIFF.sh` | Diffs every branch against remote (or against a tag suffix if given) |
+| `COPY.sh` | Copies branches to `../vorlagen`, `../livecoding`, `../spickzettel` directories |
+| `patch_gradle_for_si_nexus.sh` | Patches `build.gradle`/`settings.gradle` to use internal Nexus mirror |
+
+Always return to `scripting` after bulk operations — scripts `git checkout scripting` at the end.
+
+## Adding a New Exercise Branch
+
+1. Add the variable name and value (branch name) to `BRANCHES.sh`.
+2. Add the corresponding `__ROOT` variable pointing to the parent branch.
+3. Add the variable name to the `BRANCHES` list inside `BRANCHES.sh`.
+4. Run `./REBASE.sh` to verify the chain is consistent.
+5. Run `./PUSH.sh` to publish.
+
+## Key Constraints
+
+- `PUSH.sh` force-pushes — it is intentional and expected for this training workflow.
+- `--vorlage` branches are skipped by build scripts (they are incomplete by design).
+- The `grundlagen/docker` branch is not in `$BRANCHES` but is handled explicitly in several scripts (PUSH, DIFF, RESET, TAG).