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
This commit is contained in:
Thore Cimbal
co-authored by
Claude Fable 5
Claude Fable 5
parent
fdf30d42e1
commit
cc0d4d3e02
@@ -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.*
|
||||
Reference in New Issue
Block a user