Files

T

martinandClaude Opus 4.6 cff9549617 feat: Clean-Code-Kommentarregel in Implementierungsphasen verankern

Explizite No-Comment-Regel in /story Phase 4, /implement Phase 4
und /script V1+V2, damit Sonnet bei der Implementierung keine
überflüssigen Kommentare generiert.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-06-08 07:30:16 +02:00

7.0 KiB

Raw Blame History

description: Bash-Script-Lifecycle nach Best Practices — Aufgabenklärung → Scope-Einschätzung → Schnell- oder Vollpfad → shellcheck → PR → Merge. Aktivieren für jede Bash-Script-Aufgabe: neues Script, Feature, Bugfix, Refactoring. Nicht verwenden für andere Shells (sh/zsh/fish), Python-/Node-Scripts oder einfache Einzeiler/Aliase. model: claude-opus-4-6

/script — Bash-Script-Lifecycle

Nicht-verhandelbare Mindeststandards — gelten für beide Pfade:

Feature-Branch
shellcheck (alle Befunde beheben)
PR erstellen, Approval abwarten, mergen

Vorab: Repository-Check

git rev-parse --show-toplevel

Scheitert der Befehl: Abbruch. Der Skill arbeitet ausschließlich innerhalb eines Repos. Meldung an den User:

"Kein Git-Repository gefunden. Starte /script erst nach git init oder aus einem bestehenden Repo."

Phase 0: Aufgabenklärung + Scope-Einschätzung

0a: Aufgabe klären

Lies das betroffene Script (falls vorhanden) und den Request. Stelle offene Fragen, falls nötig — aber nur solche, die den Lösungsweg beeinflussen:

Bei Bugfixes: Was ist das erwartete Verhalten? Was passiert stattdessen? Wie lässt sich der Fehler reproduzieren?
Bei neuen Features: Was soll das Script leisten, was es heute nicht kann? Gibt es Randbedingungen (Umgebung, Eingaben, Abhängigkeiten)?
Bei neuen Scripts: Welches Problem wird gelöst? Wer ruft das Script auf und in welchem Kontext?

Wenn der Request eindeutig genug ist, diese Fragen überspringen.

Warte auf Antwort des Users, bevor du mit 0b fortfährst.

0b: Scope einschätzen

Entscheide anhand dieser Heuristiken:

Schnellpfad wenn alle Punkte zutreffen:

Kein neues CLI-Interface (kein neues Flag, kein neuer Subcommand, keine neue Abhängigkeit)
Änderung betrifft nur internen Ablauf (Bugfix, Ausgabe, Logik)
Geschätzter Diff: < 20 Zeilen

Vollpfad wenn mindestens eines zutrifft:

Neues Script
Neues Flag, Subcommand oder externe Abhängigkeit
Strukturelle Änderung (Error-Handling, Trap, Exit-Codes, Logging-Schema)
Geschätzter Diff: ≥ 20 Zeilen

Präsentiere dem User in einem Satz: Pfad + Begründung. Warte auf Bestätigung oder Korrektur.

Schnellpfad

S1: Branch + Implementierung

git checkout -b fix/script-<name>   # oder feat/ je nach Typ

Änderungen direkt implementieren. Bash-Leitplanken einhalten:

Quoting: "$var", Arrays als "${array[@]}"
Keine neuen Magic Numbers ohne benannte Konstante
set -euo pipefail muss gesetzt bleiben

S2: shellcheck (Pflicht)

shellcheck <script>

Alle Befunde beheben. Falls nicht installiert: User informieren (sudo apt install shellcheck) und in bootstrap.sh aufnehmen.

S3: Review-Checkliste

Auch bei kleinen Änderungen prüfen:

Vertauschte oder irreführende Variablennamen
Unmögliche Shell-Operationen (z.B. tar -rf auf .gz)
Gleiche Daten mehrfach abfragen statt Variable wiederverwenden
Ausgaben die Erfolg suggerieren obwohl nichts passiert ist

S4: Test-Empfehlungen

Gib dem User konkrete Kommandos zum Verifizieren der Änderung. Warte auf Rückmeldung.

S5: Abschluss via /ship

Rufe /ship auf (Commit → Push → PR → Merge → Cleanup).

Vollpfad

V1: Planung (Opus)

Aktiviere den Plan-Modus (EnterPlanMode).

Wenn das Script auf spezifische Tools/Libraries aufsetzt (z.B. jq, gh, yq), Dokumentation via Context-7 abrufen — nur wenn inhaltlich nützlich:

mcp__plugin_context7_context7__resolve-library-id
mcp__plugin_context7_context7__query-docs

Plan-Inhalt:

Zweck: Was das Script löst, ein bis zwei Sätze
CLI-Interface: Positionsargumente und Flags (--help, --dry-run Pflicht bei destruktiven Aktionen, --verbose, ggf. --yes)
Abhängigkeiten: Externe CLI-Tools, werden am Script-Start per command -v geprüft
Error-Handling: Cleanup-Strategie (trap), definierte Exit-Codes (0 Erfolg, 1 Fehler, 2 Usage, weitere dokumentiert)
Konsolenausgabe: Eine Zeile pro Hauptschritt ( Schritt ... ok (Details)). Keine Farben außer Gelb (Warnungen) und Rot (Fehler). Keine Querlinien, Tabellen oder Raw-Ausgabe. Ergebnis in die Hauptzeile, nicht als separater Block. "Erfolgreich" nur wenn tatsächlich etwas passiert ist — keine irreführenden Meldungen
Output-Beispiel: Exakte Zeile-für-Zeile-Ausgabe für den typischen Ablauf, so wie der User sie sehen soll
Code-Skelett: Hauptfunktion als Ablauf von Funktionsaufrufen, Hilfsfunktionen als Signatur mit kurzem Einzeiler nur wenn das WARUM nicht offensichtlich ist. Sonnet füllt die Funktionskörper
Dry-Run: Welche Aktionen werden durch Log-Ausgabe ersetzt
User-Einbindung: Rückfragen bei irreversiblen Operationen (read -p), --yes für nicht-interaktive Ausführung
Explizite Verbote: Bekannte Pitfalls, Redundanzen und Stilfehler benennen, die Sonnet vermeiden muss
Randfälle: Für jeden Hauptschritt: "Was kann hier schiefgehen oder sinnlos sein?"
Test-Szenarien: Konkrete Aufrufe für die spätere Verifikation

Speichere den Plan unter <repo-root>/plans/script-<name>.md (Verzeichnis bei Bedarf anlegen).

Präsentiere den Plan dem User. Warte auf Bestätigung bevor V2 startet.

V2: Implementierung (Sonnet)

Wechsle das Modell: /model claude-sonnet-4-6.

Feature-Branch anlegen:

git checkout -b feat/script-<name>

Bash-spezifische Leitplanken:

Shebang #!/usr/bin/env bash, direkt danach set -euo pipefail und IFS=$'\n\t'
Quoting konsequent: "$var", Arrays als "${array[@]}"
main()-Funktion am Dateiende, aufgerufen mit main "$@"
Script ausführbar machen: chmod +x <pfad>
Keine Kommentare — Code muss selbsterklärend sein. Nur kommentieren wenn das WARUM nicht aus dem Code hervorgeht

V3: shellcheck (Pflicht)

shellcheck <script>