Gemini CLI in großen Codebases: Wie viel Kontext ist zu viel? (Praxis-Guide 2026)

Gemini CLI in großen Codebases: Warum „mehr Kontext“ nicht automatisch besser ist

In großen Repositories ist der Reflex verständlich: „Gib dem Modell einfach das ganze Repo, dann versteht es alles.“ In der Praxis ist das oft der schnellste Weg zu schlechteren Ergebnissen. Gerade in Legacy-Projekten, Monorepos oder TYPO3-Installationen mit vielen Extensions führt zu breiter Kontext häufig zu Halluzinationen, unnötigen Annahmen über die Projektstruktur, Performance-Einbrüchen und einem unklaren Scope.

Dieser Guide zeigt, wie Gemini CLI mit Repository-Kontext arbeitet, welche Kontextgrenzen 2026 realistisch sind und wie du in großen Codebases systematisch zu verlässlichen Resultaten kommst. Fokus: pragmatische Workflows für Entwickler, Agenturen und DevOps-orientierte Teams, die produktiv bleiben müssen.

Wie Gemini CLI mit großem Repository-Kontext arbeitet

Gemini CLI ist im Kern ein Interface, das Eingaben (Prompts), ausgewählte Dateien, Diffs und ggf. weitere Artefakte in einen Modell-Request übersetzt. Entscheidend ist: Das Modell „sieht“ nicht dein Repository als Dateisystem, sondern nur den Text, den du ihm tatsächlich übergibst. Alles, was nicht im Request steckt, existiert für das Modell nicht.

In großen Codebases entstehen dabei drei typische Kontext-Schichten:

• Expliziter Kontext: Dateien, Ausschnitte, Diffs, Logs, die du direkt übergibst.
• Impliziter Kontext: Annahmen, die das Modell aus Konventionen ableitet (z. B. typische TYPO3-Strukturen, Composer-Layouts, PSR-Standards).
• Arbeitskontext: Zwischenergebnisse im Dialog (z. B. „Wir ändern nur Extension X“). Dieser Kontext ist fragil, wenn du später zu viel neues Material nachschiebst.

Bei großen Repos ist die zentrale Aufgabe nicht „Kontext maximieren“, sondern Kontext kuratieren: so viel wie nötig, so wenig wie möglich, und immer entlang eines klaren Scopes.

Token-Fenster und Kontextgrenzen 2026: Einordnung ohne Marketing

2026 sind große Kontextfenster in der Praxis verfügbar, aber sie lösen das Problem nicht automatisch. Ein größeres Fenster bedeutet:

• Du kannst mehr Text mitschicken, ohne dass er abgeschnitten wird.
• Du erhöhst aber auch die Wahrscheinlichkeit, dass irrelevante Details das Modell ablenken.
• Du riskierst, dass widersprüchliche Informationen im Repo (Legacy vs. neu) zu falschen Schlussfolgerungen führen.

Wichtig ist die Unterscheidung zwischen Kontextkapazität (wie viel passt rein) und Kontextnutzbarkeit (wie gut kann das Modell daraus robuste Entscheidungen ableiten). In großen Codebases ist die Nutzbarkeit oft der Engpass: Je heterogener das Repo, desto stärker wirkt „Kontext-Rauschen“.

Für Teams bedeutet das: Auch wenn das Token-Fenster groß genug wäre, ist es häufig sinnvoller, in modularen Schritten zu arbeiten und nur die relevanten Teile zu übergeben.

Typische Probleme in großen Projekten (und warum sie passieren)

1) Halluzinationen bei zu breitem Kontext

Halluzinationen sind in großen Repos oft keine „freien Erfindungen“, sondern falsche Verallgemeinerungen. Beispiele:

• Das Modell sieht irgendwo eine alte DDEV-Konfiguration und nimmt an, sie sei aktiv.
• Es findet eine veraltete TYPO3-Version in einem Unterordner und leitet falsche API-Nutzung ab.
• Es erkennt mehrere Build-Systeme (Webpack/Vite/Encore) und „mischt“ Annahmen.

Je mehr widersprüchliches Material du lieferst, desto größer die Chance, dass das Modell eine „Durchschnittsrealität“ konstruiert, die in deinem Projekt nicht existiert.

2) Performance-Einbrüche

Mehr Kontext bedeutet mehr I/O, mehr Vorverarbeitung, größere Requests und längere Antwortzeiten. In CI-nahen Workflows oder bei iterativen Debugging-Loops ist das spürbar. Zusätzlich steigt die Wahrscheinlichkeit, dass du mehrere Iterationen brauchst, weil das Modell sich in Nebenschauplätzen verliert.

3) Unklare Scope-Definition

In Legacy-Projekten ist „Scope“ selten eindeutig. Wenn du dem Modell das ganze Repo gibst und sagst „Mach das schneller“, wird es zwangsläufig raten: Welche Schicht? DB? Cache? Frontend-Bundle? TYPO3-Rendering? Ohne harte Grenzen entstehen Vorschläge, die zwar plausibel klingen, aber nicht zu deinem Ziel passen.

