admin/ki-hinter-vorhang
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ki-hinter-vorhang/AGENTS.md
T

11 KiB
Raw Permalink Blame History

AGENTS.md — Next Token („Die KI hinter dem Vorhang“)

Projekt-Regeln für Grok Build. Karpathy-Prinzipien, übertragen auf ein deutsches Sachbuch. Tradeoff: Vorsicht vor Geschwindigkeit. Bei trivialen Tasks nach eigenem Ermessen handeln.

1. Denken vor dem Schreiben

  • Annahmen explizit. Bei Unsicherheit: nachfragen.
  • Mehrere Lesarten → Alternativen zeigen, nicht still wählen.
  • Unklare Anweisung → stoppen, benennen, nachfragen.
  • Fakten: zuerst research/ (bes. timeline-faktenblatt.md, faktencheck-v2/).
  • Lektorat: zuerst das Ziel der Änderung verstehen, dann editieren.

2. Einfachheit zuerst

  • Kürzeste präzise Erklärung. Keine ungefragten Exkurse, Boxen oder Kapitel-Umbauten.
  • Kein Hype, keine Alarm-Rhetorik, keine AGI-Jahreszahlen.
  • Etablierte Begriffe definieren statt neue erfinden.

3. Chirurgische Änderungen

  • Nur Textstellen der Aufgabe anfassen. Keine Drive-by-Edits.
  • Ton beibehalten: demystifizierend, nüchtern, technisch korrekt.
  • Illustration-/Figure-Marker und Box-Trigger nicht umformatieren.
  • Auffällige tote Referenzen erwähnen, nicht still löschen.

4. Zielgetriebenes Arbeiten

Vage Wünsche → prüfbare Ziele. Bei Mehrschritt: Checkpoints nennen und verifizieren.

Wunsch Erfolgskriterium
Lektorier Kap. N 6 Checkpoints (Ton, Fakten, Terminologie, Wiederholungen, Verständlichkeit, Struktur); P0/P1 mit Zeilen
Review Kap. N 4 Dimensionen; Feedback only, kein Edit
Bau das PDF just pdf + just qa grün
Print-PDF (KDP) just pdf-print + just qa-print grün (6×9 Gray)
Faktencheck Claims gegen research/; Unsicherheit markiert
Handoff HANDOFF.md ≤ 60 Zeilen nach .grok/skills/status/references/handoff-vorlage.md; SHA, AE-Tabelle und „Nicht still“ stimmen; kein Changelog
Zahlen stimmen just konsistenz: keine neue ABWEICHUNG; Inhaltliches → AE-Frage

5. Dateihoheit, Entscheidungen, Korrekturen

  • Dateihoheit: manuskript/, pdf/front/, research/, Bilder (assets/, prompts/imagine/) und marketing/ nur mit ausdrücklichem Auftrag ändern, der Datei oder Stelle nennt. Sonst melden.
  • Keine Inhaltsentscheidungen. Offene Fragen werden nummerierte AE-Fragen (AE-01 ff., Tabelle in HANDOFF.md): Stelle datei:zeile, Optionen, Diff-Skizze, Empfehlung „ungeprüft“. An der Stelle nichts ändern. Entschiedene AEs werden nicht neu geöffnet; lässt sich eine nicht wie beschlossen umsetzen: neue AE.
  • Korrekturen aus Audits sind ungeprüfte Claims. Ersatzsätze aus Audits, Prüfprotokollen oder research/ erst übernehmen, wenn die Primärquelle geöffnet ist (Fundstelle in Commit oder Bericht). Es gilt die neueste Prüfung mit geöffneter Primärquelle; widersprechen sich zwei solche Prüfungen: AE.
  • Lieber streichen als verneinen. Keine Sätze darüber, was ein Kapitel nicht behauptet. Keine neuen Formel- oder Schablonensätze; bei Korrekturen vorher/nachher zählen (rg).
  • Keine Kompromiss-Spannen. Zwei Quellen, zwei Zahlen: nicht mitteln, sondern Quelle und Stand (Version, Datum) festlegen und abhängige Rechnungen mitziehen. „Gibt es nicht“-Aussagen doppelt prüfen (zweite Quelle oder Zweitprüfer).
  • Gedankenexperimente bleiben als solche erkennbar („Stellen Sie sich vor …“), nie als echtes Ereignis.
  • Sub-Agenten: .grok/rules/subagenten.md (Text deepseek-v4_1-flash ohne Effort, Bilder Grok 4.7 low, minimaler Kontext).

