kkh2114/claude-skills-public

Coding Harness Designer v1

"Ein Agent scheitert nicht an mangelnden Fähigkeiten, sondern an mangelnder Umgebung." — OpenAI "Lass den Erzeuger nicht seine eigene Arbeit bewerten." — Anthropic "Wenn ein Agent einen Fehler macht, gestalte das System so, dass dieser Fehler nie wieder passieren kann." — Mitchell Hashimoto

Beziehung zwischen diesem Skill und dem harness-designer

┌─────────────────────────────────────────────────────────────┐
│  Gemeinsame Basis: Die 5 Säulen des Harness-Designs         │
│  Progressive Disclosure / Mechanical Enforcement /           │
│  Feedback Loop / Session Continuity / Entropy Management     │
├──────────────────────────┬──────────────────────────────────┤
│  harness-designer (bestehend) | coding-harness-designer (dieser)	│
│  Analyse- & Entscheidungs-WS │  Coding- & Entwicklungs-WS  │
│  Agent = Standpunkt/Rolle    │  Agent = Coding-Arbeiter    │
│  Output = Berichte/Entscheide │  Output = Quellcode/Tests  │
│  Validierung = Checkliste/Diskussion │  Validierung = CI/Linter/Browser-Tests │
│  "Besprechungsraum-Design"    │  "Fabrikstraßen-Design"   │
└──────────────────────────┴──────────────────────────────────┘

---

Die 7 Säulen des Coding Harness

Zu den bestehenden 5 Säulen werden 2 codingspezifische hinzugefügt:

Säule	Kernfrage	Prinzip
Progressive Disclosure	Kann der Agent nur das Nötigste sehen?	AGENTS.md ~100 Zeilen Inhaltsverzeichnis → docs/
Mechanical Enforcement	Wird die Architektur maschinell durchgesetzt?	Linter · Strukturtests · CI
Feedback Loop	Korrigiert sich der Agent bei Fehlern selbst?	Fehlermeldung lehrt die Korrektur
Session Continuity	Ist der Handoff zwischen Sitzungen sauber?	progress + feature-status + git
Entropy Management	Bleibt die Codequalität über Zeit erhalten?	Automatischer Scan · Refactoring · Qualitätsstufen
Architectural Rigidity ← Neu	Werden Modulgrenzen erzwungen?	Schichtenregeln · Abhängigkeitsrichtungsprüfung
Observable Runtime ← Neu	Kann der Agent Ausführungsergebnisse sehen?	Zugriff auf Logs · Metriken · DOM · Screenshots

---

Beziehung der zwei Schichten

┌─────────────────────────────────────────────────────────────┐
│  LAYER 1: Meta (Rolle dieses Skills)                        │
│                                                             │
│  Planner ──→ Generator ──→ Evaluator                        │
│     ↑         (eindirektional sequentiell, keine Rückverweise)│
│     └──── Feedback bei Unzulänglichkeit ──────────────────┘ │
│                                                             │
│  Zweck: Entwerfen, Erstellen und Validieren der Codestruktur│
└─────────────────────────┬───────────────────────────────────┘
                          │ Nach Genehmigung: Harness fertiggestellt
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  LAYER 2: Betrieb (Rolle der fertigen Coding-Harness)       │
│                                                             │
│  ┌ Initializer (erster Lauf) ─→ Scaffold + Umgebungseinrichtung│
│  │                                                          │
│  └ Coding Agent (wiederholter Lauf):                        │
│    1. progress lesen → nächste Aufgabe wählen               │
│    2. Implementieren (Code generieren)                      │
│    3. Selbstvalidierung (Tests · Linter · Browser)          │
│    4. Review anfordern (Code-Review zwischen Agenten)       │
│    5. Feedback einarbeiten → Wiederholen                    │
│    6. Im sauberen Zustand committen                         │
│                                                             │
│  Zweck: Tatsächliches Codieren, Testen, Refactoring, Deploy │
└─────────────────────────────────────────────────────────────┘

---

LAYER 1: Meta — Prozess zum Entwurf der Coding-Harness

L1 Drei Agententypen (eindirektional sequentiell, keine Rückverweise)

Planner (Planer)

Analysiert Benutzeranforderungen und entwirft die Struktur der Coding-Harness.

• Input: Projektanforderungen (durch Fragen gesammelt)
• Output: Architekturentwurf + Ordnerstruktur + Erzwingungsregeln + Bewertungskriterien

Generator (Erbauer)

Erzeugt aus dem Plan des Planner die tatsächlichen Dateien und Einstellungen.

• Input: Vom Planner genehmigter Entwurf
• Output: AGENTS.md, docs/, Linter-Regeln, CI-Konfiguration, Teststruktur

Evaluator (Prüfer)

Validiert die Generator-Ergebnisse unabhängig basierend auf den 7 Säulen.

• Input: Generator-Dateien + Planner-Bewertungskriterien
• Output: Punktzahl pro Säule + funktionale Validierung + Verbesserungsfeedback

---

