ki-grok/01-einfuehrung-und-philosophie.md

Kapitel 1

Einführung und Philosophie – was Grok Build wirklich ist

Kern in einem Satz: Grok Build ist ein agentischer Harness um ein Sprachmodell: Das Modell schlägt vor, der Harness prüft Regeln, führt Tools aus und speist Ergebnisse zurück – und genau diese Schleife steuerst du mit Scope, Modes, Dateien und Review.

---

1.1 Der Montagmorgen, den du kennst

Du öffnest das Ticket: „Login-Flow bricht ab, wenn der Refresh-Token abgelaufen ist.“ Drei Dateien sind verdächtig, die CI ist rot, der Kollege ist im Urlaub. Früher hättest du gesucht, gelesen, spekuliert, einen Fix skizziert, Tests geschrieben.

Mit Grok Build tippst du im Projektordner grok und gibst einen engen Auftrag:

Untersuche den Refresh-Token-Fehler im Login-Flow.
Lies nur auth- und session-bezogene Dateien.
Ändere noch nichts. Fasse Ursache und 2 Fix-Optionen zusammen.

Was passiert dann – und was nicht? Das Modell plant Schritte. Der Harness lässt es Dateien lesen und suchen. Du siehst Tool-Aufrufe im Scrollback. Am Ende hast du eine Analyse – ohne dass schon Code geschrieben wurde. Das ist der philosophische Kern dieses Buchs: Zuerst verstehen und steuern, dann handeln lassen.

Warum der enge Prompt zählt: „Fix the login“ ohne Scope lädt den Agenten ein, halb das Repo umzubauen. Die Junior-Metapher hilft: Du gibst Auftrag, Scope und Definition of Done – nicht „mach mal irgendwas Sinnvolles“.

---

1.2 Die wichtigste Unterscheidung: Modell vs. Harness

Wenn Marketing „KI schreibt deinen Code“ sagt, verschmelzen zwei Schichten zu einer Phrase. Trenne sie bewusst – sonst optimierst du am falschen Knopf (lauter prompten statt Plan Mode, AGENTS.md und Permissions).

Schicht	Was sie ist	Was sie tut
Modell	Next-Token-Predictor (Grok u. a.)	Erzeugt Text und strukturierte Tool-Aufrufe
Harness / System	Grok Build (TUI, Tools, UI, Config)	Führt Tools aus, prüft Safety/Permissions, speichert Sessions, lädt AGENTS.md

Was dieses Buch steuert: vor allem den Harness. Das Modell wählst du je Aufgabe (Kapitel 14); die Steuerknöpfe lernst du einmal.

Wie die Schleife läuft: Das Modell erzeugt die nächste sinnvolle Fortsetzung – oft in Form von „jetzt lies Datei X“ oder „jetzt führe pytest aus“. Der Harness erkennt den Tool-Aufruf, prüft deine Regeln und den aktuellen Mode (Normal, Plan, Always-approve), fragt dich bei riskanten Schritten, führt aus und speist das Ergebnis zurück in den Kontext. Daraus entsteht der Eindruck von Autonomie – obwohl jede „Handlung“ ein freigegebener (oder im Always-approve-Modus vorab freigegebener) Tool-Call ist.

Das Modell „will“ nichts. Es maximiert keine Ziele und hat keine Absicht, dein Repo zu retten. Es erzeugt die fortgesetzte Antwort, die zu Prompt, Code und bisherigen Tool-Ergebnissen passt. Deshalb wirken schlechte Anweisungen und fehlende Grenzen so stark: Der Harness führt aus, was das Modell vorschlägt – im Rahmen deiner Regeln.

Wer nur das Modell sieht, überschätzt Magie. Wer nur die Tools sieht, unterschätzt, wie stark schlechte Anweisungen und fehlende Grenzen das Ergebnis ruinieren.

Ein Bild für den Alltag: Das Modell ist der Junior, der vorschlägt. Der Harness ist der Arbeitsplatz mit Tastatur, Repo-Zugriff und Sicherheitsregeln. Ohne Arbeitsplatz bleibt der Junior ein Chat. Ohne Junior bleibt der Arbeitsplatz leer. Produktivität entsteht erst, wenn du beide steuerst – und genau das ist der rote Faden der folgenden Kapitel.

{width=80%}

---

1.3 Surfaces: eine Engine, drei Arbeitsmodi