6. Seiten und Umschlag

Print-Seitenzahl, _print_pages im justfile und Rücken (just kdp-cover) gehören zusammen. Nach jedem just pdf-print: just konsistenz. Weicht die gemessene Zahl von _print_pages ab: melden; mit Auftrag _print_pages setzen und just kdp-cover im selben Commit. Seitenzahlen nie in Doku festschreiben, messen. Nach Textänderungen gelten PDF, Print und EPUB als STALE; neu bauen nur mit Auftrag.

Projekt-Kontext

Sachbuch über moderne KI für Laien ohne Informatik-Hintergrund. Keine Mathematik.

Kern-These: Fast alle heutigen KI-Systeme basieren auf Next-Token-Prediction.

Zentrale Unterscheidung: Modell (= Next-Token-Predictor) vs. System/Harness (= Tools, Filter, Protokolle, Planung).

Ton: demystifizierend, nüchtern, technisch korrekt.

Detail-Regeln: .grok/rules/schreibkonventionen.md · Pipeline: .grok/rules/bau-pipeline.md

Wichtige Pfade

Pfad Rolle
HANDOFF.md Session-Arbeitszettel (kurz; siehe § Handoff)
manuskript/*.md Kapitel-Quellen (Vorwort, Prolog, Kap. 1–10, Epilog, Anhang; Reihenfolge scripts/assemble_book.py) — nur mit Auftrag
research/ Fakten, Timeline, Faktencheck-v2 — vor Behauptungen lesen; ändern nur mit Auftrag
abbildungen.md Didaktischer Illustrations-Katalog
assets/ Illustrationen/Cover — nur mit Auftrag (/abbildung)
audits/ Berichte von Prüf- und Optimierungsläufen
pdf/** Template/Filter — nur auf expliziten Auftrag
scripts/* Assembler, QA, Cover — ausführen, nicht umbauen
justfile Build-Orchestrierung; _print_pages = Seitenzahl für den Umschlag
scripts/konsistenz_check.py Meta-Zahlen messen (just konsistenz), nur lesend

Build & QA

just pdf          # A4 eBook: assemble → pandoc → lualatex
just pdf-draft    # Mit ENTWURF-Wasserzeichen
just pdf-sample   # Prolog + Kap. 1–2 (schnell)
just pdf-print    # KDP Interior 6×9 Grayscale
just qa           # eBook-QA
just qa-print     # Print-QA (Page size, Gray-Assets)
just clean        # build/ + dist/*.pdf (nachfragen)
just konsistenz   # Zahlen messen (nur lesend)
just kdp-cover    # Umschlag, Seiten aus _print_pages (nur mit Auftrag)

Erfolg eBook: dist/die-ki-hinter-dem-vorhang.pdf existiert, QA ohne Fehler.
Erfolg Print: dist/die-ki-hinter-dem-vorhang-print.pdf (6×9), just qa-print ohne FAIL.
TeX Live liegt nicht in Devbox (Host).

Sandbox: Alltag workspace oder off (PDF braucht Host-TeX). Nur Gegenlesen: read-only.

Skills & Commands

Slash Wann
/lektorat <kapitel> 6-Checkpoint-Lektorat
/review <kapitel> Gegenlese (4 Dimensionen, kein Edit)
/faktencheck <kapitel> Claims vs. research/
/lesepass Buchweite Wiederholungen/Brücken
/total-check Buchweite Vollprüfung, max. Sub-Agenten, Protokoll
/pdf [full|draft|sample] eBook-PDF bauen + QA
/pdf-print [full|assets-only|qa-only] KDP Interior 6×9 + Print-QA
/status Arbeitsstand: zuerst HANDOFF.md, dann just konsistenz, Faktencheck-v2 / Git
/konsistenz [--formate|--strict] Kapitel, Wörter, Bilder, Stichtag, Auflage, Seiten/Umschlag messen
/bildpruefung [alle|I-ID] Abbildungen nur berichtend prüfen (Grok 4.7 low)
/abbildung <I-ID> Eine Abbildung erzeugen/nachziehen (Imagine) — der Aufruf ist der Auftrag
/kdp-vorab Upload-Reife prüfen, nichts hochladen

Box-Trigger & Marker (nicht zerstören)

Trigger als Markdown-Header (##/###), nicht als Blockquote. Filter: pdf/filters/boxes.lua.

Überschrift Box
### Kern in einem Satz, ### Worum geht es intro
### Zusammenfassung (H2 ebenfalls ok) summary
### Für Neugierige, Vertiefung, Zum Weiterdenken vertiefung
### Häufiges Missverständnis, Überblick, Stand der Technik info 
<!-- illustration: assets/illustrations/<tier>/I-XX-description.jpg -->

Optional/ungenutzt im Manuskript: <!-- figure: … caption="…" -->

Terminologie (Kern)

Begriff Bedeutung Nicht
LLM Large Language Model, Next-Token-Predictor —
Token kleinste Texteinheit (~¾ Wort) —
Harness Software-Schicht ums Modell Wrapper, Framework
Modell vs. System LLM vs. LLM+Harness vermischen
MCP Model Context Protocol —
JEPA Joint Embedding Predictive Architecture —
AGI immer problematisieren Superintelligenz als Fakt

Glossar: manuskript/glossar.md

Handoff

HANDOFF.md ist der Startzettel für die nächste Session, kein Arbeitsprotokoll.

Inhalt (in dieser Reihenfolge, eine Datei, ≤ 60 Zeilen, Vorlage .grok/skills/status/references/handoff-vorlage.md): Stand + HEAD + Messung (just konsistenz); Letzte Arbeit (2–4 Sätze); AE-Tabelle; ein Einstiegsblock; Offene Reste nur mit Auftrag; Nicht still; Verweise (git, research), kein zweiter Einstieg.

Aktualisieren nur an einer Phasengrenze oder wenn SHA / „nicht nochmal“ sonst falsch wäre. Nicht nach jedem kleinen Diff. Nicht weil eine Smartzone-Regel „Handoff + neue Session“ vorschlägt.

Nicht in die Datei: 0ak-Changelog, SHA-Archäologie, doppelte Scorecards, überholte PDF-Zähler. Das bleibt in git log und in research/-Protokollen.

Commit: Handoff mit der Arbeit mitziehen, der er gilt. Kein eigener Commit, dessen einzige Änderung SHA-Nachzug ist. I-12b-Prompt und pics/ nicht still mitziehen.

Git

  • Commit-Messages auf Deutsch, klar was am Manuskript/Build geändert wurde.
  • Kein Force-Push (auch nicht --force-with-lease), kein reset --hard, kein rebase, kein commit --amend, nie --no-verify. Keinen Branch oder Tag löschen. Den Stash nicht anfassen. Der Hook .grok/hooks/protect-pipeline.sh blockt das auch im yolo-Modus; nach Hook-Änderungen sh scripts/test_hook.sh (Exit 0 = alle Fälle wie erwartet).
  • yolo-Läufe: git status --porcelain nicht leer → anhalten, nichts committen oder verwerfen. Dann lokaler Backup-Tag pre-<lauf>-YYYY-MM-DD (existiert er: -2, nie überschreiben), eigener Branch, ein Commit je Schritt. Merge nur --ff-only nach main; rework nicht mergen. Push nur am Ende und nur bei grüner QA bzw. grünem Check.
  • Keine Secrets committen.
  • git push / git commit nur mit Freigabe (Permission-Ask).
  • Keine PAT/API-Keys in Repo-Dateien (auch nicht in .grok/config.toml).

Do’s & Don’ts

Do Don’t
research/ vor Faktenbehauptungen Produktnamen ohne Stichtag
Chirurgische Diffs Umliegende Absätze „mitverbessern“
Modelle generieren/raten Modelle wissen/verstehen/denken (als Next-Token)
Box-Trigger exakt schreiben Marker umformatieren oder HTML/LaTeX in Kapitel
Nach PDF: just qa lesen QA-Warnungen blind ignorieren
Unsicherheit markieren Hype / Alarm / AGI-Jahreszahlen
Bei Lektorat: P0 freigeben lassen Stille Massenedits am Manuskript

Nächste sinnvolle Arbeitsschritte

Die aktuelle Liste steht in HANDOFF.md (Offen / Nicht still). Hier nur der Dauer-Hinweis: Lesepass, Faktencheck-v2-Reste und Stichtage nur mit Auftrag — nicht still aus dieser Datei ableiten.

Regeln greifen, wenn: Diffs nur zur Aufgabe gehören, Rückfragen vor riskanten Edits kommen, und Fakten aus research/ stammen.

Reference in new issue View Git Blame Copy Permalink