admin/ki-grok
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ki-grok/16-best-practices-tipps-tricks-troubleshooting.md
T
grok-bot 17a2bc8a45 Ship Codex-parity harness, chapter polish, and rebuilt PDF. 
Add reader vorlagen (permissions, MCP, hooks, plugins, team AGENTS),
humanizer skill, and adaptionen for ki-codex; refresh chapters 00–18,
resource-path justfile, and dist PDF with full illustration set.
2026-08-02 21:19:46 +02:00

8.3 KiB
Raw Permalink Blame History

Kapitel 16

Best Practices, Tipps und Troubleshooting

Kern in einem Satz: Die meisten „Grok spinnt“-Tickets sind Kontext-, Permission-, Trust-, Scope- oder Erwartungsprobleme – gelöst mit Systematik, nicht mit lauteren Prompts.

Stand der Fakten im Buch: Juli–Aug 2026 (CLI 0.2.x); UI-Labels und einzelne Commands können driften.

Schnellpfad Symptom → Fix: 16.6.
Prompt-Rezepte: 16.2.

16.1 Best Practices – kompakt

Alltag: Ticket, Diff, CI-Fail – die folgenden Blöcke decken den Großteil der Fälle. Details und Kanon sitzen in den Fachkapiteln; hier die kompakte Reprise.

Prompts

  1. Ziel + Nicht-Ziel + Verify in jedem nicht-trivialen Auftrag
  2. Dateipfade nennen, wenn bekannt
  3. „Ändere nichts“ bei Explore explizit
  4. Fehler: komplette Meldung, nicht „geht nicht“
  5. Ein Thema pro Prompt-Block; Queue bewusst nutzen

Repo

  1. AGENTS.md kurz, Commands exakt
  2. Deny für Secrets und Force-Push von Tag 1
  3. Skills = Verfahren, Rules = Normen, Hooks = Zwang
  4. Kleine PRs – auch wenn der Agent 40 Dateien anbietet

Sessions

  1. Ein Thema pro Session
  2. /context lesen, bevor du „lauter“ wirst
  3. /plan vor multi-file Ambiguität
  4. /compact mit Hinweis, nicht blind
  5. Entscheidungen in Dateien/PR persistieren
  6. Vor Merge: frische Review-Session oder Mensch

Sicherheit

  1. Kein Always-approve auf Alltagsrechnern mit Prod-Zugang ohne Deny
  2. MCP wie Dependencies reviewen
  3. Folder-Trust nur für bekannte Repos
  4. CI least privilege + API-Key als Secret

Parallelität

  1. Explore parallel, Writes serial oder Worktrees
  2. Parent orchestriert Integration-Verify
  3. Plan-Parent sperrt Kind-Edits nicht automatisch

16.2 Prompt-Engineering für Grok Build

Grok Build ist ein Agent mit Tools, kein reiner Chat. Gute Prompts steuern den Harness. Englisch in Tool-Steuerung und DoD ist oft robuster – Formulierungen unten sind Copy-Paste, kein Stilbruch zum deutschsprachigen Buch.

Schablone (Copy-Paste)

Ziel: <was am Ende wahr sein soll>
Nicht-Ziel: <explizit out of scope>
Kontext: <Ticket/Branch/Constraints>
Dateien: <pfade wenn bekannt>
Vorgehen: <explore | plan | implement>
Verify: <exakter Command>
Stop: <wann warten / kein push>

Vorher / Nachher

Schwach:

Mach die App besser und fix bugs.

Stark:

Ziel: flaky test_retry_timeout stabil grün (2×).
Nicht-Ziel: kein Retry-Framework-Rewrite, keine API-Änderung.
Vorgehen: erst Repro + Ursache, dann minimaler Fix.
Verify: pytest tests/payments/test_retry.py -q
Stop: kein commit/push ohne mein ok.

Explore vs. Implement

Intent Formulierung
Nur verstehen „Ändere nichts. Keine Edits.“
Plan /plan … + Constraints
Implement „Implement approved plan…“ + Verify
Review „Read-only findings table…“

Tool-Steuerung in Worten

Use explore subagent for research; parent only summarizes.
Do not spawn write-capable subagents while planning.
Prefer @path over wide repo scans when path is known.
First search_tool before any MCP use_tool.

Compact-Hints

/compact Behalte freigegebenen Plan, geänderte Dateien, letzten Test-Fail.
Verwirf Explore-Umwege und gescheiterte Zwischenversuche.

Anti-Patterns

  • „Sei gründlich“ ohne Scope → endloses Lesen
  • Widersprüchliche Regeln in Prompt vs. AGENTS.md
  • Secrets im Prompt „nur kurz“
  • Fünf Features in einer Session
  • Approve ohne Diff

16.3 Session-Hygiene (Ritual)

Zeitpunkt Aktion
Start CWD prüfen, /session-info, Mode lesen
Vor großem Feature /plan
Bei Drift /context → compact mit Hint oder /new
Nach Meilenstein Entscheidung in PR/AGENTS.md
Vor Merge Review-Session oder zweiter Mensch
Ende /quit; optional /flush wenn Memory an

