From cc0d4d3e02c089ff7f231e61954020995a9cf43a Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Sat, 1 Aug 2026 12:00:00 +0000 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01PKhFj1S3UdD6xL2fbWPeYj --- CLAUDE.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 153 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..03b504a --- /dev/null +++ b/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.* diff --git a/README.md b/README.md index bef3d1a..05048d7 100644 --- a/README.md +++ b/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** |