Communitygithub.com

majiayu000/claude-skill-registry-data

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

claude-skill-registry-data 是什麼?

此技能提供了一個結構化的研究方法,用於除錯、調查和架構分析。它整合了從 CLAUDE.md 提煉出的核心原則,以解決那些無法通過快速迭代解決的複雜問題。該技能支援 AWS CLI、Git、ripgrep 等多種工具,並定義了何時使用研究而非反覆嘗試的明確閾值(例如,兩次修復嘗試後)。它所包含的工作流程涵蓋了從生產事故排查、程式碼庫理解,到架構決策和系統邊界驗證等多種場景。此技能適用於 Claude Code 等代理平台,其核心是一個名為「Meta-Loop 轉 Initial-Sensitive」的思維循環模式,引導使用者透過觀察、假設、研究和驗證的步驟來挑戰既有假設,從而找出根本原因。文件中也包含了邊界驗證、本地重現、真實資料檢查等具體原則,以及類型系統錯誤、生產事故和陌生程式碼庫操作等常見情境的逐步指南。

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

在你喜歡的 AI 中提問

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

說明文件

研究技能

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

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


何時使用此技能

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

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

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

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

快速研究決策樹

問題是什麼?
├─ 第一次遇到這個問題?
│  ├─ 是 → 嘗試顯而易見的修復(迭代)
│  └─ 否 → 兩次嘗試後問題依舊?→ 開始研究
│
├─ 生產事故?
│  ├─ 正在影響使用者?→ 先回滾/熱修復,事後再研究
│  └─ 事故後分析?→ 深度研究
│
├─ 需要理解程式碼庫?
│  ├─ 特定函式/模組?→ 閱讀程式碼與測試
│  ├─ 系統架構?→ 追蹤請求流程
│  └─ 歷史背景?→ Git blame + 提交歷史
│
├─ 技術決策?
│  ├─ 閱讀官方文件(非部落格文章)
│  ├─ 比較替代方案(權衡取捨)
│  ├─ 用真實用例製作原型
│  └─ 記錄決策(ADR)
│
└─ API/函式庫整合?
   ├─ 閱讀型別要求(請勿假設)
   ├─ 檢查版本相容性
   ├─ 測試最小範例
   └─ 用實際資料驗證

循環模式:Meta-Loop 轉 Initial-Sensitive

升級觸發條件:

  • /reflect 揭示:「我嘗試了 3 次修復,但都因相同的錯誤而失敗」
  • /trace 輸出在多次嘗試中完全相同
  • 模式:陷入重試循環(執行方式改變,但結果不變)
  • 行動:使用 /hypothesis 來質疑假設(切換至 initial-sensitive 模式)

使用的工具:

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

為何有效:研究技能自然符合 initial-sensitive 循環——你是在質疑假設,而不僅僅是修正執行方式。

請參閱 Thinking Process Architecture - Feedback Loops 以了解結構性概述。


核心研究原則

原則 1:在迭代之前先研究

來自 CLAUDE.md:

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

為何重要:

  • ❌ 迭代:回饋快,但在兩次以上嘗試失敗後很浪費
  • ✅ 研究:前期成本,防止三次以上失敗的部署循環

模式:

嘗試 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 bucket、API 格式?)
  • 實體的屬性是什麼?(Lambda 逾時/記憶體、Aurora 連線限制、預期用途)
  • 我該如何驗證契約?(Terraform 設定、SHOW COLUMNS、測試存取?)

正確性的五個層級:

  1. 語法:程式碼可以編譯(Python 語法有效)
  2. 語意:程式碼做了它聲明要做的事(邏輯正確)
  3. 邊界:程式碼可以觸及其所需的資源(網路、權限)
  4. 設定:實體設定符合程式碼要求(逾時、記憶體)
  5. 意圖:使用方式符合設計目的(同步 Lambda 不用於非同步工作)

何時應用:

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

驗證工作流程:

1. 識別執行邊界(程式碼 → 執行環境、程式碼 → 資料庫、服務 → 服務)
2. 識別實際實體(哪個 Lambda、哪個 Aurora、哪個 S3 bucket)
3. 驗證設定是否符合要求(逾時、記憶體、並發數)
4. 驗證意圖是否符合使用方式(非同步 Lambda 不用於同步 API)
5. 逐步檢視證據層級(程式碼 → 設定 → 執行環境 → 真實情況)

與研究工作流程的整合:

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

參閱:Execution Boundary Checklist 以獲得全面的驗證工作流程

相關原則:

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

架構調查

適用時機:在技術、模式或架構方法之間進行選擇時

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

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

步驟:

  1. 定義要比較的概念

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

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

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

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

參閱:Relationship Analysis Guide 以獲得全面的方法論

用例範例:

  • 「我應該用 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-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".

相關技能