Communitygithub.com

majiayu000/claude-skill-registry

Systematische Untersuchung und Ursachenanalyse. Verwende dies beim Debuggen persistenter Probleme, zum Verständnis komplexer Systeme oder vor Architekturentscheidungen.

Was ist claude-skill-registry?

Diese Forschungskompetenz befähigt KI-Agenten wie Claude Code zu einer strukturierten, evidenzbasierten Ursachenanalyse, anstatt blinde Lösungen zu erraten. Sie ist besonders nützlich für Entwickler, die mit hartnäckigen Fehlern, unbekannten Codebasen oder kritischen Systemausfällen konfrontiert sind. Die Implementierung leitet den Agenten durch einen Entscheidungsbaum, um zu erkennen, wann Iteration durch systematische Forschung ersetzt werden muss, und stellt Prinzipien wie die Prüfung von Primärquellen (offizielle Dokumentation, Quellcode), lokale Reproduktion von Fehlern und Inspektion realer Daten bereit. Die Fähigkeit definiert einen Meta-Loop, bei dem der Agent bei wiederholten Fehlschlägen seine Annahmen hinterfragt, sowie spezifische Workflows für die Untersuchung von Produktionsstörungen, Grenzschnittstellenproblemen in verteilten Systemen und Architekturentscheidungen. Sie wird durch Checklisten und konkrete CLI-Befehle für AWS, Git und andere Werkzeuge ergänzt, die eine sofortige Anwendung ermöglichen.

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

In Ihrer bevorzugten KI fragen

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

Dokumentation

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:

  • /reflect zeigt: „Ich habe 3 Korrekturen versucht, alle sind mit demselben Fehler fehlgeschlagen“
  • /trace Ausgabe ist bei allen Versuchen identisch
  • Muster: Feststecken in einer Wiederholungsschleife (Ausführungen ändern sich, Ergebnis nicht)
  • Aktion: /hypothesis verwenden, 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:

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

  1. Syntax: Code kompiliert (Python-Syntax gültig)
  2. Semantik: Code tut, was er vorgibt (Logik korrekt)
  3. Grenze: Code kann erreichen, was er benötigt (Netzwerk, Berechtigungen)
  4. Konfiguration: Entitätskonfiguration stimmt mit Code-Anforderungen überein (Timeout, Speicher)
  5. 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:

  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 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?
  3. Mit konkreten Beispielen dokumentieren

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

  1. Zielsystem-Dokumentation lesen

    # PyMySQL-Dokumentation
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # Suche 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 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:

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

  1. Einstiegspunkt finden
    # Nach der Hauptfunktion 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

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".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

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

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

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

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

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

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

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

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

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

majiayu000/claude-skill-registry

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

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

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

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

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

Verwandte Skills