Kicktemp Astro Starter

Erscheinungsbild

0017 — Wenige Skills mit Abschlusskriterien statt einer großen Anweisungsdatei ​

Status: angenommen · Milestone: M9

Kontext ​

Dieses Repository wird in jedem Kundenprojekt vervielfältigt, und in jedem davon arbeitet Claude Code daran weiter. Die naheliegende Form dafür ist eine große CLAUDE.md, in der alles steht: Regeln, Abläufe, Befehle, Beispiele.

Diese Form hat drei Eigenschaften, die sich mit der Zeit verschärfen. Sie liegt bei jedem Aufruf vollständig im Kontext, auch bei einer Tippfehlerkorrektur. Sie widerspricht sich, sobald sie über einige hundert Zeilen wächst — und der Widerspruch fällt niemandem auf, weil niemand sie am Stück liest. Und sie sagt nirgends, wann eine Arbeit fertig ist: Eine Anleitung endet, wenn die Schritte abgearbeitet sind, nicht wenn das Ergebnis stimmt.

Dazu kommt eine Beobachtung aus den vorangegangenen Milestones: Die Fehler, die hier wirklich teuer waren, waren keine Wissenslücken. Es war ein Formularfeld ohne pnpm forms:contract, ein Alt-Text ohne menschliche Bestätigung, eine Consent-Kategorie ohne Verbraucher. Alles Dinge, bei denen der letzte Schritt fehlte — nicht der erste.

Entscheidung ​

Das Wissen wird auf drei Orte verteilt, jeder mit einer eigenen Aufgabe:

CLAUDE.md — was gilt. Ausschließlich stabile, projektweite Regeln, nummeriert, mit Verweis auf das ADR, das sie begründet. Keine Abläufe, keine Befehlssammlung, nichts, was sich aus dem Code selbst ergibt. Ein Zeilenbudget hält die Datei bei dieser Aufgabe; tests/unit/claude-system.test.ts bricht ab, wenn sie darüber hinauswächst.

.claude/skills/ — wie etwas gemacht wird. Zehn abgegrenzte Arbeitsabläufe, je eine SKILL.md mit immer denselben sieben Abschnitten:

Zweck · Eingaben · Ablauf · Erlaubte Änderungen · Validierung ·
Abschlusskriterien · Wann nicht verwenden

Die letzten drei tragen die Entscheidung. Validierung nennt den Befehl, der den Zustand belegt. Abschlusskriterien enden immer auf pnpm verify — die Kette ist der Maßstab, nicht die Einschätzung. Wann nicht verwenden ist der Abschnitt, den eine Anweisungsdatei nie hat: Er hält einen Skill davon ab, zur Universalantwort zu werden.

Ein Skill verweist auf eine Regel, statt sie zu wiederholen. Eine umformulierte Regel ist auf Dauer eine widersprochene Regel.

.claude/agents/ — womit geprüft wird. Vier Review-Agents entlang der vier Bereiche, in denen dieses Repository etwas zusagt: Designsystem, SEO und Tracking, Barrierefreiheit und Performance, Formulare und Handler-Sicherheit. Sie bekommen ausschließlich lesende Werkzeuge.

Dazu project/ als Arbeitsgrundlage: sieben Briefing-Vorlagen mit Leitfragen, aus denen die Skills ihre Eingaben ziehen.

Begründung ​

Warum sieben feste Abschnitte. Eine feste Form lässt sich prüfen. Der Test verlangt alle sieben in derselben Reihenfolge — dadurch kann ein Skill nicht unbemerkt ohne „wann nicht verwenden" entstehen, und genau der Abschnitt ist der, den man beim Schreiben weglässt.

Warum pnpm verify als Abschlusskriterium überall. Es ist die einzige Aussage über Fertigkeit, die niemand einschätzen muss. Ein Skill, der mit „danach ist das Formular fertig" endet, ist eine Selbstauskunft; einer, der mit der Kette endet, ist eine Zusage.

Warum lesende Agents. Ein Reviewer, der nebenbei repariert, verliert den Blick auf das, was er noch nicht geprüft hat — und ein bereits behobener Befund lässt sich nicht mehr abwägen. Der Werkzeugschnitt macht daraus eine Zusage statt einer Bitte; der Test prüft ihn.

Warum vier Agents und nicht mehr. Ein Agent lohnt sich, wenn er einen echten Kontext- oder Toolvorteil hat. Diese vier bringen je einen eigenen Prüfblick mit, der sich aus dem Diff allein nicht ergibt — etwa die Prüfreihenfolge im Handler oder die Frage, ob zu einem JSON-LD-Knoten sichtbarer Inhalt gehört.

Warum der Test keine Inhalte prüft. Er prüft Struktur: Namen, Abschnitte, Werkzeuge, Zeilenbudgets. Ein Test, der Formulierungen festschreibt, macht jede Verbesserung am Text zu einer Teständerung — und wird dann umgangen statt gepflegt.

Verworfene Alternativen ​

Ein repository-architect-Agent. Im ursprünglichen Entwurf vorgesehen. Er hätte genau das gewusst, was CLAUDE.md und die ADRs bereits sagen — eine Rollenbezeichnung ohne Kontextvorteil. Verworfen zugunsten der Regel, dass ein Agent etwas mitbringen muss, das im Repository noch nicht steht.

Ein Skill je Komponente oder Seitentyp. Wäre schnell auf zwanzig gewachsen, hätte sich überschnitten und die Frage „welcher denn jetzt" bei jedem Aufruf neu gestellt. Zehn Skills entlang der Arbeitsabläufe sind unterscheidbar; zwanzig entlang der Artefakte nicht.

Beispielinhalte in den Briefing-Vorlagen. Sie lesen sich besser und stehen nach dem dritten Kundenprojekt als Antwort da, die niemand gegeben hat. Die Vorlagen enthalten deshalb Leitfragen und leere Tabellen — eine leere Zeile ist ehrlicher als eine plausible.

Skills auch für Prüfungen. Prüfen und Bauen im selben Ablauf führt dazu, dass der Befund sofort behoben wird und niemand mehr weiß, wie viele es waren. Deshalb prüfen die Agents und release-audit, und beide ändern nichts.

Konsequenzen ​

  • Ein neuer Skill ist erst fertig, wenn er alle sieben Abschnitte hat, in der Liste in tests/unit/claude-system.test.ts steht und unter dem Zeilenbudget bleibt.
  • Wer eine Regel ändert, ändert sie in CLAUDE.md — nicht in den Skills. Die verweisen nur.
  • Ein neuer Agent braucht eine Begründung, welchen Kontext- oder Toolvorteil er hat.
  • project/brief.md gibt es zweimal: als Vorlage im Repository und als das, was pnpm starter:init schreibt. Der Test hält beide Überschriftenlisten deckungsgleich — sonst beschriebe der Starter eine andere Datei als die, die im Kundenprojekt entsteht.
  • Bestätigte Projekt-Learnings gehören in die Dokumentation oder ein ADR, nicht in eine parallele Memory-Sammlung. Was aus Code, ADR oder docs/ hervorgeht, wird nicht ein zweites Mal abgelegt.