Sobald grok läuft (Installation und First-Start: Kapitel 2), stehst du vor der Wahl: interaktive TUI? Einmal-Prompt im Script? IDE über ACP? Die gute Nachricht: Es ist dieselbe Engine. Die schlechte: Wer nur klickt oder nur „yolo“ in CI drückt, sieht seltener, warum eine Freigabe greift oder eine Regel greift.

Surface	Einstieg (typisch)	Wann sinnvoll
Interaktive TUI	grok im Projektordner	Alltag, Review, Lernen, maximale Sichtbarkeit
Headless	grok -p "…"	Scripts, CI, Einmal-Jobs ohne TUI
ACP / Agent-Server	grok agent …	IDEs, SDKs, langlebige Clients über Agent Client Protocol

Was du heute mitnimmst: Starte zum Lernen in der TUI. Headless und ACP später – Config, AGENTS.md und viele MCP-Setups reisen mit. Surface wechseln ändert die UI und die Interaktivität, nicht die Grundarchitektur.

TUI: Hier siehst du Tool-Streams, Diffs, Modes und Slash-Commands am klarsten. Warum starten viele hier? Weil Plan Mode, Freigaben und Abbrüche weniger „magisch“ wirken und du die Ursache von Fehlern leichter findest.

Headless: Ausgabe, Exit-Code, Automation. Warum mächtig und riskant? Ohne interaktive Rückfragen brauchst du ein klares Permission-/Always-approve-Konzept – sonst blockiert der Job oder er tut zu viel (Kapitel 10 und 13).

ACP: JSON-RPC-Clients (IDE, eigene Bots). Warum nicht als einziger Einstieg? Du lernst dieselben Konzepte, aber die Feedbackschleife ist eine Schicht weiter weg. Erst TUI-Muskeln, dann Server-Modus (Kapitel 11).

{width=80%}

---

1.4 Was Grok Build kann – und was nicht

Grenzen sind keine Marketing-Absätze. Jede Zeile unten schützt vor einer typischen Fehleinschätzung.

Kann (realistisch):

• Codebasen erkunden und erklären – wie: Read/Grep/Glob-Tools, nicht „telepathisches Verstehen“
• Features und Fixes über mehrere Dateien planen und umsetzen – warum Plan Mode zählt: Fehler akkumulieren in langen Ketten
• Tests schreiben und ausführen, bis sie grün sind – wie: Shell-Tools + dein Verify-Command in AGENTS.md
• Git-Workflows (Diffs, Commits, PRs) mit deiner Freigabe – warum Freigabe: Commits und Push sind irreversibel genug für menschliche Ownership
• Arbeit delegieren an Subagents und optional in Worktrees isolieren – wie: eigener Kontext, parallele Tracks (Kapitel 5–6)
• Externe Systeme über MCP anbinden – warum riskant und mächtig: jedes Tool ist Code + oft Credentials
• Wiederholbare Workflows als Skills und Hooks automatisieren – wie: Skills on-demand, Hooks erzwungen
• Headless in CI und ACP in der IDE – wie: dieselbe Engine, andere Einstiegsfläche

Kann nicht (oder soll nicht allein):

• Verantwortlichkeit ersetzen – du bleibst Owner von Merge und Produktion. Ein grüner Agent-Diff ist kein freigegebener Release.
• Secrets „sicher raten“ – Secrets gehören in Env/Vault, nicht in den Prompt. Was im Kontext landet, kann in Logs, Zusammenfassungen oder Tool-Outputs weiterwandern.
• Blindes Trust in unbekannte Repos – unbekannter Code + Agent-Shell ist dasselbe Risikoprofil wie „Skript vom fremden USB-Stick“, nur höflicher formuliert.
• Unendlichen Kontext – das Kontextfenster ist endlich. Lange Sessions brauchen Compact, neue Sessions und gute AGENTS.md, sonst steigen Kosten und sinkt Qualität (Kapitel 12).
• Produktpolitik ersetzen – Auth, Kontingente und verfügbare Modelle hängen von deinem Zugang ab (Kapitel 2 und 14).

---

1.5 Philosophie: Explore → Plan → Code → Verify (danach Commit/PR)

Grok Build liefert bessere Diffs, wenn du nicht „alles auf einmal“ forderst, sondern den Tag in Phasen schneidest – dieselben Phasen, die gute Teams ohnehin nutzen:

