2026-08-01 12:00:00 +00:00
# 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.
2026-08-06 12:00:00 +00:00
>
> 📋 **Kopierbare Kurzfassungen zum Voranstellen:**
> [verfahren/textbloecke.md](verfahren/textbloecke.md) — Session-Start, Host-Session,
> Deploy-Übergabe, Abschluss, Entscheidungsvorlage. Diese Datei hier bleibt die
> Quelle; die Bausteine verweisen nur darauf.
2026-08-01 12:00:00 +00:00
## 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 )).
2026-08-02 12:00:00 +00:00
- **Warum überhaupt zwei Orte — und warum das kein Altbestand ist:** Auf git.lab
liegen die *Baupläne* , auf Gitea eine Kopie, die der Cluster **ohne verfügbares
Lab** erreicht. Der Hetzner-Cluster muss sich bauen und neu ausrollen lassen,
wenn das Homelab aus ist, im Umbau steckt oder niemand zu Hause ist — er darf
deshalb nicht von einem Host abhängen, der nur im Lab antwortet.
⚠️ **Die Flux-Quelle nicht „geradeziehen"** auf git.lab: Das sähe aufgeräumter
aus und würde die Verfügbarkeit der Produktion an das Lab koppeln — genau das,
was die Trennung verhindert.
2026-08-01 12:00:00 +00:00
- **Nie direkt zu Gitea pushen** (gespiegelte Repos) — der Mirror überschreibt
2026-08-02 12:00:00 +00:00
per Force.
- **Gespiegelt wird nur die Gruppe `axion1337.chat` ** (die fünf Produkt-Repos und
`management` ). Die Gruppe ** `homelab` ** (`docs` , `wiki` , `wiki-bookstack` ) hat
bewusst **keine Mirrors** : Sie beschreibt und konfiguriert ausschließlich
Lab-Infrastruktur, und seit dem Site-to-Site-VPN
([ADR-0004 ](decisions/0004-site-to-site-vpn-hetzner-lab.md )) erreichen auch
Host-Sessions git.lab direkt — Tunnel einschalten genügt. Betriebslehren, die
von außen lesbar sein müssen, gehören deshalb in die **AARs** unter
`verfahren/aar/` (dieses Repo ist gespiegelt), nicht nur in die READMEs der
2026-08-02 12:00:00 +00:00
Lab-Repos.
- Landet doch ein Commit auf Gitea (z. B. aus einer Host-Session ohne Lab-Route):
**Kanonisierungs-Verfahren** in
2026-08-01 12:00:00 +00:00
[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.
2026-08-02 12:00:00 +00:00
- **Ausnahme** (bewusst entschieden, nur noch eine): der
2026-08-02 12:00:00 +00:00
TURN-Rotations-CronJob schreibt weiter nach Gitea, weil er im Cluster läuft und
git.lab nicht erreicht.
**Die Rotation nicht von Hand nachziehen und den PR nie auf Gitea mergen** —
das erledigt seit 2026-08-02 der geplante CI-Job `canonize_rotation` im
gitops-Repo täglich von git.lab aus. Scheitert er, bleibt die Pipeline rot;
diese rote Pipeline **ist** der Alarm, einen zusätzlichen Termin gibt es
bewusst nicht.
2026-08-01 12:00:00 +00:00
- **Dokumentation** ([ADR-0006 ](decisions/0006-wikis-konsolidieren-docusaurus.md )):
Das gitops-Wiki liegt seit 2026-08-02 auf git.lab (*Wiki*-Reiter im Projekt);
⚠️ der `wiki` -**Branch** im gitops-Repo ist ein überholter Mai-Abzug von `docs/`
und nicht die gepflegte Fassung. Alle Quellen zusammen erscheinen unter
2026-08-02 12:00:00 +00:00
**axionwiki.lab** ([`homelab/wiki` ](https://git.lab/homelab/wiki ), Docusaurus) —
2026-08-01 12:00:00 +00:00
Inhalte werden beim Bau geholt, **Änderungen gehören ins Quell-Repo** .
2026-08-01 12:00:00 +00:00
## 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".
2026-08-06 12:00:00 +00:00
- **Der Titel trägt keine Priorität.** Präfixe wie `[HIGH]` /`[MEDIUM]` /`[LOW]`
gehören nicht in den Titel — die Priorität steht im Label, und zwar nur dort.
Alte Kennungen wie `CFGMON-01` bleiben, die benennen den Gegenstand, nicht die
Dringlichkeit.
⚠️ Der Grund ist keine Ästhetik: Aus der Gitea-Migration trugen 34 Issues ein
Präfix, davon **zwei mit einer anderen Aussage als ihr Label** — wer nach Titel
sortierte, bekam ein anderes Bild als wer nach Label sortierte. Zwei Wahrheiten
über dieselbe Sache sind schlimmer als eine unvollständige. Bereinigt 2026-08-06.
- **Jedes Issue gehört zu genau einem Meilenstein** (Gruppen-Milestones M1–
siehe [roadmap.md ](roadmap.md )). Label und Meilenstein beantworten verschiedene
Fragen: `priority:*` sagt **wie dringend** , der Meilenstein sagt **worauf es
einzahlt**. Ein Issue ohne Meilenstein taucht in keiner Roadmap-Ansicht auf und
ist damit praktisch unsichtbar — es existiert nur noch für den, der es angelegt
hat.
M1– **bewusst kein Enddatum** : Sie bündeln, sie simulieren keinen
Termindruck. Termindruck steht als Datum am einzelnen Issue.
2026-08-01 12:00:00 +00:00
## 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.*
