Communitygithub.com

majiayu000/claude-skill-registry

系統性調查與根本原因分析。用於除錯持續性問題、理解複雜系統,或在做出架構決策之前。

claude-skill-registry 是什麼?

此技能提供了一個結構化的研究方法,專為開發者與 AI 代理(如 Claude Code、Cursor)設計,用於系統性除錯與根本原因分析。當同一錯誤在兩次修復嘗試後依然存在、需要理解不熟悉的程式碼庫、調查生產事故,或在做出架構決策前,此技能尤為關鍵。它透過一個元循環 → 初始敏感的反饋模式運作,使用 `/observe`、`/hypothesis`、`/research`、`/validate` 和 `/reflect` 等工具,挑戰假設而非盲目迭代。技能強調四個核心原則:先研究再迭代(投入 30-60 分鐘了解根本原因)、閱讀官方文件等第一手資料、在本地重現問題以快速迭代,以及透過實際範例驗證真實資料。此外,它還涵蓋邊界驗證(用於分散式系統)、架構調查的 OWL 關係分析框架,以及處理型別系統不符、生產事故和不熟悉程式碼庫等常見研究情境的具體工作流程。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

研究技能

技術棧:AWS CLI、Git、ripgrep、jq、curl、瀏覽器 DevTools

來源:從 CLAUDE.md 的調查原則與除錯模式中提取。


何時使用此技能

在以下情況使用研究技能:

  • ✓ 同一錯誤在兩次修復嘗試後依然存在
  • ✓ 需要理解不熟悉的程式碼庫
  • ✓ 調查生產事故
  • ✓ 做出架構決策
  • ✓ 除錯複雜的系統互動
  • ✓ 學習新技術/函式庫

請勿在以下情況使用此技能:

  • ✗ 第一次修復嘗試(先嘗試顯而易見的解決方案)
  • ✗ 已充分理解的問題(直接修復即可)
  • ✗ 時間緊迫的事故(先修復,後調查)

快速研究決策樹

問題是什麼?
├─ 第一次看到這個問題?
│  ├─ 是 → 嘗試直接修復(迭代)
│  └─ 否 → 同一錯誤在兩次嘗試後?→ 開始研究
│
├─ 生產事故?
│  ├─ 現在影響用戶?→ 先回滾/熱修復,後研究
│  └─ 事後分析?→ 深入調查
│
├─ 需要理解程式碼庫?
│  ├─ 特定函式/模組?→ 閱讀程式碼 + 測試
│  ├─ 系統架構?→ 追蹤請求流程
│  └─ 歷史脈絡?→ Git blame + 提交歷史
│
├─ 技術決策?
│  ├─ 閱讀官方文件(非部落格文章)
│  ├─ 比較替代方案(權衡取捨)
│  ├─ 用真實用例建立原型
│  └─ 記錄決策(ADR)
│
└─ API/函式庫整合?
   ├─ 閱讀型別要求(不要假設)
   ├─ 檢查版本相容性
   ├─ 測試最小範例
   └─ 用實際資料驗證

循環模式:元循環 → 初始敏感

升級觸發條件:

  • /reflect 顯示:「我試了 3 次修復,都以相同的錯誤失敗」
  • /trace 輸出每次嘗試都相同
  • 模式:陷入重試循環(執行方式改變,但結果不變)
  • 行動:使用 /hypothesis 質疑假設(切換到初始敏感模式)

使用的工具:

  • /observe - 觀察系統行為(什麼在失敗)
  • /hypothesis - 產生替代解釋(為什麼失敗可能與我想的不同?)
  • /research - 系統性測試假設
  • /validate - 檢查新理解是否正確
  • /reflect - 調查後綜合所學

為何有效:研究技能自然適合初始敏感循環——你在質疑假設,而不只是修正執行方式。

參閱 思考流程架構 - 反饋循環 以了解結構性概述。


核心研究原則

原則 1:先研究再迭代

來自 CLAUDE.md:

「當同一錯誤在兩次修復嘗試後依然存在時,停止迭代並開始研究。投入 30-60 分鐘了解根本原因,而不是部署更多猜測。」

為何重要:

  • ❌ 迭代:快速反饋,但在兩次以上失敗嘗試後會造成浪費
  • ✅ 研究:前期成本,可避免 3 次以上的失敗部署循環

模式:

嘗試 1:假設 + 部署(8 分鐘)
  ↓ 失敗
嘗試 2:不同假設 + 部署(8 分鐘)
  ↓ 失敗
嘗試 3:❌ 停止 - 不要部署另一個猜測

切換到研究模式:
  - 閱讀規格/文件(15 分鐘)
  - 檢查真實資料(10 分鐘)
  - 在本機重現問題(20 分鐘)
  - 識別根本原因(15 分鐘)
  ↓ 總計:60 分鐘研究

