Forschungskompetenz
Tech-Stack: AWS CLI, Git, ripgrep, jq, curl, Browser-DevTools
Quelle: Extrahiert aus den Untersuchungsprinzipien und Debugging-Mustern von CLAUDE.md.
Wann diese Fähigkeit einsetzen
Nutze die Forschungskompetenz, wenn:
- ✓ Derselbe Fehler nach 2+ Korrekturversuchen bestehen bleibt
- ✓ Eine unbekannte Codebasis verstanden werden muss
- ✓ Produktionsvorfälle untersucht werden
- ✓ Architekturentscheidungen getroffen werden
- ✓ Komplexe Systeminteraktionen debuggt werden
- ✓ Eine neue Technologie/Bibliothek erlernt wird
Diese Fähigkeit NICHT nutzen für:
- ✗ Erster Korrekturversuch (zuerst die naheliegende Lösung probieren)
- ✗ Gut verstandene Probleme (einfach beheben)
- ✗ Zeitkritische Vorfälle (zuerst beheben, später untersuchen)
Schnellentscheidungsbaum für die Forschung
Was ist das Problem?
├─ Erstes Auftreten dieses Problems?
│ ├─ JA → Naheliegende Lösung versuchen (Iteration)
│ └─ NEIN → Gleicher Fehler nach 2 Versuchen? → FORSCHUNG
│
├─ Produktionsvorfall?
│ ├─ Betrifft Benutzer JETZT? → Rollback/Hotfix zuerst, später forschen
│ └─ Analyse nach dem Vorfall? → Tiefgehende Forschung
│
├─ Codebasis verstehen?
│ ├─ Bestimmte Funktion/ein bestimmtes Modul? → Code + Tests lesen
│ ├─ Systemarchitektur? → Anfragefluss verfolgen
│ └─ Historischer Kontext? → Git blame + Commit-Verlauf
│
├─ Technologieentscheidung?
│ ├─ Offizielle Dokumentation lesen (keine Blogbeiträge)
│ ├─ Alternativen vergleichen (Kompromisse)
│ ├─ Prototyp mit realem Anwendungsfall erstellen
│ └─ Entscheidung dokumentieren (ADR)
│
└─ API-/Bibliotheksintegration?
├─ Typanforderungen lesen (nicht annehmen)
├─ Versionskompatibilität prüfen
├─ Minimalbeispiel testen
└─ Mit echten Daten verifizieren
Schleifenmuster: Meta-Schleife → Anfangs-sensitiv
Eskalationsauslöser:
/reflectzeigt: „Ich habe 3 Korrekturen versucht, alle sind mit demselben Fehler fehlgeschlagen“/traceAusgabe ist bei allen Versuchen identisch- Muster: Feststecken in einer Wiederholungsschleife (Ausführungen ändern sich, Ergebnis nicht)
- Aktion:
/hypothesisverwenden, um Annahmen zu hinterfragen (zu anfangs-sensitiv wechseln)
Verwendete Werkzeuge:
/observe– Systemverhalten bemerken (was schlägt fehl?)/hypothesis– Alternative Erklärungen generieren (warum könnte es anders fehlschlagen als ich denke?)/research– Hypothesen systematisch testen/validate– Prüfen, ob das neue Verständnis korrekt ist/reflect– Erkenntnisse nach der Untersuchung synthetisieren
Warum das funktioniert: Die Forschungskompetenz passt natürlich zur anfangs-sensitiven Schleife – du hinterfragst Annahmen, nicht nur die Ausführung.
Siehe Thinking Process Architecture - Feedback Loops für eine strukturelle Übersicht.
Kernprinzipien der Forschung
Prinzip 1: Forschung vor Iteration
Aus CLAUDE.md:
„Wenn derselbe Fehler nach 2 Korrekturversuchen bestehen bleibt, HÖRE MIT DER ITERATION AUF und BEGINNE MIT DER FORSCHUNG. Investiere 30-60 Minuten, um die Ursache zu verstehen, anstatt weitere Vermutungen zu deployen.“
Warum das wichtig ist:
- ❌ Iteration: Schnelles Feedback, aber verschwenderisch nach 2+ fehlgeschlagenen Versuchen
- ✅ Forschung: Anfänglicher Aufwand, verhindert 3+ fehlgeschlagene Deployment-Zyklen
Muster:
Versuch 1: Hypothese + Deployment (8 Minuten)
↓ Fehlgeschlagen
Versuch 2: Andere Hypothese + Deployment (8 Minuten)
↓ Fehlgeschlagen
Versuch 3: ❌ STOPP – Keine weitere Vermutung deployen
WECHSEL IN DEN FORSCHUNGSMODUS:
- Spezifikationen/Dokumentation lesen (15 Minuten)
- Echte Daten inspizieren (10 Minuten)
- Lokal reproduzieren (20 Minuten)
- Ursache identifizieren (15 Minuten)
↓ Gesamt: 60 Minuten Forschung
Versuch 3 (mit Ursache): Korrektur deployen (8 Minuten)
✅ Erfolg
Gesamtzeit: 76 Minuten (vs. 120+ Minuten mit blinder Iteration)
Prinzip 2: Primärquellen lesen
Hierarchie der Informationsqualität:
| Quellentyp | Zuverlässigkeit | Wann verwenden |
|---|---|---|
| Offizielle Dokumentation | Höchste | Erster Anlaufpunkt für API-Verhalten, Typanforderungen |
| Quellcode | Sehr hoch | Wenn Dokumentation unklar oder unvollständig ist |
| GitHub Issues | Hoch | Für bekannte Fehler, Grenzfälle, Workarounds |
| Stack Overflow | Mittel | Für häufige Probleme, nach dem Lesen der Dokumentation |
| Blogbeiträge | Niedrig | Für allgemeine Konzepte, keine Implementierungsdetails |
| ChatGPT/KI | Geringste | Nur als Ausgangspunkt, immer verifizieren |
Beispiel: Integration des Typsystems
# ❌ NICHT: Frag ChatGPT „Akzeptiert PyMySQL Dicts für JSON-Spalten?“
# ChatGPT halluziniert möglicherweise oder gibt veraltete Antworten
# ✅ DO: Lies die PyMySQL-Dokumentation
open https://pymysql.readthedocs.io/en/latest/
# ✅ DO: Teste mit Minimalbeispiel
python3 << 'EOF'
import pymysql
import json
# Test: Akzeptiert PyMySQL ein Dict für eine JSON-Spalte?
data = {'key': 'value'}
try:
cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
print("✅ Dict akzeptiert")
except TypeError as e:
print(f"❌ Dict abgelehnt: {e}")
# Alternativ JSON-String versuchen
cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
print("✅ JSON-String akzeptiert")
EOF
Prinzip 3: Lokal reproduzieren
Bevor Korrekturen deployed werden, das Problem lokal reproduzieren.
Vorteile:
- ✅ Schnelle Iteration (Sekunden vs. Minuten)
- ✅ Debugging mit Breakpoints möglich
- ✅ Keine Cloud-Kosten
- ✅ Einfaches Testen von Grenzfällen
Muster:
# Schritt 1: Minimalen Fehlerfall extrahieren
# Statt der gesamten Lambda-Funktion zu testen...
# ❌ SCHLECHT: In AWS deployen, Logs prüfen, wiederholen
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# 30 Sekunden auf CloudWatch-Logs warten...
# ✅ GUT: Lokal reproduzieren
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher
# Exakt derselbe Code wie in der Lambda
fetcher = NewsFetcher()
result = fetcher.fetch_news('NVDA19')
print(result) # Sofortiges Feedback
EOF
Prinzip 4: Echte Daten inspizieren
Nimm keine Datenstruktur an – verifiziere mit tatsächlichen Beispielen.
Häufige Fehler:
- Annahme, dass ein API ein Dict zurückgibt (könnte eine Liste sein)
- Annahme, dass ein Feld existiert (könnte null/fehlend sein)
- Annahme des Typs (könnte String, nicht Integer sein)
Muster:
# ❌ NICHT: Annehmen
# „Die API gibt eine Liste von Tickers zurück“
# ✅ DO: Verifizieren
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json
# Struktur inspizieren:
# - Ist es eine Liste oder ein Dict?
# - Welche Felder sind vorhanden?
# - Welche Typen haben sie?
# - Gibt es Nullwerte?
# - Gibt es verschachtelte Strukturen?
Beispiel: Aurora-Schema-Untersuchung
# Über SSM-Tunnel mit Aurora verbinden
aws ssm start-session \
--target i-1234567890abcdef0 \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'
# Tatsächliches Schema inspizieren (nicht annehmen)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;
-- Tatsächliche Datentypen prüfen
SELECT
symbol,
report_json,
typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G
-- Auf Nullwerte prüfen
SELECT COUNT(*) as total,
SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL
Forschungs-Workflow
Siehe WORKFLOW.md für einen detaillierten, schrittweisen Forschungsprozess.
Untersuchungs-Checkliste
Siehe INVESTIGATION-CHECKLIST.md für eine systematische Debugging-Checkliste.
Grenzverifikation
Wann: Bei der Untersuchung verteilter Systeme (Lambda, Aurora, S3, SQS, Step Functions)
Problem: Code sieht korrekt aus, schlägt aber in der Produktion aufgrund unverifizierter Ausführungsgrenzen fehl
Kritische Fragen:
- WO läuft dieser Code? (Lambda, EC2, lokal?)
- WELCHE Umgebung benötigt er? (Umgebungsvariablen, Netzwerk, Berechtigungen?)
- WELCHE externen Systeme ruft er auf? (Aurora-Schema, S3-Bucket, API-Format?)
- WAS sind die Entitätseigenschaften? (Lambda-Timeout/Speicher, Aurora-Verbindungslimits, beabsichtigte Nutzung)
- WIE verifiziere ich den Vertrag? (Terraform-Konfiguration, SHOW COLUMNS, Testzugriff?)
Fünf Ebenen der Korrektheit:
- Syntax: Code kompiliert (Python-Syntax gültig)
- Semantik: Code tut, was er vorgibt (Logik korrekt)
- Grenze: Code kann erreichen, was er benötigt (Netzwerk, Berechtigungen)
- Konfiguration: Entitätskonfiguration stimmt mit Code-Anforderungen überein (Timeout, Speicher)
- Absicht: Nutzung entspricht dem entworfenen Zweck (synchrone Lambda nicht für asynchrone Arbeit)
Wann anwenden:
- „Code sieht korrekt aus, funktioniert aber nicht“-Fehler
- Mehrere Service-Workflows (Lambda → Aurora → S3)
- Nach 2 fehlgeschlagenen Deployment-Versuchen (Infrastrukturprobleme)
- Bevor zu dem Schluss „Code ist korrekt“ gekommen wird (Ausführungskontext verifizieren)
Verifikations-Workflow:
1. Ausführungsgrenzen identifizieren (Code → Laufzeit, Code → Datenbank, Service → Service)
2. Physische Entitäten identifizieren (WELCHE Lambda, WELCHES Aurora, WELCHER S3-Bucket)
3. Konfiguration mit Anforderungen abgleichen (Timeout, Speicher, Parallelität)
4. Absicht mit Nutzung abgleichen (asynchrone Lambda nicht für synchrone API)
5. Durch Beweisebenen fortschreiten (Code → Konfiguration → Laufzeit → Grundwahrheit)
Integration mit dem Forschungs-Workflow:
- Phase 1 (Beobachten): Grenzbezogenen Fehler bemerken (Timeout, Berechtigungsverweigerung, Schema-Konflikt)
- Phase 2 (Hypothese): Identifizieren, welche Grenze möglicherweise verletzt sein könnte
- Phase 3 (Forschung): Grenzverifikations-Checkliste systematisch anwenden
- Phase 4 (Validieren): Vertrag durch Grundwahrheit verifizieren (tatsächliche Ausführung testen)
Siehe: Execution Boundary Checklist für einen umfassenden Verifikations-Workflow
Verwandte Prinzipien:
- Prinzip Nr. 20 (Ausführungsgrenzendisziplin) – CLAUDE.md
- Prinzip Nr. 2 (Progressive Beweisstärkung) – Durch alle Ebenen verifizieren
- Prinzip Nr. 15 (Infrastruktur-Anwendungs-Vertrag) – Code und Infrastruktur synchronisieren
Architekturuntersuchungen
Wann: Bei der Auswahl zwischen Technologien, Mustern oder Architekturansätzen
Problem: „X vs. Y“-Vergleiche liefern vage „es kommt darauf an“-Antworten ohne strukturierte Analyse
Lösung: Wende OWL-basierten Beziehungsanalyse-Rahmen für systematischen Vergleich an
Schritte:
-
Zu vergleichende Konzepte definieren
- Was ist X? (Definition, Ort, Zweck, Beispiele)
- Was ist Y? (Definition, Ort, Zweck, Beispiele)
-
4 Beziehungstypen anwenden:
- Teil-Ganzes: Ist eines Teil des anderen, oder sind sie gleichrangig?
- Ergänzung: Behandeln sie nicht überlappende Belange, die zusammenwirken?
- Substitution: Kann eines das andere ersetzen? Unter welchen Bedingungen?
- Komposition: Können sie zu einem mehrschichtigen System geschichtet/kombiniert werden?
-
Mit konkreten Beispielen dokumentieren
- Reale Szenarien bereitstellen, keine abstrakte Theorie
- Kompromissanalyse einbeziehen (was gewinnt man vs. was verliert man)
-
Empfehlung basierend auf der Analyse aussprechen
- Auf Beziehungsanalyse, nicht auf Intuition gestützt
- Anti-Patterns einbeziehen, die vermieden werden sollten
Siehe: Relationship Analysis Guide für eine umfassende Methodik
Beispiel-Anwendungsfälle:
- „Sollte ich Redis oder DynamoDB für Caching verwenden?“ → Substitutions- & Kompositionsanalyse anwenden
- „Wie verhalten sich CDN und Anwendungs-Caching zueinander?“ → Ergänzungs- & Kompositionsanalyse anwenden
- „Microservices vs. Monolith?“ → Teil-Ganzes- & Kompromissanalyse anwenden
Häufige Forschungsszenarien
Szenario 1: Typkonflikt
Symptom: Gleicher Fehler nach 2 Versuchen, stiller Fehlschlag
Forschungsschritte:
-
Zielsystem-Dokumentation lesen
# PyMySQL-Dokumentation open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # Suche nach: Welche Typen akzeptiert execute()? -
Minimalbeispiel testen
import pymysql import json # Hypothese testen: Dict vs. JSON-String data = {'key': 'value'} # Test 1: Dict try: cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,)) except TypeError as e: print(f"Dict fehlgeschlagen: {e}") # Test 2: JSON-String cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),)) print("JSON-String erfolgreich") -
Korrektur mit Vertrauen anwenden
# Jetzt WISSEN wir, dass json.dumps() erforderlich ist def store_report(symbol: str, report_json: dict): cursor.execute( "INSERT INTO reports (symbol, report_json) VALUES (%s, %s)", (symbol, json.dumps(report_json)) # In String umwandeln )
Szenario 2: Produktionsvorfall
Symptom: Benutzer melden Fehler, Dashboard zeigt Spike
Forschungsschritte:
-
Triage (< 5 Minuten)
# Fehleranzahl prüfen aws logs filter-log-events \ --log-group-name /aws/lambda/worker \ --start-time $(($(date +%s) - 600))000 \ --filter-pattern "ERROR" \ --query 'length(events)' # Prüfen, wann es begann aws cloudwatch get-metric-statistics \ --namespace AWS/Lambda \ --metric-name Errors \ --dimensions Name=FunctionName,Value=worker \ --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S) \ --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \ --period 60 \ --statistics Sum -
Sofortige Eindämmung (< 10 Minuten)
# Auf vorherige Version zurückrollen CURRENT=$(aws lambda get-alias --function-name worker --name live \ --query 'FunctionVersion' --output text) PREVIOUS=$((CURRENT - 1)) aws lambda update-alias \ --function-name worker \ --name live \ --function-version $PREVIOUS echo "Von v$CURRENT auf v$PREVIOUS zurückgerollt" -
Analyse nach dem Vorfall (30-60 Minuten)
# Beweise sammeln mkdir incident-$(date +%Y%m%d-%H%M%S) cd incident-* # Fehlerlogs exportieren aws logs filter-log-events \ --log-group-name /aws/lambda/worker \ --start-time $INCIDENT_START \ --end-time $INCIDENT_END \ --filter-pattern "ERROR" > errors.json # Metriken exportieren aws cloudwatch get-metric-statistics ... > metrics.json # Deployment-Diff erhalten git diff v$PREVIOUS v$CURRENT > deployment.diff # Analysieren (Ursachenanalyse) # - Was hat sich geändert? # - Was ist fehlgeschlagen? # - Warum ist es fehlgeschlagen? # - Wie kann man es verhindern?
Szenario 3: Unbekannte Codebasis
Aufgabe: Funktion zu einem Modul hinzufügen, das du noch nie gesehen hast
Forschungsschritte:
- Einstiegspunkt finden
# Nach der Hauptfunktion suchen rg "def main"