4) Falsche Annahmen über Projektstruktur

Monorepos und Multi-Package-Setups sind prädestiniert für Struktur-Fehlannahmen: Das Modell sieht mehrere composer.json-Dateien, mehrere Extensions, mehrere Entry-Points und entscheidet sich „irgendwie“ für einen. Das führt zu Änderungen am falschen Ort oder zu Vorschlägen, die in deinem Setup nicht builden.

Best Practices: Kontext-Handling als reproduzierbarer Workflow

Schritt 1: Ziel und Scope in einem Satz festnageln

Formuliere vor jeder Analyse einen Scope-Satz, der drei Dinge enthält: Ziel, Ort, Ausschlüsse.

• Ziel: „Bug X beheben“ oder „Refactor Y“
• Ort: „nur Extension site_package“ oder „nur packages/api“
• Ausschlüsse: „keine DB-Migrationen“, „keine UI-Änderungen“

Dieser Satz gehört in jeden Prompt, besonders wenn du später weitere Dateien nachreichst.

Schritt 2: Gezielte Dateiauswahl statt vollständiger Repo-Übergabe

Statt „Repo analysieren“: wähle die kleinste Menge an Dateien, die die Entscheidung ermöglicht. In TYPO3-Projekten sind das häufig:

• composer.json (Root) und ggf. extension-spezifische composer.json
• ext_emconf.php, ext_localconf.php, Configuration/TCA/*
• relevante Controller/Command/Service-Klassen
• TypoScript/TSconfig nur, wenn Rendering/Backend betroffen ist
• Tests, wenn vorhanden (sie definieren Erwartung)

In Monorepos/Multi-Package-Setups: zusätzlich die Paket-Grenzen (z. B. packages/*/composer.json) und die Build-/CI-Definitionen, aber nur, wenn sie für das Problem relevant sind.

Schritt 3: Modulare Analyse in zwei Phasen

Teile die Arbeit bewusst auf:

• Phase A: Orientierung (kleiner Kontext): „Welche Komponenten sind beteiligt? Welche Dateien sind die Entry-Points?“
• Phase B: Umsetzung (zielgerichteter Kontext): „Hier sind genau diese 3 Dateien und ein Diff. Erzeuge eine Änderung, die Tests grün macht.“

So verhinderst du, dass das Modell in Phase B plötzlich neue Hypothesen aus anderen Repo-Bereichen zieht.

Schritt 4: Diff-basierte Änderungen statt „Rewrite“

In großen Codebases ist „Schreib die Datei neu“ riskant: Stil, Nebenbedingungen, Legacy-Workarounds gehen verloren. Diff-basierte Workflows sind stabiler, weil du den Änderungsumfang kontrollierst und Review/CI sauber bleibt.

Praktisch heißt das: Lass dir Änderungen als Patch/Unified Diff ausgeben oder arbeite in kleinen Commits. Wenn du Gemini CLI nutzt, ist der wichtigste Hebel nicht „mehr Kontext“, sondern „kleinere, überprüfbare Änderungen“.

Schritt 5: Minimaler Repro-Case-Ansatz (MRC) erzwingen

Wenn ein Bug nur in „der echten Installation“ auftritt, ist das ein Signal: Der Kontext ist zu groß und zu unklar. Baue einen minimalen Repro-Case:

• kleinste Extension/Package, die das Verhalten zeigt
• kleinste Konfiguration (z. B. eine Route, ein Controller, ein Service)
• ein Test oder ein CLI-Command, das den Fehler reproduziert

Das reduziert Kontext, erhöht Signal und macht die Modellantworten überprüfbar.

Praxisbeispiele: realistische Szenarien und robuste Prompts

Szenario 1: TYPO3-Installation mit mehreren Extensions

Ausgangslage: Ein Legacy-TYPO3-Projekt mit 15 Extensions, davon 3 aktiv entwickelt. Ein Bug tritt beim Speichern eines Datensatzes auf. Typischer Fehler: Das Modell bekommt das ganze Repo, sieht alte TCA-Definitionen und schlägt Änderungen in einer inaktiven Extension vor.

Vorgehen:

• Scope: „Nur Extension vendor/site_package, nur DataHandler-Hook, keine DB-Migration.“
• Kontext: ext_localconf.php, relevante Hook-Klasse, TCA der betroffenen Tabelle, Log-Auszug, ggf. Test oder Repro-Schritte.
• Erst Orientierung: „Welche Hook-Kette ist aktiv?“ Dann Umsetzung: „Ändere nur diese Klasse, liefere Diff.“

Wenn du lokal die relevanten Dateien identifizieren willst, starte mit einer gezielten Suche statt Repo-Upload:

Und prüfe, welche Extensions tatsächlich installiert/aktiv sind (statt Annahmen):

Szenario 2: Monorepo mit Frontend + API + Shared Libraries

Ausgangslage: Ein Monorepo enthält packages/frontend, packages/api, packages/shared. Ein Build bricht in CI, lokal aber nicht. Wenn du dem Modell alles gibst, wird es oft versuchen, „das Build-System zu vereinheitlichen“ oder falsche Paketgrenzen anzunehmen.