Phase	Ziel	Typischer Grok-Hebel
Explore	Verstehen, nicht ändern	Enger Prompt („ändere nichts“), explore-Subagent
Plan	Ansatz freigeben	Plan Mode (/plan, Shift+Tab), Plan-Datei reviewen
Code	Kleine, reviewbare Diffs	Normal-Mode, klare DoD, AGENTS.md
Verify	Beweisen statt hoffen	Tests/Lint im Prompt oder als Skill/Hook
Commit / PR	Ownership	Diff lesen, Message, menschliche Freigabe

Warum diese Reihenfolge? In der Explore-Phase ist ein falscher Edit teuer, weil er Annahmen zementiert. Im Plan Mode ist der Agent read-only außer der Plan-Datei – du korrigierst den Ansatz, bevor hundert Zeilen Code entstehen (Kapitel 4). Verify trennt „fühlt sich fertig an“ von „ist grün“.

Mikrogeschichte: Ein Tech-Lead lässt den Agenten „Auth refactorn“. Ohne Plan: 40 Dateien, gemischte Patterns, rote CI. Mit Plan Mode: drei Optionen, eine freigegebene Strategie, dann Implementierung in zwei PRs. Dieselbe Modell-Intelligenz – anderer Harness-Einsatz.

{width=80%}

---

1.6 Drei Steuerknöpfe, die du früh kennen solltest

Du musst noch nicht jedes Feature auswendig können. Diese drei Knöpfe tragen 80 % des Alltags:

1. Scope im Prompt – Dateien, Nicht-Ziele, „ändere noch nichts“ / „nur Tests“ / „kein Git-Push“.
2. Mode – Normal für Umsetzung, Plan für Architektur-Ambiguität, Always-approve nur wenn du die Konsequenzen verstehst (CI, enge Sandbox).
3. Dateien statt Wiederholungen – stabiles Wissen in AGENTS.md und Rules, wiederkehrende Abläufe in Skills, erzwungene Gates in Hooks.

Wie sie zusammenspielen: Der Prompt steuert diese Session. AGENTS.md steuert jede Session im Repo. Config und Permissions steuern, was der Harness überhaupt darf. Skills und MCP erweitern, was er kann. Wer nur promptet, trainiert Ausdauer – wer Dateien pflegt, trainiert das Team.

# Schwacher Einstieg
Mach die App besser und fix bugs.

# Brauchbarer Einstieg (Deutsch)
Im Modul payments: flaky Test test_retry_timeout.
Repro finden, Ursache erklären, minimalen Fix vorschlagen.
Keine API-Änderungen. Nach dem Fix: nur tests/payments ausführen.

# Gleicher Anspruch, oft im Team-Englisch
In payments: flaky test_retry_timeout.
Find repro, explain root cause, propose minimal fix.
No API changes. After fix: run only tests/payments.

Beide starken Varianten sind gleich gut – wähle die Sprache, in der dein Team Tickets und Diffs reviewt. Warum sie gewinnen: Sie begrenzen den Suchraum, definieren Erfolg und verbieten Scope-Creep. Das Modell halluziniert weniger „Hilfs-Refactors“, weil der Harness-Kontext klar ist.

Schablone zum Abschreiben (ausführlicher in Kapitel 16):

Ziel: <was am Ende wahr sein soll>
Nicht-Ziel: <explizit out of scope>
Dateien: <pfade wenn bekannt>
Vorgehen: <explore | plan | implement>
Verify: <exakter Command, z. B. pytest -q>
Stop: <kein push / warte nach Plan>

---

1.7 Chat, Agent, IDE-Autocomplete – kurze Abgrenzung

Werkzeug-Klasse	Typische Stärke	Typische Grenze
Chat im Browser	Erklären, skizzieren, brainstormen	Kein direkter Repo-Zugriff; du kopierst hin und her
Inline-Autocomplete / Chat in der IDE	Schnelle lokale Edits, Selection-Kontext	Oft schwächer bei langen Multi-File-Ketten und Policy
Grok Build (Agent)	Tool-Loop im Repo, Plan, Subagents, Headless/ACP	Braucht Scope, Review und klare Regeln

Detailvergleich mit Claude Code, Codex und Cursor: Kapitel 17. Hier reicht die Haltung: Autocomplete beschleunigt Tippen. Ein Agent beschleunigt Arbeit – und multipliziert Fehler, wenn du nicht steuerst.

---

1.8 Sicherheit als Feature, nicht als Anhang

Achtung: Starte Grok Build nur in Ordnern, die du kennst. Nicht in Downloads mit unbekannten ZIPs. Nicht „mal eben“ auf Produktionsservern. Always-approve und Headless multiplizieren jede zu weite Regel.

