project-baseline
Ein testbarer Bereitschaftsstandard: 69 Regeln, jede gestützt durch eine Prüfung, die ein Node-Runner ohne Abhängigkeiten in einem Repository im Ruhezustand ausführt. Blockers führen zu CI-Fehlschlägen (exit 1); die Ermessensentscheidungen, die ein Skript nicht treffen kann, werden über ein datiertes Signoff-Ledger gelöst. Der springende Punkt: Vertraue keinem schriftlichen Versprechen – lass etwas es prüfen.
Das Toolkit befindet sich neben dieser Datei: check.mjs (Runner), rules.json (die 69 Regeln), config.example.json, templates/, README.md (Schnellstartanleitung), REFERENCE.md (vollständige Referenz: Regel-Tabelle, Kategorien, Architekturdiagramme, CI-Anbindung) und GLOSSARY.md (einfache Erklärungen der DevOps/Lieferketten-Begriffe).
Löse das Skill-Verzeichnis zuerst auf. $SKILL_DIR im Folgenden bedeutet der absolute Pfad des Verzeichnisses, das diese SKILL.md enthält – löse es in einen konkreten Pfad auf, bevor du einen Befehl ausführst (übergib den Literal-String $SKILL_DIR nicht an die Shell). Es ist typischerweise ~/.claude/skills/baseline. check.mjs lädt rules.json aus seinem eigenen Verzeichnis, daher müssen die beiden zusammenbleiben; rufe den Runner immer mit seinem absoluten Pfad auf (node "<abs>/check.mjs" …) und kopiere ihn nicht woanders hin. Der Runner benötigt nur Node ≥ 18 und git; falls node fehlt, teile dies dem Benutzer mit, anstatt zu raten.
Bei Aufruf
Ermittle die Absicht aus den Worten des Benutzers und wähle einen Modus. Standardmäßig wird score verwendet, wenn nichts angegeben ist.
Modus: score (Standard) — "Baseline ausführen", "/baseline", "Repo prüfen"
- Wähle das Ziel-Repository: einen expliziten Pfad in der Anfrage, sonst das aktuelle Arbeitsverzeichnis. Bestätige, dass es wie ein Repository aussieht (hat ein Manifest oder
.git). - Führe den Runner aus (menschenlesbar):
node "$SKILL_DIR/check.mjs" --repo <target>- Füge
--no-exechinzu, wenn DU das Bootstrap-/Testkommando des Repositorys NICHT ausführen darfst (BUILD-05) – z.B. bei nicht vertrauenswürdigem Repo, keine Zeit zum Testen oder das Kommando ist nicht konfiguriert. Bevorzuge die Ausführung, wenn es sicher ist, da BUILD-05 die Kronjuwel-Prüfung ist. - Füge
--profile advancedhinzu, wenn der Benutzer die Expertenregeln wünscht (SBOM, Code-Scanning, Mutationstests, Symbolintegrität, Abhängigkeits-Schwachstellenscan, Coverage-Mindestwert). Dasservice-Profil wird automatisch aktiviert, wennproject_type=servicegesetzt ist. - Füge
--jsonhinzu, wenn du die Ergebnisse programmatisch parsen willst, anstatt die Scorecard anzuzeigen.
- Füge
- Präsentiere dem Benutzer das Ergebnis, führe mit Blockern (diese lassen CI fehlschlagen), dann mit Warnungen, die zu beheben sind. Gruppiere nach Kategorie. Gib nicht alle 69 Zeilen aus – fasse zusammen: Bereitschaftsprozentsatz, Anzahl der Blocker und die spezifischen Fehlschläge/bemerkenswerten Warnungen mit ihrer einzeiligen Detailangabe. Biete an, sie zu beheben oder zu ergänzen.
Modus: init — "Baseline hier einrichten", "Standard übernehmen", "Baseline bereitstellen"
- Kopiere das Toolkit in das Repository (empfohlen:
tools/baseline/) oder referenziere es direkt vor Ort. - Ergänze die Artefakte, nur wenn sie fehlen (überschreibe niemals ohne Nachfrage):
cp "$SKILL_DIR/config.example.json" <repo>/baseline.config.json cp "$SKILL_DIR/templates/CLAIMS.json" <repo>/docs/CLAIMS.json # nur wenn das Repository externe Behauptungen aufstellt cp "$SKILL_DIR/templates/start-here.md" <repo>/docs/start-here.md # wenn kein Statusdokument existiert mkdir -p <repo>/.project-baseline && cp "$SKILL_DIR/templates/signoff.json" <repo>/.project-baseline/signoff.json - Passe
baseline.config.jsonan die Realität des Repositorys an: setzeproject_type,bootstrap_command(das Installations- und Testkommando für BUILD-05) undmakes_external_claims(false überspringt die CLAIM-*-Regeln). Die optionalen*_globs-Schlüssel (frische/generiert/grounding) bleiben leer, bis das Repository diese Konventionen übernimmt. - Zeige dem Benutzer die CI-Einbindung aus der
README.mdund mache denbaseline-Job zu einer erforderlichen Prüfung (das ist Regel BUILD-06). - Führe einen ersten Score-Lauf durch.
Modus: fix — "Baseline-Fehler beheben", "dies auf grün bekommen"
- Führe zuerst den Score-Lauf durch. Wende für jeden Blocker/jede Warnung, den/die der Benutzer adressiert haben möchte, das
fix-Feld der Regel (lies es ausrules.json) als konkrete Änderungen am Repository an – füge die fehlende Lizenz hinzu, pinne die Aktion auf einen SHA, füge.envzu.gitignorehinzu und dreh das Secret, füge den Negativtest hinzu usw. - Führe bei
manual(Signoff-)Regeln keine Prüfung vor – hilf dem Benutzer bei der Entscheidung (Auswirkungsradius, Stand-der-Technik-Prüfung, Wedge/Moat) und zeichne einen datierten Eintrag in.project-baseline/signoff.jsonauf. - Führe erneut einen Score-Lauf durch, um zu bestätigen.
Modus: explain — "Was prüft SEC-03?", "Warum ist CTX-05 fehlgeschlagen?"
Lies die Regel aus rules.json (jede hat title, rationale, fix, source und den check) und erkläre sie verständlich, plus was der Runner tatsächlich überprüft hat. Bei unbekanntem Jargon (SBOM, SLSA, Provenance, Signoff-Ledger, …) enthält GLOSSARY.md in diesem Verzeichnis einfach erklärte Definitionen.
Wie der Runner entscheidet (damit du Detailzeilen interpretieren kannst)
- PASS / FAIL / WARN / SIGN-OFF / SKIP pro Regel. Nur
blocker-Fehlschläge setzen den Exit-Code 1. - SKIP bedeutet, die Regel traf nicht zu: falscher
project_type(n/a für <type>), ein deaktiviertes Profil (Profil 'advanced' aus), eine nicht übernommene optionale Funktion oder nichts zu prüfen. Ein Skip zählt nie gegen die Bereitschaft. - Profile:
coreläuft immer;serviceläuft automatisch, wennproject_type=service;advancedläuft nur mit--profile advancedoderprofiles:["advanced"]in der Konfiguration. - Claims sind optional: CLAIM-* werden nur ausgeführt, wenn ein Claims-Register existiert oder
makes_external_claims:trueexplizit gesetzt ist. Ein Repository ohne Claims-Register wird nicht bestraft. - Die Konfiguration erkennt sinnvoll automatisch;
baseline.config.jsonim Repository-Stammverzeichnis überschreibt. Die Schlüssel sind inconfig.example.jsondokumentiert. - Der Runner hat keine Abhängigkeiten (Node ≥ 18 + git) und ist absturzsicher: Eine Regel, deren Prüfung nicht ausgewertet werden kann, degradiert zu SKIP und bringt den Lauf nie zu Fall.
Hinweise
- Stelle eine Warnung nie als Blocker dar oder umgekehrt – der Schweregrad steht in
rules.jsonund in der Ausgabe des Runners. - Bevorzuge es, BUILD-05 tatsächlich auszuführen (lasse
--no-execweg), wenn das Repository vertrauenswürdig ist und das Bootstrap-Kommando gesetzt ist – eine grüne Kronjuwel-Prüfung ist das stärkste Einzelsignal. - Die vollständige Begründung, Regel-Tabelle, Kategoriebeschreibungen, Architekturdiagramme und CI-Codeausschnitt befinden sich in der
REFERENCE.mddieses Verzeichnisses – lies sie, wenn der Benutzer in die Tiefe gehen möchte.