2D0/claude-skills

blackbox

Übersicht

Eine Blackbox ist der Flugschreiber eines Elements: eine nicht zusammengefasste Entscheidungsaufzeichnung pro vom Eigentümer genehmigter Änderungseinheit – was der Eigentümer tatsächlich gesagt hat (wortwörtlich), was es im Kontext bedeutete, was der Assistent empfohlen und gebaut hat, warum, die Beweise, die jede Wahl untermauerten, und was der Assistent dabei falsch gemacht hat – verankert an dem Inhalt, den es erklärt, und nur bei Bedarf lesbar. Sie existiert, damit eine zukünftige Sitzung den Ursprung einer Regel prüfen kann, anstatt sie erneut zu verhandeln.

Zwei Dinge, die sie nicht ist:

• Kein Transkript. Auswählen ist nicht Zusammenfassen. Der Eintrag wird aus dem Entscheidungspfad erstellt, nicht aus dem Chat-Protokoll: Erklärungen, Analogien und Umwege, die dem Eigentümer halfen zu verstehen, aber keine Entscheidung veränderten, werden weggelassen. Was behalten wird, bleibt vollständig.
• Kein Tagebuch über den Eigentümer. Es zeichnet auf, was gesagt und entschieden wurde, nicht wer der Eigentümer ist. Beobachtungen zum Arbeitsstil gehören in das Gedächtnis des Assistenten, niemals hierher.

Hat dieses Element eine Blackbox?

• blackbox/README.md liegt neben dem Element (oder im Repository-Stammverzeichnis) → die Konvention gilt. Lesen Sie diese README UND den neuesten Eintrag, bevor Sie Ihren schreiben – das Schema stammt von ihnen, niemals aus Ihrem Kopf.
• Kein Marker und der Eigentümer bittet um Einführung → bootstrappen: Kopieren Sie blackbox/README.md aus dem Verzeichnis dieses Skills in das Element, ändern Sie nichts außer dem Elementnamen, und zeichnen Sie die Einführung selbst als ersten Eintrag auf.
• Kein Marker und Sie sind dabei, ein Spezifikations-/Konventions-/Entwurfsdokument zum ersten Mal in dieser Sitzung zu bearbeiten → prüfen Sie auf den Marker. Wenn er fehlt, bieten Sie die Einführung einmal an, in einem Satz, und setzen Sie dann die Aufgabe des Eigentümers fort. Die Einführung ist die Entscheidung des Eigentümers; wenn er ablehnt, notieren Sie es im Gedächtnis, damit das Repository nicht erneut gefragt wird.

Die Einführungseinheit ist das Verzeichnis, das den Marker enthält – ein Skill, ein Paket oder ein ganzes Repository. Beliebiges Repository, beliebige Merge-Methode.

Einheit und Zeitplan

• Ein Eintrag pro vom Eigentümer genehmigter Einheit: eine bestätigte Spezifikation, ein gemergter PR, eine überarbeitete Konvention. Nicht pro Commit, nicht pro Gesprächsrunde. Eine Einheit, die mehrere Commits erzeugte, erhält einen Eintrag.
• Geschrieben in der Sitzung, in der die Entscheidungen getroffen wurden. Der rohe Austausch lebt nur im aktuellen Kontext; sobald die Sitzung endet, überleben nur Zusammenfassungen und wörtliche Zitate sind verschwunden. Wenn eine Einheit lange dauert oder sich über Sitzungen erstreckt, speichern Sie früh einen Entwurf – Refs: ausstehend, Zitate des Eigentümers und der Index ausgefüllt – und finalisieren Sie (Blobs anheften, Textkörper vervollständigen) bei Genehmigung. Ein Entwurf ist besser als eine rekonstruierte Erinnerung.

Das Rezept (pro vom Eigentümer genehmigter Einheit)

1. Nehmen Sie die Änderung vor.
2. Heften Sie die Ergebnisse inhaltlich an. Führen Sie für jede geänderte Datei git hash-object <Pfad> im Arbeitsbaum aus. Blob-SHAs sind inhaltsadressiert – dieselben Bytes ergeben für immer denselben Hash, sodass die Verankerung Squash, Rebase und jede Umschreibung der Historie überlebt, und sie existiert, bevor ein Commit getätigt wird.
3. Schreiben Sie den Eintrag blackbox/YYYY-MM-DD-<Slug>.md in der folgenden Form: einen Index, der auf den Textkörper verweist, dann den rohen Textkörper.
4. Landen Sie den Eintrag mit der Änderung – derselbe Commit oder derselbe PR, gemergt, wie das Repository normalerweise merged.

Überprüfen einer Verankerung: git hash-object <Pfad> und vergleichen. Abrufen eines verankerten Zustands: git log --find-object=<SHA> oder die GitHub-Blobs-API.

Lese-Regel: Laden Sie niemals blackbox/ während der normalen Arbeit an dem Element. Lesen Sie es nur bei Fragen zur Herkunft.

Form des Eintrags

# YYYY-MM-DD – <Titel>

Refs:           <Pfad> @ blob <SHA>            (eine Zeile pro geänderter Datei)
Entscheidungen: <Entscheidung> <Gewicht> [→ <neues Gewicht>, siehe §…] · …
Umkehrungen:    §… · §…   (oder: keine)
Eigentümer erkannte:   §… · …    (oder: keine)
Abgelehnt:       §… · …    (oder: keine)
Beweise:       <Befehl / Nummer / Link> · …
Verständnis:    §…        (oder: n. v.)
---
<roher Textkörper, mit §-Überschriften, auf die der Index verweist>