嘗試 3(基於根本原因):部署修復(8 分鐘)
  ✅ 成功

總時間:76 分鐘(對比盲目迭代的 120+ 分鐘)

原則 2:閱讀第一手資料

資訊品質層級:

來源類型可靠度使用時機
官方文件最高API 行為、型別要求的首選來源
原始碼非常高當文件不清楚或不完整時
GitHub Issues高已知錯誤、邊界情況、解決方案
Stack Overflow中常見問題,在閱讀文件後使用
部落格文章低一般概念,非實作細節
ChatGPT/AI最低僅作為起點,務必驗證

範例:型別系統整合

# ❌ 不要:問 ChatGPT「PyMySQL 接受 dict 作為 JSON 欄位嗎?」
# ChatGPT 可能產生幻覺或給出過時答案

# ✅ 要:閱讀 PyMySQL 文件
open https://pymysql.readthedocs.io/en/latest/

# ✅ 要:用最小範例測試
python3 << 'EOF'
import pymysql
import json

# 測試:PyMySQL 是否接受 dict 作為 JSON 欄位?
data = {'key': 'value'}

try:
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    print("✅ Dict 被接受")
except TypeError as e:
    print(f"❌ Dict 被拒絕:{e}")
    # 嘗試 JSON 字串
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("✅ JSON 字串被接受")
EOF

原則 3:在本機重現問題

在部署修復之前,先在本機重現問題。

優點:

  • ✅ 快速迭代(秒級 vs 分鐘級)
  • ✅ 可用中斷點除錯
  • ✅ 無雲端成本
  • ✅ 可輕鬆測試邊界情況

模式:

# 步驟 1:提取最小失敗案例
# 與其測試整個 Lambda 函式...

# ❌ 不好:部署到 AWS,檢查日誌,重複
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# 等待 30 秒取得 CloudWatch 日誌...

# ✅ 好:在本機重現
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher

# 與 Lambda 完全相同的程式碼
fetcher = NewsFetcher()
result = fetcher.fetch_news('NVDA19')
print(result)  # 立即回饋
EOF

原則 4:檢查真實資料

不要假設資料形狀——用實際範例驗證。

常見錯誤:

  • 假設 API 回傳 dict(可能回傳 list)
  • 假設欄位存在(可能為 null 或缺失)
  • 假定型別(可能是字串而非整數)

模式:

# ❌ 不要:假設
# 「API 會回傳一個股票代碼列表」

# ✅ 要:驗證
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json

# 檢查結構:
# - 是 list 還是 dict?
# - 有哪些欄位?
# - 它們的型別是什麼?
# - 有任何 null 值嗎?
# - 有任何巢狀結構嗎?

範例:Aurora Schema 調查

# 透過 SSM 通道連線到 Aurora
aws ssm start-session \
  --target i-1234567890abcdef0 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'

# 檢查實際 schema(不要假設)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;

-- 檢查實際資料型別
SELECT
  symbol,
  report_json,
  typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G

-- 檢查 null 值
SELECT COUNT(*) as total,
       SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL

研究工作流程

詳細的逐步研究流程請參閱 WORKFLOW.md。


調查檢查清單

系統性除錯檢查清單請參閱 INVESTIGATION-CHECKLIST.md。


邊界驗證

時機:調查分散式系統(Lambda、Aurora、S3、SQS、Step Functions)

問題:程式碼看似正確,但在生產環境中因未驗證的執行邊界而失敗

關鍵問題:

  • 這段程式碼在哪裡執行?(Lambda、EC2、本機?)
  • 它需要什麼環境?(環境變數、網路、權限?)
  • 它呼叫了哪些外部系統?(Aurora schema、S3 儲存桶、API 格式?)
  • 實體屬性是什麼?(Lambda 逾時/記憶體、Aurora 連線限制、預期用途)
  • 如何驗證合約?(Terraform 配置、SHOW COLUMNS、測試存取?)

正確性的五個層級:

  1. 語法層:程式碼可編譯(Python 語法有效)
  2. 語意層:程式碼達到其聲稱的功能(邏輯正確)
  3. 邊界層:程式碼可存取其所需的資源(網路、權限)
  4. 配置層:實體配置符合程式碼需求(逾時、記憶體)
  5. 意圖層:使用方式符合設計目的(同步 Lambda 不用於非同步工作)

何時應用:

  • 「程式碼看似正確但無法運作」的錯誤
  • 多服務工作流程(Lambda → Aurora → S3)
  • 兩次部署嘗試失敗後(基礎設施問題)
  • 在得出「程式碼正確」結論之前(驗證執行環境)

驗證工作流程:

