Communitygithub.com

Recherche

Systematische Untersuchung und Ursachenanalyse. Verwenden Sie diese Fähigkeit beim Debuggen persistenter Probleme, beim Verständnis komplexer Systeme oder vor architektonischen Entscheidungen.

Was ist Recherche?

Diese Skill unterstützt Entwickler und KI-Agenten bei der systematischen Untersuchung und Ursachenanalyse von komplexen und hartnäckigen Fehlern in Softwareprojekten. Sie ist besonders nützlich, wenn einfache Lösungsversuche fehlschlagen und ein tieferes Verständnis des zugrunde liegenden Problems erforderlich ist. Die Skill fördert einen strukturierten Ansatz, der die Untersuchung vor der Iteration stellt, und betont die Verwendung primärer Quellen wie offizielle Dokumentation und Quellcode gegenüber sekundären Quellen wie Blogbeiträgen oder KI-generierten Antworten. Sie unterstützt eine Vielzahl von Szenarien, darunter die Fehlerbehebung in Produktion, das Verständnis unbekannter Codebasen und das Treffen fundierter Architekturentscheidungen. Die Skill ist plattformunabhängig und kann in Verbindung mit Tools wie AWS CLI, Git, ripgrep, jq und curl eingesetzt werden, um reproduzierbare und verifizierbare Forschungsergebnisse zu erzielen. Sie enthält Entscheidungsbäume, Prinzipien und Checklisten für eine effiziente und gründliche Untersuchung.

Funktioniert mit✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/analysis/research-awannaphasch2016-jousef-landing

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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:

  • /reflect zeigt: "Ich habe 3 Korrekturen versucht, alle sind mit demselben Fehler fehlgeschlagen"
  • /trace Ausgabe ist über Versuche hinweg identisch
  • Muster: In einer Wiederholungsschleife feststecken (Ausführungen ändern sich, Ergebnis nicht)
  • Aktion: /hypothesis verwenden, 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:

QuellentypZuverlässigkeitWann verwenden
Offizielle DokumentationHöchsteErster Anlaufpunkt für API-Verhalten, Typanforderungen
QuellcodeSehr hochWenn die Dokumentation unklar oder unvollständig ist
GitHub IssuesHochFür bekannte Fehler, Randfälle, Problemumgehungen
Stack OverflowMittelFür häufige Probleme, nach dem Lesen der Dokumentation
BlogbeiträgeNiedrigFür allgemeine Konzepte, nicht für Implementierungsdetails
ChatGPT/KINiedrigsteNur 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:

  1. Syntaktisch: Code kompiliert (Python-Syntax gültig)
  2. Semantisch: Code tut, was er behauptet (Logik korrekt)
  3. Grenzen: Code kann erreichen, was er benötigt (Netzwerk, Berechtigungen)
  4. Konfiguration: Entitätskonfiguration entspricht den Code-Anforderungen (Timeout, Speicher)
  5. 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:

  1. Zu vergleichende Konzepte definieren

    • Was ist X? (Definition, Ort, Zweck, Beispiele)
    • Was ist Y? (Definition, Ort, Zweck, Beispiele)
  2. 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?
  3. Mit konkreten Beispielen dokumentieren

    • Reale Szenarien bereitstellen, keine abstrakte Theorie
    • Kompromissanalyse einschließen (was man gewinnt vs. verliert)
  4. 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:

  1. Zielsystem-Dokumentation lesen

    # PyMySQL-Dokumentation
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # Suchen nach: Welche Typen akzeptiert execute()?
    
  2. 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")
    
  3. 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:

  1. 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
    
  2. 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"
    
  3. 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:

  1. Einstiegspunkt finden
    # Nach main-Funktion suchen
    rg "def main"
    

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

Verwandte Skills