CLAUDE.md: kanonische Arbeitskonventionen fuer alle Agenten-Sessions

Uebergreifende Teile der gitops-CLAUDE.md (ThreadNet Server Suite) hierher
gehoben und erweitert: Topologie-Regeln, Kanban-Framework (ADR-0005),
Secrets-Handling, gelebte Lehren; Karpathy-Guidelines wortgleich uebernommen
(unantastbar). Lesbar von ueberall via Gitea-Mirror sorb/management.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PKhFj1S3UdD6xL2fbWPeYj

CLAUDE.md

@@ -0,0 +1,152 @@
+# CLAUDE.md — übergreifende Arbeitskonventionen (kanonisch)
+
+Diese Datei gilt für **jede Claude-/Agenten-Session in allen Projekten** der
+Gruppe (axion1337.chat-Stack, ThreadNet-Repos, CFGMON/threadnet-operating,
+Homelab). Projekt-Repos haben eigene CLAUDE.mds für ihre Spezifika (z. B. die
+ESS-/Flux-Details in „ThreadNet Server Suite" = `axion1337.chat-gitops`) — bei
+Widerspruch gilt für Arbeitsweise und Prozess **diese** Datei.
+
+> **Für Sessions ohne Lab-Zugang** (CFGMON, MATRIX, …): dieses Repo ist als
+> Push-Mirror unter `https://rohana.axion1337.de/sorb/management` von überall
+> **lesbar** — dort diese Datei und die ADRs nachschlagen. Nur pushen ist tabu.
+
+## Projektrealitäten (Stand 2026-08-01)
+
+**Das Lab ist die Quelle der Wahrheit** ([ADR-0002](decisions/0002-issues-und-management-ins-lab.md)):
+
+- Kanonische Repos liegen auf `git.lab/axion1337.chat/*` (nur im Lab/VPN
+  auflösbar). Gitea/rohana wird per **Push-Mirror** beliefert und bleibt
+  Flux-Source, Container-/npm-Registry und Release-Download
+  ([ADR-0001](decisions/0001-gitlab-kanonisch-push-mirror.md)).
+- **Nie direkt zu Gitea pushen** (gespiegelte Repos) — der Mirror überschreibt
+  per Force. Landet doch ein Commit auf Gitea (z. B. aus einer Host-Session
+  ohne Lab-Route): **Kanonisierungs-Verfahren** in
+  [verfahren/deploy-uebergabe.md](verfahren/deploy-uebergabe.md) — `.patch`
+  von Gitea ziehen, `git am` (erhält Autorschaft), Push über git.lab.
+- **Issues leben auf git.lab.** Die alten Gitea-Issues sind geschlossen und
+  verweisen dorthin. ⚠️ gitops-Nummern haben sich beim Umzug verschoben
+  (Gitea zählte PRs mit; z. B. Gitea#48 → GitLab#46) — alte „gitops#N"-Verweise
+  meinen die Gitea-Nummer; verbindlich ist der Migrations-Fußtext im Issue.
+- **Ausnahmen** (beide bewusst entschieden): Deploy-Übergabe-Issues laufen auf
+  dem Gitea-Tracker `sorb/management`, bis das Site-to-Site-VPN steht
+  ([ADR-0004](decisions/0004-site-to-site-vpn-hetzner-lab.md)); der
+  TURN-Rotations-CronJob öffnet seine PR weiter auf Gitea (nie dort mergen —
+  Kanonisierung wie oben).
+
+## Arbeitsframework ([ADR-0005](decisions/0005-pm-framework-kanban.md))
+
+Kanban-Rückgrat mit leichten Scrum-Elementen:
+
+- **Alles Offene ist ein Issue** — host-/infra-Scope hier im management-Projekt
+  (`host:`-Labels, alte IDs wie `CFGMON-01` bleiben im Titel), Projekt-Scope im
+  jeweiligen Projekt. Kein neues Backlog-Markdown anlegen; `hosts/`/`shared/`
+  sind nur Bestand + Historie.
+- **Status über Labels**, genau eins pro Issue: `status:next` (die einzige
+  Zusage), `status:doing` (**WIP-Limit 2** — auch sessionübergreifend zu
+  verteidigen), `status:wartet` (nur mit benanntem Grund). Ohne Label = Backlog.
+- **ADR-Pflicht** ([decisions/](decisions/)) bei Architektur-/Prozess-
+  entscheidungen und **jeder dauerhaften Ausnahme von einer Regel**. Eine
+  Ausnahme nur zu dokumentieren statt sie als Entscheidung vorzulegen, ist ein
+  Fehler.
+- **Deploy-Übergaben** („einer baut, ein anderer rollt aus") laufen über das
+  Issue-Template und die Pflichtfelder in
+  [verfahren/deploy-uebergabe.md](verfahren/deploy-uebergabe.md) — das ist
+  unsere Definition of Done für Deployments. Nach Deploys mit Übergabe und nach
+  Incidents: **AAR** ([verfahren/aar/](verfahren/aar/), Vorlage liegt daneben).
+- Prioritäten über `priority:*`; Zeitkritisches bekommt ein **Datum** im Issue,
+  nicht „bald".
+
+## Secrets & Credentials
+
+- **Token-/Secret-Werte niemals anzeigen, loggen oder in Dateien echoen** —
+  anzeigen = Exposure = Rotation. Echte Credentials tippt/legt sorb selbst an;
+  Sessions referenzieren sie nur über Dateipfade (z. B.
+  `~/.config/gitlab-lab/token`) oder maskierte CI-Variablen.
+- Nicht-geheime Konfiguration wird direkt geschrieben und committet — die
+  Trennung ist „Credential vs. Config", nicht „alles über den Menschen".
+
+## Redlichkeit & gelebte Lehren
+
+- **Aussagen mit Quelle:** Verifiziert (Messung/Konsole) klar von Vermutung
+  trennen; nicht selbst Geprüftes als solches kennzeichnen. Korrelation ≠
+  Kausalität — ein plausibler Verdacht ist kein Befund.
+- **Config-Dateien textuell/chirurgisch editieren, nie re-dumpen** (YAML/JSON
+  neu serialisieren hat zweimal real Schaden angerichtet). Compose-/YAML-
+  Änderungen vor dem Push validieren (`docker compose config`, YAML-Parse).
+- Fehlschläge und übersprungene Schritte werden benannt, nicht geglättet;
+  „fertig" heißt verifiziert.
+
+---
+name: karpathy-guidelines
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+license: MIT
+---
+
+# Karpathy Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+*Der Karpathy-Block oben ist wortgleich aus der gitops-CLAUDE.md übernommen und
+darf nicht bearbeitet werden (stehende Regel von sorb). Änderungen an dieser
+Datei insgesamt: nur mit sorb abgestimmt — sie ist die gemeinsame
+Arbeitsgrundlage aller Sessions.*

README.md

@@ -29,6 +29,7 @@ noch nicht erreichen. Abgelöst wird das durch das Site-to-Site-VPN
 
 | Pfad | Artefakt |
 |---|---|
+| [`CLAUDE.md`](CLAUDE.md) | **Kanonische Arbeitskonventionen für alle Agenten-Sessions** (Topologie, Framework, Secrets, Karpathy-Guidelines) |
 | `vision/` | Eine Vision je Linie: Community (axion1337.chat), Tool (ThreadNet), Plattform (Homelab) |
 | `roadmap.md` | Linien, Meilenstein-Kandidaten, Kadenz — GitLab-Milestones halten den Stand |
 | `decisions/` | ADRs — Pflicht bei Architekturentscheidungen **und dauerhaften Ausnahmen** |