L1 Phase 0: Pattern Match — Referenz auf harness-100 (Neu v1.1)

"99% eines guten Entwurfs hat schon jemand gemacht. Finde es und passe es an."

Vor Eintritt in die Discovery: Suche aus den validierten Exemplaren von harness-100 (https://github.com/revfactory/harness-100, Apache-2.0) das ähnlichste heraus und verwende es als Referenz. Nicht-Entwickler werden an den Skill harness-starter-coding verwiesen.

Ziel-Exemplare (27 Coding-Domänen)

• Dev&DevOps #16–30: fullstack-webapp, mobile-app-builder, api-designer, database-architect, devops-pipeline, security-audit, performance-tuning, refactoring-squad, test-automation, monitoring-setup usw.
• Data&AI/ML #31–42: ml-experiment, data-pipeline, rag-llm-app, nlp-processor, recommendation-engine, design-system usw.

Phase-0-Ablauf

1. Extrahiere Schlüsselwörter zum App-Typ aus der 1–2-Satz-Anfrage des Benutzers
2. Präsentiere die Top-3-Kandidaten aus den obigen 27 + bitte um Benutzerbestätigung
3. Trage die ausgewählte Exemplar-Nummer im Feld reference_exemplar von _workspace/00_input.md ein
4. Matching-Ähnlichkeit < 0.5 → Fallback in den Freien Entwurfsmodus (Fortsetzung mit bestehender Phase 1)

Phase-0-Ergebnis in nachfolgende Schritte einfließen lassen

• Planner: Die 5-Agenten-Konfiguration des Exemplars als Basis nehmen, aber je nach Scale Mode (Full/Reduced/Single) anpassen
• Generator: Das Grundgerüst des Exemplars zuerst verwenden, die Nummernkonvention _workspace/NN_*.md erzwingen
• Evaluator: Die 8 Qualitätsstandards des Exemplars (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) als Rubrik verwenden

Pattern Fidelity (qualitative Bewertung, nur Phase 0)

Nicht in die automatische Bewertung der 7 Säulen einbezogen. Phase 0 bewertet qualitativ beim Exemplar-Matching.

Die 8 Quality Standards des in Phase 0 ausgewählten harness-100-Exemplars (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) werden getrennt von der Evaluator-Bewertung geprüft.

• Anwendungszeitpunkt: Einmal in Phase 0 (Exemplar-Auswahl), einmal nach Evaluator PASS bei der Berichterstattung
• Keine Punktevergabe: Nicht in den 23 Items der 7 Säulen enthalten
• pillar-weight: Nur Anpassung der Gewichtung der 7 Säulen möglich. Pattern Fidelity ist kein Gewichtungsgegenstand

Trigger Boundaries (soll + NICHT)

Planner/Generator MÜSSEN im erzeugten orchestrator skill.md einen Abschnitt soll-NICHT trigger einfügen. Beispiel: "NICHT verwenden für mobile Apps, Enterprise-Mikroservices, statische Webseiten".

Coding Agent Behavior Principles (Karpathy-inspiriert, zwingend zu injizieren)

Der Generator MUSS am Ende der erstellten .claude/CLAUDE.md den folgenden Abschnitt einfügen. Diese 4 Prinzipien sind mit dem Skill karpathy-guidelines (unabhängig installiert) synchronisiert und dienen als grundlegende Verhaltensrichtlinie für alle Coding-Agenten innerhalb der Harness.

## Coding Agent Behavior Principles (Karpathy-inspiriert)

Alle Coding-Agenten befolgen bei ihrer Arbeit die folgenden 4 Prinzipien.
Details siehe Skill `karpathy-guidelines` (automatischer Trigger).

1. Think Before Coding — Annahmen explizit machen, bei Unklarheit nachfragen, Alternativen vorschlagen
2. Simplicity First — Nur das Geforderte tun. Keine spekulativen Abstraktionen oder Funktionen
3. Surgical Changes — Nur die angeforderten Zeilen ändern. Keine Verbesserung des umgebenden Codes
4. Goal-Driven Execution — Überprüfbare Erfolgskriterien → Schleife → Bestätigung

Füge zur Evaluator-Checkliste den Punkt "Existenz des Karpathy-4-Prinzipien-Abschnitts in CLAUDE.md" hinzu.

Scale Modes (Betriebsschicht-Standardwerte)

Modus	Agentenkonfiguration
Full	architect + frontend + backend + qa + devops
Backend	architect + backend + qa
Frontend	architect + frontend + qa
Refactoring	architect + beteiligte Entwickler + qa
DevOps	devops solo

---

L1 Phase 1: Discovery — Planner-Ablauf

Die Discovery besteht aus 4 Stufen von Fragen. Jede Stufe wird der Reihe nach durchlaufen, wobei Folgeabfragen basierend auf Benutzerantworten verzweigen. Nach Erhalt der Antwort einer Stufe wird zur nächsten Stufe übergegangen. Nicht alles auf einmal fragen.

1-1. Stufe 1 — Zweck und Kontext (WARUM / WER)

Nicht die Technik, sondern den Grund für die Existenz dieses Projekts erfassen.

P1. Welches Problem soll dieses Projekt lösen?
    (Welches Unbehagen / welche Ineffizienz soll beseitigt werden?)

P2. Wer nutzt es?
    (Interne Mitarbeiter / Kunden / Entwickler / breite Öffentlichkeit)
    → Folge: Anzahl der Nutzer? IT-Kenntnisse?

P3. Was sind die Erfolgskriterien dieses Projekts?
    (Wann gilt es als "gut gemacht"?)

P4. Gibt es ähnliche bestehende Systeme?
    (Ersetzt es eines? / Wird es neu erstellt?)
    → Folge [Ersatz]: Was ist das größte Problem des bestehenden Systems?
    → Folge [Neu]: Gibt es einen Benchmark-Dienst?

Folgeabfrage-Verzweigungen:

• Bei P2 "interne Mitarbeiter" → "Wie viele? Gibt es eine Abteilungsstruktur? Wird ein Berechtigungssystem benötigt?"
• Bei P2 "Kunden" → "Registrierungsmethode? Gibt es Bezahlung? Datenschutzverarbeitung?"
• Bei P3 Nennung konkreter Zahlen → "Wie wird diese Zahl gemessen?"
• Bei P3 vage Antwort → "Welcher Bildschirm / welche Funktion muss konkret funktionieren, damit es ein Erfolg ist?"

1-2. Stufe 2 — Funktionen und Inhalt (WAS)

Was beinhaltet es, was sind die Kernfunktionen.

F1. Nennen Sie die Top-3-Kernfunktionen nach Priorität geordnet?
    (Beginnend mit dem, was zuerst funktionieren muss)

F2. Welche Art von Daten?
    (Relational / Dokumentenbasiert / Zeitreihen / Dateien / Gemischt)
    → Folge: Sind die Beziehungen zwischen den Daten komplex? Sind Aggregationen/Statistiken wichtig?

F3. Gibt es Authentifizierungs-/Autorisierungsanforderungen?
    (Keine / Einfacher Login / Rollenbasiert / Organisatorische Hierarchie-Berechtigungen)
    → Folge [Rollenbasiert oder höher]: Wie viele Berechtigungsstufen? Ist Datenisolierung erforderlich?

F4. Gibt es Integrationen mit externen Systemen?
    (Keine / API-Integration / Datei-Import/Export / Zahlung / Benachrichtigungen)

F5. Ist Offline- oder Mobile-Unterstützung erforderlich?

Folgeabfrage-Verzweigungen:

• Bei F1 mehr als 3 Funktionen → "Bewerten Sie die Komplexität jeder Funktion als hoch/mittel/niedrig?"
• Bei F2 "Gemischt" → "Welche Arten sind gemischt? Müssen die Speicher getrennt werden?"
• Bei F3 "Organisatorische Hierarchie" → "Werden Abteilungen häufig hinzugefügt/geändert? Muss dies ohne Codeänderungen erweiterbar sein?"

1-3. Stufe 3 — Technologie und Struktur (WIE)

Wie wird es gemacht. Unter Berücksichtigung der Antworten aus Stufe 1–2 werden geeignete Technologien vorgeschlagen.

T1. Gibt es eine Präferenz für den Technologie-Stack?
    (Falls ja, angeben / Falls nein, "Empfehle mir")
    → Empfehlung von "Boring Technology": Agenten arbeiten besser mit stabilen, datenreichen Technologien (OpenAI-Original)
    → Basierend auf Antworten aus Stufe 1–2 wird ein geeigneter Stack vorgeschlagen

T2. Deployment-Umgebung?
    (Vercel / AWS / Unternehmensserver / Unbekannt)

T3. Tool für Coding-Agenten?
    (Claude Code / Codex / Cursor / Sonstige)
    → Harness-Konfiguration variiert je nach Tool

T4. Grad der Autonomie des Agenten?
    (Mensch reviewed und merged / Agenten-Review und Auto-Merge / Vollständig autonom)

T5. Projektumfang und -dauer?
    (Prototyp 1–2 Wochen / Mittelgroß 1–3 Monate / Groß, langfristig)

T6. Gibt es eine bestehende Codebasis?
    (Neu / Harness auf bestehenden Code anwenden)
    → Bei bestehendem Code wird eine schrittweise Einführungsstrategie entworfen

Folgeabfrage-Verzweigungen:

• Bei T1 "Empfehle mir" → Basierend auf Antworten aus Stufe 1–2 eine Vergleichstabelle mit 2–3 Optionen präsentieren und auswählen lassen
• Bei T2 "Unbekannt" → Empfehlung basierend auf Benutzeranzahl und Funktionen
• Bei T5 "Groß" → "Teamgröße? Anzahl gleichzeitig arbeitender Agenten?"

1-3.5. Stufe 3.5 — Flussänderungsverlauf (FLOW HISTORY) [Optional]

Empfohlen für Langzeitprojekte oder wenn sich die Coding-Harness über mehrere Sitzungen hinweg weiterentwickeln könnte. Kann bei 1–2-Wochen-Prototypen übersprungen werden.

F1. "Soll ein Verlauf von zukünftigen Änderungen an Prompts, Protokollen, Templates, API-Skripten, Commands, CLAUDE.md geführt werden?"

    Verwendungszweck:
    - Retrospektive des Projektverbesserungsverlaufs (Warum wurde was geändert?)
    - Grundlage für Rollback auf frühere Versionen, falls nötig
    - Referenz für zukünftiges Design ähnlicher Coding-Harnesses

    ※ Nicht zum Lesen in jeder neuen Sitzung gedacht.
      Nur zur Referenz beim Ändern, Zurücksetzen oder Portieren von Flows.

    → "Nein" → 05-flow-history/ nicht enthalten. Weiter mit Stufe 4.
    → "Ja" → Weiter zu F2.

F2. "Soll der erste Build (v1) automatisch als Change 0001 aufgezeichnet werden?"
    - Standardwert: Ja (Planner-Discovery-Antworten bleiben als Design-Begründung erhalten)
    - Nein → Nur CHANGELOG erstellen und erste Änderung manuell aufzeichnen

Grundsätze der Flussverlaufsverwaltung (nach Erstellung im Betrieb): Dieser Verlauf zeichnet nur Änderungen am Workflow-System (Prompts · Protokolle · Templates · API-Skripte · Commands · CLAUDE.md) auf. Vom System erstellte Artefakte(Code · Berichte · Analyseergebnisse) sind nicht aufzuzeichnen. Abgrenzungskriterium: "Wäre das Ergebnis des nächsten Laufs anders, wenn diese Änderung nicht stattgefunden hätte?" → Anders = Systemänderung = Aufzeichnung / Nicht anders = Artefakt = Aufzeichnung nicht nötig Details: 00-system/protocols/flow-change-protocol.md

Hinzufügen zur Planner-Ausgabe (bezüglich flow-history):

• flow_history_enabled: true/false
• flow_history_initial_record: true/false (F2-Antwort)

1-4. Stufe 4 — Qualität und Bewertungskriterien (QUALITÄT / EVALUIERUNG)

Die Werte, die dem Benutzer wichtig sind, erfassen und Bewertungskriterien vereinbaren.

E1. Welche Qualitätsattribute sind bei diesem Projekt am wichtigsten? (Top 3 auswählen)
    □ Sicherheit (Berechtigungen, Datenisolierung, Authentifizierung)
    □ Leistung (Antwortzeit, gleichzeitige Zugriffe)
    □ Skalierbarkeit (Skalierung ohne Codeänderungen)
    □ Wartbarkeit (Einfach zu modifizieren durch andere Personen/Agenten)
    □ Benutzererfahrung (Intuitive UI, schnelle Reaktion)
    □ Testbarkeit (Qualitätssicherung durch automatische Tests)
    □ Schnelle Markteinführung (MVP zuerst, Perfektion später)
    □ Datenkonsistenz (Genaue Aufzeichnung, keine Datenverluste)

E2. Gibt es zukünftige Erweiterungspläne?
    (Keine / Funktionserweiterung / Kombination mit anderen Systemen / Nutzerzahl skalieren)
    → Folge: Welche konkreten Erweiterungen? Zeitrahmen?

E3. Was darf bei diesem Projekt auf keinen Fall kompromittiert werden?
    (Beispiel: "Die Berechtigungsisolierung darf nicht gebrochen werden", "Daten dürfen nicht verloren gehen")

E4. Was kann dagegen anfangs fehlen?
    (Beispiel: "Mobile Unterstützung später", "Statistik-Dashboard in Phase 2")

Folgeabfrage-Verzweigungen:

• Bei E1 Auswahl von "Sicherheit" → "Welche Art von Sicherheit? Authentifizierung/Berechtigungen/Datenverschlüsselung/Prüfprotokolle?"
• Bei E2 "Kombination mit anderen Systemen" → "Welche Systeme? Sind die Datenformate kompatibel?"
• E3-Antwort → Wird als Kerneingabe für die Evaluator-Gewichtung verwendet

1-5. Einigung über Bewertungsgewichtung (nach Abschluss von Stufe 4)

Die Antworten aus Stufe 1–4 analysieren und eine Gewichtung für die 7 Säulen vorschlagen. Mit dem Benutzer abstimmen und endgültig festlegen.

[Gewichtungsvorschlagsprozess]

SCHRITT 1. Schlüsselwörter aus Stufe-1–4-Antworten extrahieren
  - "Berechtigungsisolierung" → Mechanical Enforcement, Architectural Rigidity ↑
  - "Skalierung ohne Codeänderungen" → Architectural Rigidity ↑
  - "Schnelle Markteinführung" → Entropy Management ↓, Observable Runtime ↑
  - "Datenkonsistenz" → Feedback Loop ↑, Mechanical Enforcement ↑

SCHRITT 2. Vorschlag durch Anpassung der Standardgewichtung

  Standardgewichtung (vor Berücksichtigung der Projekteigenschaften):
  | Säule | Standard | Anpassungsgrund | Vorschlag |
  |------|------|----------|------|
  | Progressive Disclosure | 15% | (Änderungsgrund) | ?% |
  | Mechanical Enforcement | 20% | (Änderungsgrund) | ?% |
  | Feedback Loop | 15% | (Änderungsgrund) | ?% |
  | Session Continuity | 10% | (Änderungsgrund) | ?% |
  | Entropy Management | 10% | (Änderungsgrund) | ?% |
  | Architectural Rigidity | 20% | (Änderungsgrund) | ?% |
  | Observable Runtime | 10% | (Änderungsgrund) | ?% |

  "Unter Berücksichtigung von [Begründung] habe ich die
   Gewichtung von [Säule] von [Standard]% auf [Vorschlag]% angepasst.
   Haben Sie Anmerkungen oder Änderungswünsche?"

SCHRITT 3. Benutzerfeedback einarbeiten
  - Zustimmung → Festlegung
  - "Erhöhe die Sicherheit" → Gewichtung relevanter Säulen erhöhen, andere senken, erneut vorschlagen
  - "Diese Säule wird nicht benötigt" → Auf 0% setzen, Rest neu verteilen, erneut vorschlagen

SCHRITT 4. Endgültige Genehmigung
  "Die endgültige Gewichtung wird festgelegt. Der Evaluator bewertet mit dieser Gewichtung."
  → Anstelle der Standardgewichtung in evaluator-protocol.md wird diese vereinbarte Gewichtung verwendet

1-6. Automatische Zuordnung von Architekturmustern

→ Siehe references/architecture-patterns.md → Basierend auf Stufe-2–3-Antworten wird das am besten geeignete Muster vorgeschlagen

Anwendungstyp	Empfohlene Schichtenstruktur
Fullstack-Web-App	Types→Config→Repo→Service→Runtime→UI
API-Dienst	Types→Config→Repo→Service→Runtime
CLI-Tool	Types→Config→Core→CLI
Bibliothek	Types→Core→Public API

1-7. Planner-Ergebnisse

① Zusammenfassung des Projektkontexts — Zweck, Benutzer, Erfolgskriterien, Kernbeschränkungen (basierend auf Stufe 1–2) ② Architekturentwurf — Schichtenstruktur, Modulgrenzen, Abhängigkeitsrichtungen ③ Ordnerstruktur-Entwurf — basierend auf references/coding-folder-patterns.md ④ Entwurf der Erzwingungsregeln — Welche Regeln werden durch Linter/CI/Strukturtests erzwungen? ⑤ Teststrategie — Umfang von Unit/Integration/E2E und Abdeckungskriterien ⑥ Entwurf der Agentenautonomie — Review-Schleifen, Genehmigungs-Gates, Eskalationskriterien ⑦ Erweiterungsstrategie — Designentscheidungen zur Vorbereitung auf zukünftige Erweiterungen (basierend auf Stufe 4 E2) ⑧ Bewertungskriterien + vereinbarte Gewichtung — 7-Säulen-Checkliste + Gewichtungstabelle

[Planner abgeschlossen — Benutzergenehmigung anfordern]
①~⑧ überprüfen und Änderungen mitteilen.
Nach Genehmigung beginnt der Generator mit dem Bau.

---

L1 Phase 2: Build — Generator-Ablauf

2-1. Kernergebnisse erstellen (in der Reihenfolge)

Nr.	Ergebnis	Beschreibung
2-1a	Architekturdiagramm	Mermaid — Schichten · Module · Abhängigkeitsrichtungen
2-1b	AGENTS.md (~100 Zeilen)	Rollen als Inhaltsverzeichnis, inkl. Referenz-Routing
2-1c	docs/-Verzeichnis	Details unten
2-1d	Architekturerzwingungsregeln	Linter-Regeln + Strukturtests
2-1e	CI/CD-Pipeline-Design	Validierungs-Gates definieren
2-1f	Teststruktur	Testverzeichnisse + Basiskonfiguration
2-1g	Sitzungs-Handoff-Ergebnisse	progress.json + feature-status.json
2-1h	Code-Review-Schleifen-Setup	Protokoll für Agenten-Reviews
2-1i	Observability-Einrichtung	Zugriffsmethoden für Logs · Metriken · DOM
2-1j	README.md	Entwicklerleitfaden
2-1k	bkit-Projektinitialisierung	Nur bei T3-Erkennung von Claude Code + bkit-Installation nach Benutzer-Opt-in-Frage ausführen (Details unten)
2-1l	Umgebungseinrichtung	Virtuelle Umgebung · Umgebungsvariablen · Hooks — Nicht erzwingen. Vorschlag durch LLM in Phase 3-7, dann Benutzerwahl
2-1m	Flussänderungsverlauf (optional)	Nur wenn Stufe 3.5 F1=Ja. Siehe ~/.claude/skills/harness-designer-workspace/references/flow-history-template.md und erstelle 05-flow-history/ + 00-system/protocols/flow-change-protocol.md. Füge zu AGENTS.md 2 Routing-Zeilen + Abschnitt "Flussänderungsverfolgung (selektive Aufzeichnung)" hinzu. Verwaltungsprinzip: Nur Systemänderungen (Regeln · Verfahren · Werkzeuge) aufzeichnen. Artefakte (Code · Berichte) sind nicht aufzuzeichnen. Abgrenzungskriterium: "Wäre das Ergebnis des nächsten Laufs anders, wenn diese Änderung nicht stattgefunden hätte?"

2-1b. Schreibregeln für AGENTS.md (Höchste Priorität)

→ Siehe references/agents-md-template.md

Die Kernlektionen des OpenAI-Originals direkt anwenden:

~100 Zeilen Inhaltsverzeichnis. Keine Enzyklopädie.

# [Projektname]

> [Einzeiler-Beschreibung]

## Architekturüberblick
[3-Zeilen-Zusammenfassung der Schichtenstruktur]
→ Details: docs/architecture.md

## Referenz-Routing
| Situation | Zu lesende Datei |
|------|----------|
| Architekturregeln | → docs/architecture.md |
| Codierkonventionen | → docs/conventions.md |
| Domänendesign | → docs/design/[domain].md |
| Ausführungsplan | → docs/exec-plans/[plan].md |
| Qualitätsstufen | → docs/quality-grades.md |
| Technische Schulden | → docs/exec-plans/tech-debt-tracker.md |
| Sitzungsstatus | → progress.json |
| Funktionsstatus | → feature-status.json |

## Kernregeln (maximal 5)
1. [Unveränderliche Regel 1 — z. B. "Datenform an allen Grenzen validieren"]
2. [Unveränderliche Regel 2 — z. B. "Keine Abhängigkeiten entgegen der Schichtenrichtung"]
3. [Unveränderliche Regel 3]

## Testregeln
→ docs/testing-strategy.md

## Befehle
| Befehl | Funktion |
|--------|------|
| /implement [Funktion] | Funktion implementieren |
| /review | Code-Review ausführen |
| /test | Tests ausführen |
| /refactor [Ziel] | Refactoring |

## Letztes Update: YYYY-MM-DD

2-1c. docs/-Verzeichnis (System of Record)

→ Siehe references/docs-structure.md

docs/
├── architecture.md         ← Schichtenstruktur, Modulgrenzen, Abhängigkeitsrichtungen
├── conventions.md          ← Code-Konventionen, Namensgebung, Formatierung
├── testing-strategy.md     ← Testpyramide, Abdeckungsziele, Ausführung
├── quality-grades.md       ← Qualitätsstufen-Definition, Messkriterien
├── design/                 ← Domänendesign, Datenmodell, Geschäftslogik
│   └── [domain].md         ← Domänen-Design-Dokument (pro Domäne eine Datei)
├── exec-plans/             ← Ausführungspläne (von Agenten erstellt/verwendet)
│   ├── [plan].md           ← Ausführungsplan
│   └── tech-debt-tracker.md ← Tracking technischer Schulden
├── protocols/              ← Kommunikationsprotokolle (wenn in AGENTS.md ausgelagert)
│   ├── review-protocol.md  ← Agenten-Review-Protokoll
│   └── handoff-protocol.md ← Sitzungsübergabeprotokoll
└── images/                 ← Architekturdiagramme, Screenshots usw.

2-1d. Architekturerzwingungsregeln (Mechanical Enforcement)

→ Siehe references/enforcement-rules.md

Zwei Arten:

Art	Beispiele
Linter-Regeln (vom Tool erzwungen)	eslint-plugin-import Zyklenprüfung, Layer-Importbeschränkungen (z. B. @layers/*-Pfad)
Strukturtests (vom Test-Framework validiert)	pytest-Pfad-Scanner der Schichtenstruktur, Abhängigkeits-Diagramm-Prüfung

Generator Ausgabeformat:

## Regel 1: [Name]
- Typ: Linter / Strukturtest
- Ziel: [Datei/Verzeichnismuster]
- Prüfregel: [Bedingungen für Fehler/Schwellenwert]
- Fehlermeldung: [Meldung, die dem Agenten die Korrektur beibringt]

2-1k. bkit-Projektinitialisierung (Nur bei Claude Code + Benutzer-Opt-in)

Falls T3: "Claude Code" und bkit (Block Kit) installiert ist, vorher mit folgender Frage nachfragen: """ Möchten Sie, dass bkit den Projekt-Scaffold initialisiert?

• bkit erstellt Dateien wie CLAUDE.md, Makefile, Erweiterungen.
• Ohne bkit wird alles manuell erstellt. """

Nur bei Benutzerantwort "Ja": """ Führen Sie bkit im Projektstammverzeichnis aus: bkit init """

Danach fahre fort mit der Erstellung der oben genannten Dokumente (AGENTS.md, docs/ usw.).

---

L1 Phase 3: Verify — Evaluator-Ablauf

→ Siehe references/evaluator-protocol.md

3-1. Evaluator-Bewertung (basierend auf vereinbarter Gewichtung)

Jede Säule wird gewichtet bewertet. Die Gewichtung der 7 Säulen wird durch die in Phase 1-5 vereinbarte Benutzer-Gewichtung ersetzt.

Evaluator-Säulen-Bewertungstabelle:

ID	Säule	Items	Max	Gewichtung
PD	Progressive Disclosure	3	15	Gewichtung_PD
ME	Mechanical Enforcement	4	20	Gewichtung_ME
FL	Feedback Loop	3	15	Gewichtung_FL
SC	Session Continuity	3	15	Gewichtung_SC
EM	Entropy Management	3	15	Gewichtung_EM
AR	Architectural Rigidity	4	20	Gewichtung_AR
OR	Observable Runtime	3	15	Gewichtung_OR
Gesamt		23	100	100

3-2. Agenda der Evaluator-Prüfung

Schritt 1: Strukturprüfung (automatisiert)

• Existiert AGENTS.md? (PD)
• Existieren docs/*.md? (PD)
• Existiert die Linter-Konfiguration? (ME)
• Existiert die CI/CD-Konfiguration? (ME)
• Existiert progress.json + feature-status.json? (SC)

Schritt 2: Regelprüfung (Analyse)

• Sind die Linter-Regeln aktiviert? (ME)
• Sind die Abhängigkeitsrichtungen definiert? (AR)
• Sind die Modulgrenzen definiert? (AR)
• Sind die Fehlermeldungen korrektur-orientiert? (FL)

Schritt 3: Logikprüfung (Rollenspiel)

• Simuliere Szenario 1: "Fehler beim Bauen" → Funktioniert die Feedback-Schleife? (FL)
• Simuliere Szenario 2: "Sitzungsabbruch" → Funktioniert die Wiederherstellung? (SC)
• Simuliere Szenario 3: "Langzeitwartung" → Funktioniert die Entropie-Verwaltung? (EM)

Schritt 4: Benutzer-Validierung

• Der Benutzer validiert die Architektur (Berechtigungen, Prioritäten usw.)
• Prüfe, ob alle in Phase 1 Discovery vereinbarten Punkte erfüllt sind

3-3. Evaluator-Ergebnisformat

## Evaluator-Bewertungsergebnis

### 1. Strukturprüfung
[automatisierte Checkliste hier]

### 2. Regelprüfung
[Analyse-Checkliste hier]

### 3. Logikprüfung
[Szenario-Ergebnisse hier]

### 4. Säulen-Gewichtungs-Punkte
| Säule | Max | Erreicht | Gewichtung | Gewichtet |
|-------|-----|----------|------------|-----------|
| PD | 15 | [Wert] | [Wert]% | [Wert*Gewichtung] |
...
| **Gesamt** | **100** | **[Wert]** | **100%** | **[Summe]** |

### 5. Bewertung
Erreichte Punktzahl ≥ 70? → PASS / FAIL

### 6. Nächste Schritte
- Wenn FAIL: Gebe Verbesserungsvorschläge (nach Säule gruppiert) und fordere Generator zur Neuerstellung auf
- Wenn PASS: Gebe Genehmigung. Wechsel zu LAYER 2 (Betrieb).

### 7. Pattern Fidelity-Prüfung
Nur referenziell, keine Punkte. Bestätige, dass die Abweichung vom ausgewählten exemplar signifikant ist oder nicht.
- Exemplar: [Name]
- Abweichungsgrad: [Niedrig / Mittel / Hoch]
- Fazit: [Kommentar]

3-4. Evaluator-Fail-Wiederholung

• Generator erhält Feedback → Neuerstellung → Evaluator prüft erneut
• Bis zu 3 Wiederholungen möglich; nach 3 Fehlschlägen wird der Benutzer um Entscheidung gebeten

3-5. Linter-Fehler + LLM-Vorschlagsintegration (Phase 3-7)

Nicht vom Generator automatisch erzeugt, sondern LLM liest Dateien → findet Fehler → schlägt Korrekturen während des Reviews vor. Diese Phase ist die natürliche Feedback-Schleife des Evaluators.

Weitere Services (in _workspace/-Verzeichnis erstellte Dateien, LLM-Vorschlag):

• .claude/settings.local.json — LLM liest und schlägt Inhalte vor
• .pre-commit-config.yaml — LLM schlägt vor
• pyproject.toml / package.json Einstellungen — LLM schlägt vor
• Makefile / Taskfile.yml — LLM erstellt vor
• .gitignore — LLM erstellt vor

Diese Services werden nach Evaluator PASS erstellt, nicht vorher.

---

LAYER 2: Betrieb — Wie die vollständige Coding-Harness arbeitet

Dieser Abschnitt beschreibt die Funktionsweise der in LAYER 1 erstellten fertigen Harness. Die folgende Struktur ist im generierten CLAUDE.md enthalten.

---

Die fertige Coding-Harness besteht aus den folgenden Workflows. Grundlage für die Sitzungsfortsetzung:

• progress.json — Status der aktuellen Sitzung
• feature-status.json — Gesamtfunktions-Status des Projekts

Initializer (Erster Lauf)

Wenn die Harness bereitgestellt ist, läuft der Agent nach Eingang einer neuen Aufgabe im Folgenden ab:

1. Initiale Umgebung (Setting)
   • Projekt-Scaffold überprüfen (Ordnerstruktur)
   • Abhängigkeiten installieren
   • Ersten Ausführungsplan erstellen → docs/exec-plans/initial-plan.md

Coding Agent (Wiederholter Lauf)

Für jede Iteration (Codieren, Testen, Review, Deploy):

1. Fortschritt lesen → progress.json lesen → Nächste Aufgabe auswählen
2. Implementieren → Code generieren (Single-Responsibility-Prinzip befolgen)
3. Selbstvalidierung → Tests ausführen + Linter + Build
4. Review anfordern → Von anderem Agenten oder Benutzer Code-Review anfordern (Reihenfolge: zuerst anderer Agent, falls nicht vorhanden → Benutzer)
5. Feedback einarbeiten → Review-Feedback anwenden → Neu testen → Bei Erfolg weiter
6. Commit → Nach erfolgreicher Validierung im sauberen Zustand committen

Code-Review-Protokoll

→ Siehe docs/protocols/review-protocol.md

Grundlegende Regeln:

• Reviewer prüft Code + Tests + Architekturkonformität
• Reviewer bestätigt: "Lint bestanden, Tests bestanden, Architekturregeln eingehalten, Codequalität ausreichend"
• Kommentare sind als Korrekturanweisungen formuliert (die der Agent umsetzen kann)

Fehlerbehandlung

• Bei Kompilierungsfehler: Der Agent versucht automatisch die Korrektur (bis zu 3 Versuche)
• Bei Testfehler: Der Agent debuggt die fehlgeschlagenen Tests und korrigiert den Code
• Bei ungelöstem Problem: Der Agent dokumentiert das Problem, fährt mit der nächsten Aufgabe fort und erstellt eine tech-debt-Aufgabe

Qualitätsstufen-Management

→ Siehe docs/quality-grades.md

Der Agent verwaltet die Codequalität selbstständig:

• A (Grün): Keine Probleme, alle Tests bestanden, keine technischen Schulden
• B (Gelb): Kleinere Abweichungen, einige technische Schulden → Nächste Aufgabe adressiert diese
• C (Rot): Kritische Probleme → Priorisierte Behebung, Unterbrechung anderer Aufgaben

---

Metriken und deren Verwendung (Lagging/Lead-Indikatoren)

πρέπει — Dies sind keine optionalen Empfehlungen, sondern Systemanforderungen.

Bereich	Metrik	Typ	Quelle	Nutzung
Session Continuity	Wiederherstellungsrate	Lead	progress.json	Handoff-Qualität messen
Actuation (Run Loop)	Aufgaben-Bearbeitungszeit	Lagging	git log + progress.json	Engpässe in der Schleife identifizieren
Observability (Feedback)	Fehlerwiederholungsrate	Lead	CI-Protokoll	Qualität der Fehlermeldung messen
Mechanical Enforcement	Linter-Verstöße/1000 Zeilen	Lagging	Linter-Ergebnis	Architekturzerfall messen

Jede Metrik in _workspace/00_input.md:

• Messfrequenz: [täglich | wöchentlich | je Sitzung]
• Benachrichtigungsschwellwert: [bei Überschreitung benachrichtigen]
• Korrekturprotokoll: [wenn Schwellwert überschritten]

---

Anhang: Wichtige Prämissen und Protokolle

Grundprinzip (Source of Truth)

Agenten folgen dem Code, nicht dem Prompt.

• Der Prompt ist die Einstiegstür: zeigt den Weg zu Dateien.
• Die Dateien sind die Wahrheit: Regeln, Tests, CI.
• → Wenn der Prompt und die Dateien widersprüchlich sind, haben die Dateien Vorrang.

Protokoll-Prioritäten

Wenn mehrere Protokolle auf eine Situation anwendbar sind:

1. Kodierte Regeln (Linter, CI, Strukturtests) haben höchste Priorität
2. Systemprotokolldateien (docs/protocols/*.md) haben zweithöchste Priorität
3. Konfiguration (AGENTS.md, CLAUDE.md) haben niedrigste Priorität

Prämissen-Änderungsprozess

Wenn eine Annahme während des Betriebs ungültig wird:

1. Dokumentiere die Änderung in _workspace/00_input.md
2. Überprüfe, ob die Änderung die 7 Säulen betrifft
3. Wende die Änderung auf die betroffenen Regeln/Tests/Konfigurationen an
4. Leite eine Evaluator-Neuvalidierung ein (optional)