1. 識別執行邊界(程式碼 → 執行環境、程式碼 → 資料庫、服務 → 服務)
2. 識別物理實體(哪個 Lambda、哪個 Aurora、哪個 S3 儲存桶)
3. 驗證配置是否符合需求(逾時、記憶體、並發)
4. 驗證意圖是否符合使用方式(非同步 Lambda 不用於同步 API)
5. 透過證據層級推進(程式碼 → 配置 → 執行環境 → 實際狀況)

與研究工作流程的整合:

  • 階段 1(觀察):注意與邊界相關的失敗(逾時、權限拒絕、schema 不符)
  • 階段 2(假設):識別可能被違反的邊界
  • 階段 3(研究):系統性應用邊界驗證檢查清單
  • 階段 4(驗證):透過實際狀況驗證合約(測試實際執行)

參閱:執行邊界檢查清單 以了解完整的驗證工作流程

相關原則:

  • 原則 #20(執行邊界紀律)- CLAUDE.md
  • 原則 #2(漸進式證據強化)- 透過所有層級驗證
  • 原則 #15(基礎設施-應用程式合約)- 同步程式碼和基礎設施

架構調查

時機:在技術、模式或架構方法之間做選擇

問題:「X vs Y」的比較往往得到模糊的「視情況而定」答案,缺乏結構化分析

解決方案:應用基於 OWL 的關係分析框架,進行系統性比較

步驟:

  1. 定義要比較的概念

    • 什麼是 X?(定義、位置、目的、範例)
    • 什麼是 Y?(定義、位置、目的、範例)
  2. 應用 4 種關係類型:

    • 部分-整體:一個是另一個的一部分,還是它們是同級的?
    • 互補:它們是否處理不重疊但協同工作的關注點?
    • 替代:一個可以取代另一個嗎?在什麼條件下?
    • 組合:它們可以分層/組合成多層系統嗎?
  3. 用具體範例記錄

    • 提供真實情境,而非抽象理論
    • 包含權衡分析(你獲得了什麼 vs 失去了什麼)
  4. 基於分析提出建議

    • 基於關係分析,而非直覺
    • 包含應避免的反模式

參閱:關係分析指南 以了解完整方法論

範例用例:

  • 「我應該使用 Redis 還是 DynamoDB 做快取?」 → 應用替代與組合分析
  • 「CDN 和應用程式快取如何關聯?」 → 應用互補與組合分析
  • 「微服務 vs 單體式?」 → 應用部分-整體與權衡分析

常見研究情境

情境 1:型別系統不符

症狀:兩次嘗試後出現相同錯誤,靜默失敗

研究步驟:

  1. 閱讀目標系統文件

    # PyMySQL 文件
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # 尋找:execute() 接受哪些型別?
    
  2. 測試最小範例

    import pymysql
    import json
    
    # 測試假設:Dict vs JSON 字串
    data = {'key': 'value'}
    
    # 測試 1:Dict
    try:
        cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    except TypeError as e:
        print(f"Dict 失敗:{e}")
    
    # 測試 2:JSON 字串
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("JSON 字串成功")
    
  3. 有信心地套用修復

    # 現在我們知道 json.dumps() 是必須的
    def store_report(symbol: str, report_json: dict):
        cursor.execute(
            "INSERT INTO reports (symbol, report_json) VALUES (%s, %s)",
            (symbol, json.dumps(report_json))  # 轉換為字串
        )
    

情境 2:生產事故

症狀:用戶回報錯誤,儀表板顯示峰值

研究步驟:

  1. 分類(< 5 分鐘)

    # 檢查錯誤數量
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $(($(date +%s) - 600))000 \
      --filter-pattern "ERROR" \
      --query 'length(events)'
    
    # 檢查何時開始
    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. 立即減輕影響(< 10 分鐘)

    # 回滾到先前的版本
    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 "已從 v$CURRENT 回滾到 v$PREVIOUS"
    
  3. 事後分析(30-60 分鐘)

    # 收集證據
    mkdir incident-$(date +%Y%m%d-%H%M%S)
    cd incident-*
    
    # 匯出錯誤日誌
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $INCIDENT_START \
      --end-time $INCIDENT_END \
      --filter-pattern "ERROR" > errors.json
    
    # 匯出指標
    aws cloudwatch get-metric-statistics ... > metrics.json
    
    # 取得部署差異
    git diff v$PREVIOUS v$CURRENT > deployment.diff
    
    # 分析(根本原因分析)
    # - 什麼變了?
    # - 什麼失敗了?
    # - 為什麼失敗?
    # - 如何預防?
    

情境 3:不熟悉的程式碼庫

任務:為從未見過的模組新增功能

研究步驟:

  1. 尋找進入點
    # 搜尋 main 函式
    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.

相關技能