Research Skill
Tech Stack: AWS CLI, Git, ripgrep, jq, curl, browser DevTools
Quelle: Extrahierte aus CLAUDE.md Untersuchungsprinzipien und Debugging-Muster.
Wann man diese Fähigkeit einsetzen sollte
Verwenden Sie die Research-Fähigkeit, wenn:
- ✓ Derselbe Fehler nach 2+ Korrekturversuchen bestehen bleibt
- ✓ Sie eine unbekannte Codebasis verstehen müssen
- ✓ Sie Produktionsvorfälle untersuchen
- ✓ Sie Architekturentscheidungen treffen
- ✓ Sie komplexe Systeminteraktionen debuggen
- ✓ Sie eine neue Technologie/Bibliothek erlernen
Verwenden Sie diese Fähigkeit NICHT für:
- ✗ Erster Korrekturversuch (versuchen Sie zuerst die offensichtliche Lösung)
- ✗ Gut verstandene Probleme (beheben Sie sie einfach)
- ✗ Zeitkritische Vorfälle (zuerst beheben, später untersuchen)
Schneller Entscheidungsbaum für die Recherche
Was ist das Problem?
├─ Sehen Sie das Problem zum ersten Mal?
│ ├─ JA → Offensichtliche Lösung versuchen (Iteration)
│ └─ NEIN → Gleicher Fehler nach 2 Versuchen? → RECHERCHE
│
├─ Produktionsvorfall?
│ ├─ Betrifft es BENUTZER jetzt? → Zuerst Zurücksetzen/Hotfix, später recherchieren
│ └─ Post-Mortem-Analyse? → Tiefgehende Recherche
│
├─ Codebasis verstehen?
│ ├─ Bestimmte Funktion/ein bestimmtes Modul? → Code + Tests lesen
│ ├─ Systemarchitektur? → Request-Fluss verfolgen
│ └─ Historischer Kontext? → Git Blame + Commit-Verlauf
│
├─ Technologieentscheidung?
│ ├─ Offizielle Dokumentation lesen (keine Blogbeiträge)
│ ├─ Alternativen vergleichen (Kompromisse abwägen)
│ ├─ 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-Loop → Initial-Sensitive
Eskalationsauslöser:
/reflectzeigt: "Ich habe 3 Korrekturen versucht, alle sind mit demselben Fehler fehlgeschlagen"/traceAusgabe ist über Versuche hinweg identisch- Muster: In einer Wiederholungsschleife feststecken (Ausführungen ändern sich, Ergebnis nicht)
- Aktion:
/hypothesisverwenden, um Annahmen zu hinterfragen (auf initial-sensitive umschalten)
Verwendete Werkzeuge:
/observe- Systemverhalten beobachten (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 Research-Fähigkeit passt natürlich zur initial-sensitiven Schleife – Sie hinterfragen Annahmen, nicht nur die Ausführung.
Siehe Thinking Process Architecture - Feedback Loops für eine strukturelle Übersicht.
Grundlegende Forschungsprinzipien
Prinzip 1: Forschen vor Iterieren
Aus CLAUDE.md:
"Wenn derselbe Fehler nach 2 Korrekturversuchen bestehen bleibt, HÖREN Sie mit der Iteration auf und BEGINNEN Sie mit der Recherche. Investieren Sie 30-60 Minuten, um die Ursache zu verstehen, anstatt weitere Vermutungen bereitzustellen."
Warum das wichtig ist:
- ❌ Iteration: Schnelles Feedback, aber verschwenderisch nach 2+ fehlgeschlagenen Versuchen
- ✅ Recherche: Anfängliche Kosten, verhindert 3+ fehlgeschlagene Bereitstellungszyklen
Muster:
Versuch 1: Hypothese + Bereitstellung (8 Minuten)
↓ Fehlgeschlagen
Versuch 2: Andere Hypothese + Bereitstellung (8 Minuten)
↓ Fehlgeschlagen
Versuch 3: ❌ STOP - Keine weitere Vermutung bereitstellen
IN DEN RECHERCHE-MODUS WECHSELN:
- Spezifikationen/Dokumentation lesen (15 Minuten)
- Echte Daten inspizieren (10 Minuten)
- Lokal reproduzieren (20 Minuten)
- Ursache identifizieren (15 Minuten)
↓ Gesamt: 60 Minuten Recherche
Versuch 3 (mit Ursache): Korrektur bereitstellen (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 die Dokumentation unklar oder unvollständig ist |
| GitHub Issues | Hoch | Für bekannte Fehler, Randfälle, Problemumgehungen |
| Stack Overflow | Mittel | Für häufige Probleme, nach dem Lesen der Dokumentation |
| Blogbeiträge | Niedrig | Für allgemeine Konzepte, nicht für Implementierungsdetails |
| ChatGPT/KI | Niedrigste | Nur als Ausgangspunkt, immer verifizieren |
Beispiel: Typ-System-Integration
# ❌ NICHT: ChatGPT fragen "Akzeptiert PyMySQL Dictionaries für JSON-Spalten?"
# ChatGPT halluziniert möglicherweise oder gibt veraltete Antworten
# ✅ DO: PyMySQL-Dokumentation lesen
open https://pymysql.readthedocs.io/en/latest/
# ✅ DO: Mit minimalem Beispiel testen
python3 << 'EOF'
import pymysql
import json
# Test: Akzeptiert PyMySQL ein Dict für die 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}")
# Stattdessen 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 Sie Korrekturen bereitstellen, reproduzieren Sie das Problem lokal.
Vorteile:
- ✅ Schnelle Iteration (Sekunden vs. Minuten)
- ✅ Kann mit Haltepunkten debuggen
- ✅ Keine Cloud-Kosten
- ✅ Kann Randfälle einfach testen
Muster:
# Schritt 1: Minimalen Fehlerfall extrahieren
# Anstatt die gesamte Lambda-Funktion zu testen...
# ❌ SCHLECHT: Nach AWS bereitstellen, 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
Nehmen Sie die Datenform nicht an – verifizieren Sie mit tatsächlichen Beispielen.
Häufige Fehler:
- Annahme, dass API ein Dict zurückgibt (könnte Liste sein)
- Annahme, dass ein Feld existiert (könnte null/fehlend sein)
- Annahme zum Typ (könnte String sein, nicht int)
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 Null-Werte?
# - 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
-- Nach Null-Werten suchen
SELECT COUNT(*) as total,
SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL
Forschungsworkflow
Siehe WORKFLOW.md für einen detaillierten schrittweisen Forschungsprozess.
Untersuchungs-Checkliste
Siehe INVESTIGATION-CHECKLIST.md für eine systematische Debugging-Checkliste.
Grenzüberprüfung
Wann: Bei der Untersuchung verteilter Systeme (Lambda, Aurora, S3, SQS, Step Functions)
Problem: Der Code sieht korrekt aus, schlägt aber in der Produktion aufgrund unverifizierter Ausführungsgrenzen fehl
Kritische Fragen:
- WO wird dieser Code ausgeführt? (Lambda, EC2, lokal?)
- WELCHE Umgebung benötigt er? (Env-Vars, Netzwerk, Berechtigungen?)
- WELCHE externen Systeme ruft er auf? (Aurora-Schema, S3-Bucket, API-Format?)
- WELCHE Entitätseigenschaften gibt es? (Lambda-Timeout/Speicher, Aurora-Verbindungslimits, beabsichtigte Nutzung)
- WIE überprüfe ich den Vertrag? (Terraform-Konfiguration, SHOW COLUMNS, Testzugriff?)
Fünf Ebenen der Korrektheit:
- Syntaktisch: Code kompiliert (Python-Syntax gültig)
- Semantisch: Code tut, was er behauptet (Logik korrekt)
- Grenzen: Code kann erreichen, was er benötigt (Netzwerk, Berechtigungen)
- Konfiguration: Entitätskonfiguration entspricht den Code-Anforderungen (Timeout, Speicher)
- Intentional: Die Nutzung entspricht dem entworfenen Zweck (Synchrone Lambda nicht für asynchrone Arbeit)
Wann anwenden:
- Fehler der Art "Code sieht korrekt aus, funktioniert aber nicht"
- Multi-Service-Workflows (Lambda → Aurora → S3)
- Nach 2 fehlgeschlagenen Bereitstellungsversuchen (Infrastrukturprobleme)
- Bevor man zu dem Schluss kommt "Code ist korrekt" (Ausführungskontext verifizieren)
Überprüfungsworkflow:
1. Ausführungsgrenzen identifizieren (Code → Laufzeit, Code → Datenbank, Dienst → Dienst)
2. Physische Entitäten identifizieren (WELCHE Lambda, WELCHE Aurora, WELCHER S3-Bucket)
3. Konfiguration auf Anforderungen überprüfen (Timeout, Speicher, Parallelität)
4. Absicht auf Nutzung überprüfen (asynchrone Lambda nicht für synchrone API)
5. Durch Beweisebenen fortschreiten (Code → Konfiguration → Laufzeit → Grundwahrheit)
Integration mit dem Forschungsworkflow:
- Phase 1 (Beobachten): Grenzbezogenen Fehler bemerken (Timeout, Zugriff verweigert, Schema-Konflikt)
- Phase 2 (Hypothese): Identifizieren, welche Grenze möglicherweise verletzt wird
- Phase 3 (Forschen): Grenzüberprüfungs-Checkliste systematisch anwenden
- Phase 4 (Validieren): Vertrag durch Grundwahrheit verifizieren (tatsächliche Ausführung testen)
Siehe: Ausführungsgrenzen-Checkliste für einen umfassenden Überprüfungsworkflow
Verwandte Prinzipien:
- Prinzip #20 (Ausführungsgrenzendisziplin) - CLAUDE.md
- Prinzip #2 (Fortschreitende Beweisstärkung) - Durch alle Ebenen verifizieren
- Prinzip #15 (Infrastruktur-Anwendungs-Vertrag) - Code und Infrastruktur synchronisieren
Architekturuntersuchungen
Wann: Bei der Wahl zwischen Technologien, Mustern oder Architekturansätzen
Problem: "X vs. Y"-Vergleiche ergeben vage "es kommt darauf an"-Antworten ohne strukturierte Analyse
Lösung: OWL-basierten Beziehungsanalyse-Rahmen für einen systematischen Vergleich anwenden
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 sich nicht überschneidende 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 einschließen (was man gewinnt vs. verliert)
-
Empfehlung basierend auf der Analyse aussprechen
- Fundiert in der Beziehungsanalyse, nicht der Intuition
- Anti-Patterns einschließen, die vermieden werden sollten
Siehe: Beziehungsanalyse-Leitfaden für eine umfassende Methodik
Beispiel-Anwendungsfälle:
- "Sollte ich Redis oder DynamoDB für Caching verwenden?" → Substitutions- & Kompositionsanalyse anwenden
- "Wie hängen CDN und Anwendungs-Caching zusammen?" → Ergänzungs- & Kompositionsanalyse anwenden
- "Mikroservices vs. Monolith?" → Teil-Ganzes- & Kompromissanalyse anwenden
Häufige Forschungsszenarien
Szenario 1: Typ-System-Konflikt
Symptom: Gleicher Fehler nach 2 Versuchen, stiller Fehlschlag
Forschungsschritte:
-
Zielsystem-Dokumentation lesen
# PyMySQL-Dokumentation open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # Suchen 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 Zuversicht 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 Anstieg
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 Schadensbegrenzung (< 10 Minuten)
# Auf vorherige Version zurücksetzen 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ückgesetzt" -
Post-Mortem-Analyse (30-60 Minuten)
# Beweise sammeln mkdir incident-$(date +%Y%m%d-%H%M%S) cd incident-* # Fehlerprotokolle 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 # Bereitstellungs-Diff abrufen 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 Sie noch nie gesehen haben
Forschungsschritte:
- Einstiegspunkt finden
# Nach main-Funktion suchen rg "def main"