Vorgehen:

• Scope: „Nur packages/api, nur TypeScript-Compile-Fehler, keine Änderungen am Frontend.“
• Kontext: tsconfig(s) der API, package.json der API, CI-Log-Ausschnitt, betroffene Datei(en).
• Diff-basiert: „Erzeuge minimalen Fix, der den Fehler behebt, ohne öffentliche API zu ändern.“

Wichtig: CI-Logs sind oft wertvoller als 200 zusätzliche Dateien. Sie sind hochsignalig und reduzieren Spekulation.

Szenario 3: Multi-Package-Setup (Composer) mit Legacy und neuen Paketen

Ausgangslage: Ein TYPO3-Projekt nutzt Composer mit mehreren internen Paketen. Ein neues Paket nutzt moderne PHP-Features, ein altes Paket nicht. Wenn du zu viel Kontext gibst, kann das Modell Features vorschlagen, die in einem Teil des Systems nicht laufen (z. B. wegen PHP-Version, Coding-Standards, Polyfills).

Vorgehen:

• Scope: „Nur packages/legacy-foo, PHP-Kompatibilität beibehalten, keine neuen Dependencies.“
• Kontext: composer.json des Pakets, PHPStan/Psalm-Konfiguration (falls relevant), betroffene Klasse, Fehlermeldung.
• Erzwinge Constraints im Prompt: PHP-Version, keine neuen libs, keine Signaturänderungen.

Entscheidungshilfe: Wann ist großer Kontext sinnvoll – und wann nicht?

Großer Kontext ist sinnvoll, wenn …

• du eine Architektur- oder Abhängigkeitsfrage klären willst (z. B. „Welche Pakete hängen von X ab?“) und du die Ausgabe als Hypothese behandelst, die du verifizierst.
• du Inkonsistenzen finden willst (z. B. doppelte Implementierungen, verteilte Konfiguration), aber danach gezielt in kleinen Schritten änderst.
• du eine Onboarding-Zusammenfassung brauchst, bei der Perfektion weniger kritisch ist als Orientierung.

Großer Kontext führt oft zu schlechteren Ergebnissen, wenn …

• du einen konkreten Bugfix brauchst und der Fehler in einem klaren Modul liegt.
• das Repo heterogen ist (mehrere Generationen, mehrere Build-Systeme, mehrere Framework-Patterns).
• du strikte Constraints hast (keine Breaking Changes, keine neuen Dependencies, bestimmte PHP-/Node-Versionen).
• du unter Zeitdruck iterieren musst (CI rot, Release steht), weil großer Kontext die Iterationszeit erhöht.

Als Faustregel: Je stärker du auf korrekte, reviewbare Diffs angewiesen bist, desto kleiner und präziser sollte der Kontext sein.

Vergleichende Einordnung zu anderen CLI-AI-Tools (ohne Tool-Bashing)

Die meisten CLI-AI-Tools unterscheiden sich weniger in „Magie“, sondern in Workflow-Details: Wie gut unterstützen sie Dateiauswahl, Diff-orientiertes Arbeiten, Wiederholbarkeit und das Einhalten von Scopes. In großen Codebases gewinnt fast immer das Tooling, das dich zu kleinen, überprüfbaren Schritten zwingt oder dich dabei unterstützt.

Gemini CLI ist in solchen Setups dann stark, wenn du es wie ein präzises Werkzeug behandelst: Kontext kuratieren, Hypothesen verifizieren, Änderungen klein halten. Wenn du hingegen „Repo rein, Lösung raus“ erwartest, wirst du in Legacy- und Monorepo-Realitäten häufiger enttäuscht.

Weiterführende interne Artikel (ohne Links im Text)

• Gemini CLI als Alternative zu Claude Code (interner Artikel auf landolsi.de)
• Claude Code vs Gemini CLI (Vergleichsartikel auf landolsi.de)

Checkliste: Kontext-Handling für Gemini CLI in großen Repositories

• Scope-Satz definieren (Ziel, Ort, Ausschlüsse) und in jedem Prompt wiederholen.
• Dateien kuratieren: nur Entry-Points, relevante Konfiguration, betroffene Module.
• Modular arbeiten: Orientierung zuerst, Umsetzung danach.
• Diff-basiert: kleine Änderungen, kleine Commits, CI-freundlich.
• Minimaler Repro-Case: wenn der Bug „zu groß“ wirkt, Kontext reduzieren statt erweitern.
• Verifizieren: Logs, Tests, Build-Schritte als Wahrheit nutzen, nicht Modellannahmen.

Wenn du diese Prinzipien konsequent anwendest, wird „Gemini CLI große Codebase“ nicht zum Risiko, sondern zu einem kontrollierbaren Workflow: weniger Spekulation, mehr reproduzierbare Ergebnisse, bessere Reviews und realistische Erwartungen an AI Kontext Limit und CLI AI Repository Analyse im Jahr 2026.