Faustregel: Wenn du denselben Korrekturprompt zum dritten Mal tippst, ist das Fenster oder der Plan kaputt – nicht „das Modell dumm“.

16.4 Team-Rituale

  1. AGENTS.md im Onboarding – erster PR jedes Neuen.
  2. Deny-Baseline committed.
  3. Plan first Label auf architektonischen Tickets.
  4. Verify-Skill statt „tests liefen irgendwie“.
  5. Human push als Default; Bot nur comment/summary.
  6. Quarterly rules review – tote Commands löschen.
  7. Incident blameless: War es YOLO, Trust, MCP, fehlender Scope?

16.5 Systematisches Debuggen

1. Symptom benennen (hängt / falscher Diff / ignoriert Regeln / Auth)
2. Surface? TUI / -p / agent
3. Mode? ask / auto / plan / always-approve (ggf. acceptEdits / dontAsk)
4. grok inspect · /context · /session-info · /doctor
5. CWD und geladene AGENTS.md/Rules
6. Trust / MCP enabled?
7. Deny/Allow Patterns
8. Minimal repro mit engem Prompt

Nicht parallel zehn Hebel drehen – eine Variable pro Versuch.

16.6 Symptom → Fix

Symptom Erste Checks Fix
grok: command not found PATH, neue Shell Installer, which grok
Login-Schleife auth.json, Key-Vorrang grok logout && grok login
Key greift nicht Session-Token aktiv logout, nur XAI_API_KEY
TUI Keys tot Terminal/tmux /doctor, Ctrl+X
Hängt in CI Permission ask --always-approve + Deny
Schreibt trotz „nur lesen“ weicher Prompt / Subagent explizit + explore/read-only
Ignoriert AGENTS.md CWD, gitignore, Länge grok inspect, kürzen
Plan Mode schreibt Repo Kind-Subagent explore/plan only
Parallel-Chaos shared tree worktrees
Kontext drift langes Fenster compact+hint / new
Rewind-Schock uncommitted Git zuerst
MCP fehlt disabled, trust, doctor /mcps, trust
Halluzinierte MCP-Tools kein search_tool Prompt erzwingen
YOLO „ignoriert Deny“ Pattern falsch Syntax, deny testen
Sandbox start fail hooks symlink /doctor, profile
Zu teuer MCP/tools/noise engere Tools, new session
Skill erscheint nicht name/path/disabled grok inspect
Falsches Modell default/CLI /model, grok models
Config „tot“ Precedence Kap. 14 Debug-Flow
Force-push im Diff fehlende Deny Deny + Review
.env im Kontext Read erlaubt Deny Read(**/.env) (+ absolute Forms)

16.7 Häufige Missverständnisse

Glaube Realität
Always-approve = alles erlaubt Deny/Hooks greifen weiter
Plan Mode sperrt Subagents Nein – Kind kann schreiben
Compact speichert alles Wichtige Verlustbehaftet – Hint + Dateien
Memory ersetzt AGENTS.md Nein – Team vs. episodisch
Mehr Tokens = bessere Fixes Oft mehr Drift
IDE braucht andere Regeln Dieselbe Engine, andere UI

16.8 Praxis-Sessions (Meta)

Session A – Prompt-Refactor

Nimm einen schwachen Prompt aus eurem Chat-Verlauf, baue die Schablone 16.2, fahre beide, vergleiche Diff-Größe und Turns.

Session B – Symptom-Drill

Simuliere absichtlich: leeres CWD, YOLO ohne Deny, vages „fix everything“. Protokolliere, was schiefgeht – dann die Fixes aus 16.6.

Session C – Team-Baseline-PR

Ein PR nur mit: AGENTS.md-Kern, Deny-Minimum, optional verify-Skill. Kein Feature-Code.

16.9 Jetzt selbst machen

Jetzt selbst machen

  1. Pinne die Schablone 16.2 neben den Monitor (oder als Snippet).
  2. Laufe einmal /context + /session-info in einer echten Session.
  3. Trage euer Top-3-Symptom aus 16.6 in ein Team-Doc.
  4. Einen Deny und einen AGENTS.md-Command diese Woche schärfen.

16.10 Checkliste „gesunder Agent-Alltag“

  • Scope in jedem Auftrag
  • Mode bewusst
  • Diff gelesen
  • Verify gelaufen
  • Kontext nicht als Deponie
  • Secrets raus
  • Human ownership vor Prod

Was du jetzt kannst

  • Stabile Prompt-Schablonen und Session-Rituale anwenden
  • Symptome systematisch auf Harness-Ursachen mappen
  • Team-Baseline und Debug-Reihenfolge fahren

Nächste Schritte

→ Kapitel 17 – Vergleich mit Claude Code, Codex und Cursor: ehrlich, tabellarisch, wann welches Werkzeug.

Reference in new issue View Git Blame Copy Permalink