Warum das hier schon steht: Ohne dieses Mentalmodell liest du Kapitel 2 als „Installationsanleitung“ und überspringst Trust. Mit diesem Mentalmodell installierst du, übst im sicheren Repo und baust Deny-/Sandbox-Gewohnheiten auf, bevor du CI-Keys einbindest.

Drei Muskeln für den ersten Tag (Tag-1-Routine – nicht dieselben wie die drei Steuerknöpfe in 1.6: Knöpfe = Hebel-Set Scope/Mode/Dateien; Muskeln = Gewohnheit Scope/Freigaben/Diffs):

1. Scope formulieren
2. Freigaben lesen statt wegklicken
3. Diffs prüfen, bevor du committest

Wer diese drei kann, steigt später in Subagents und MCP ein, ohne die Kontrolle zu verlieren.

---

1.9 Was „gut steuern“ im Alltag heißt

Szene: Feature „Export als CSV“ in einer bestehenden API.

• Explore: „Finde bestehende Export- und Streaming-Patterns. Ändere nichts.“
• Plan: /plan – Endpoint, Auth, Tests, Migrations? Eine Seite, die du kommentierst.
• Code: Freigabe, dann Implementierung in kleinen Diffs.
• Verify: pytest tests/export -q (oder dein Stack) – im Prompt oder als Skill.
• Persistenz: Was das Team immer wissen muss → AGENTS.md; was nur diese Story betrifft → Ticket/PR.

Häufiger Fehler: In der Code-Phase neue Architektur erfinden, die im Plan nicht stand. Gegenmittel: Plan Mode ernst nehmen; Abweichungen zurück in den Plan oder explizit im Prompt freigeben.

Häufiger Fehler: Eine Session für „alles bis Release“. Gegenmittel: Neue Session pro klarer Teilaufgabe; Kontext ist endlich (Kapitel 12).

---

1.10 Checkliste: Mentalmodell sitzt

• Ich kann Modell und Harness in einem Satz unterscheiden.
• Ich kenne die drei Surfaces (TUI, Headless, ACP) und starte bewusst in der TUI.
• Ich formuliere Scope und Nicht-Ziele, bevor der Agent schreibt.
• Ich weiß, warum Plan Mode vor großen Features kommt.
• Ich behandle Diffs und Freigaben als Teil der Arbeit, nicht als nervige UI.

---

1.11 Mini-Glossar für den Einstieg

Spickzettel vor Kapitel 2. Ausführlicher: Kapitel 18.14.

Begriff	In einem Satz
Harness	Schicht ums Modell: Tools, Permissions, Sessions, Modes – was dieses Buch steuert
Tool-Call	Konkreter Handlungsschritt (lesen, shell, edit), den der Harness freigibt und ausführt
Session	Ein Arbeitsgespräch mit Kontext; nicht endlos führen
CWD	Working Directory – Ordner, in dem grok die Dateien „sieht“
Diff	Zeilen-Ansicht der Änderung (+/−); vor Allow und vor Commit lesen
Plan Mode	Read-only planen, Plan-Datei freigeben, erst dann Code
Always-approve / YOLO	Fast keine Klick-Freigaben – Deny/Hooks bleiben; Tag 1 aus
Compact	Kontext zusammendrücken (verlustbehaftet) – mit Hinweis, was behalten werden soll
Deny	Harte Regel: dieser Tool-Call wird blockiert, auch unter Always-approve
Folder-Trust	Vertrauens-Gate für project-lokale Hooks/MCP – nur bekannte Repos
MCP / ACP	Externe Tools bzw. IDE/Server-Protokoll – später (Kapitel 9 und 11)

---

Was du jetzt kannst

• Modell und den Harness von Grok Build unterscheiden und die Tool-Schleife skizzieren
• TUI, Headless und ACP einordnen und erklären, was über Surfaces hinweg gilt
• Den Zyklus Explore → Plan → Code → Verify als Steuerungsphilosophie anwenden
• Erklären, warum Scope, Modes und AGENTS.md keine Nice-to-haves sind, sondern die Steuerknöpfe des Harness
• Die Day-1-Begriffe aus dem Mini-Glossar in einem Satz erklären

Nächste Schritte

→ Kapitel 02 – Installation und erster Start: Binary installieren, anmelden und die ersten sicheren Aufgaben – Standard: beispiele/todo-cli.