Indexzeilen verweisen auf den Textkörper; sie ersetzen ihn nie.

• Entscheidungen – jede Entscheidung, die die Einheit enthält, mit dem Gewicht, das der Assistent bei der Frage zuwies (🔴 muss jetzt entschieden werden · 🟡 entscheiden, überprüfbar · 🟢 Empfehlung annehmen). Wenn ein Gewicht später geändert wurde, sagen Sie es und verweisen Sie auf den Grund. Im Laufe der Zeit ist diese Zeile, wie der Eigentümer seine eigene Überlegung gegen das Gewicht, das die Entscheidung verdient, prüft.
• Umkehrungen – alles, was der Assistent behauptete und später zurückzog oder korrigierte: eine falsche Behauptung, eine durch Messung widerlegte Empfehlung, eine Entscheidung, die er ohne Nachfrage traf. keine ist ein gültiger Wert und muss explizit geschrieben werden.
• Eigentümer erkannte – Inkonsistenzen oder Fehler, die der Eigentümer entdeckte (eine falsche Zählung, ein fehlendes Element, ein struktureller Fehler). Die Prüfung des Eigentümers, nicht nur die des Assistenten.
• Abgelehnt – Optionen, Standardeinstellungen des Tools oder externe Empfehlungen, die bewusst nicht angenommen wurden, mit dem Grund im Textkörper.
• Beweise – was tatsächlich angesehen wurde, als die Entscheidung getroffen wurde: der ausgeführte Befehl, die Zahlen, die er produzierte, die angezeigte Seite oder Datei. Zeichnen Sie die Reproduktion auf, nicht das Bild – ein Diagramm wird aus seinem Befehl neu generiert; ein Screenshot nicht.
• Verständnis – wenn der Eigentümer zustimmte, während er sagte, er verstehe nicht vollständig, seine Aussage und was später erneut erklärt werden muss.

Sprache

• Textkörper: Englisch, unabhängig von der Dokumentsprache des Repositorys.
• Eingabe des Eigentümers: das Original wörtlich, dann eine englische Umschreibung. Zuerst wörtlich, in einem > Zitat, genau wie getippt – Tippfehler, Abkürzungen, ㅇ und alles. Dann die Umschreibung: inhaltlich vollständig, natürlich in der Form, in sich geschlossen (ein Leser ohne weiteren Kontext versteht sie). Das Wörtliche ist der Beweis – ein Tippfehler, der eine Entscheidung änderte, kann nur dort gefunden werden. Die Umschreibung ist die Lesart des Assistenten zu diesem Zeitpunkt – wenn beide nicht übereinstimmen, hat der Eintrag bereits den Fehler dokumentiert.
• Antworten des Assistenten, Begründungen und interne Verarbeitung: Englisch, in voller Form für alles, was eine Entscheidung betrifft. > ㅇ gefolgt von Eigentümer genehmigte Option (a). ist eine vollständige Aufzeichnung; füllen Sie sie nicht auf.

Harte Formen

Regel	Nicht so
Eingabe des Eigentümers = wörtliches Zitat und englische Umschreibung	Nur wörtlich (ohne Kontext unlesbar), nur Umschreibung (Beweis verloren) oder ein einzeilige Zusammenfassung
Index oben, roher Textkörper unten, Indexzeilen verweisen auf §-Überschriften	Ein Index, der zusammenfasst statt verweist; ein Textkörper ohne Index; Abschnitte mit Einzeilern gefüllt
Textkörper aus dem Entscheidungspfad	Erklärungen, Analogien oder Umwege, die keine Entscheidung änderten
Umkehrungen: vorhanden, auch als keine	Ein Eintrag, der nur auflistet, was richtig lief
Refs: = Blob-SHAs pro Datei (git hash-object)	Ein Commit- oder PR-Nummer als Anker – Geschichtsüberschreibungen töten diese
Eintrag landet im selben Commit oder PR wie die Änderung	Ein Folge-PR „später“
Geschrieben in der Sitzung, in der die Entscheidungen getroffen wurden	In der nächsten Sitzung aus dem Gedächtnis rekonstruiert
Eintragsschema aus der README und dem neuesten Eintrag	Ein erfundener Format

Warnsignale

• Ein Eintrag ohne Refs:-Zeile oder mit einem Refs:, das einen Commit oder PR anstelle von Blobs benennt
• Eine Eingabe des Eigentümers ohne > wörtliches Zitat oder ein Zitat ohne Umschreibung dahinter
• Keine Umkehrungen:-Zeile
• Indexzeilen, die wie Zusammenfassungen statt wie Verweise wirken
• Ein Textkörper, der dem Leser Konzepte erklärt, anstatt aufzuzeichnen, was entschieden wurde
• Eine Änderung, die ohne ihren Eintrag gemergt wurde
• Ein Eintrag, der in der Sitzung nach den Entscheidungen geschrieben wurde, die er aufzeichnet (im Eintrag angeben, wenn unvermeidbar)

Herkunft

blackbox/ enthält die vollständige Entscheidungsaufzeichnung für dieses Element – Eingaben des Eigentümers (wörtlich + englische Umschreibungen), Begründungen des Assistenten, Beweise und Umkehrungen, inhaltsverankert pro genehmigter Änderung. Lesen Sie es nur, wenn Sie untersuchen, warum eine Regel existiert oder was der Eigentümer ursprünglich verlangte. Laden Sie es niemals während der normalen Nutzung.