Communitygithub.com

majiayu000/claude-skill-registry-data

系统化调查与根因分析。用于调试持续性问题、理解复杂系统,或在做出架构决策之前。

claude-skill-registry-data 是什么?

此技能提供了一套完整的调查与根因分析方法论,专为AI Agent(如Claude Code、Cursor等)设计。其核心价值在于避免盲目迭代:当同一错误连续2次修复失败后,强制切换至研究模式,通过阅读官方文档、本地复现、审查真实数据等系统性原则,从根本上解决问题。该技能支持AWS CLI、Git、ripgrep、jq、curl等工具,并特别关注分布式系统的边界验证(执行环境、配置、权限等)。文档中包含了详细的决策树、调查工作流和常见场景案例(如生产事故处理、不熟悉代码库探索等),能够显著提升Agent诊断复杂技术问题的效率与准确性。

兼容平台✓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 中的调查原则和调试模式提取。


何时使用此技能

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

  • ✓ 同一错误经过两次修复尝试后仍然存在
  • ✓ 需要理解不熟悉的代码库
  • ✓ 调查生产事故
  • ✓ 做出架构决策
  • ✓ 调试复杂的系统交互
  • ✓ 学习新技术/库

请勿在以下情况使用此技能:

  • ✗ 首次修复尝试(先尝试显而易见的解决方案)
  • ✗ 理解透彻的问题(直接修复)
  • ✗ 时间关键型事故(先修复,后调查)

快速研究决策树

问题是什么?
├─ 第一次见到这个问题?
│  ├─ 是 → 尝试显而易见的修复(迭代)
│  └─ 否 → 经过2次尝试后同一错误?→ 研究
│
├─ 生产事故?
│  ├─ 当前正在影响用户?→ 先回滚/热修复,后研究
│  └─ 事后分析?→ 深入研究
│
├─ 需要理解代码库?
│  ├─ 特定函数/模块?→ 阅读代码 + 测试
│  ├─ 系统架构?→ 追踪请求流
│  └─ 历史背景?→ Git blame + 提交历史
│
├─ 技术决策?
│  ├─ 阅读官方文档(而非博客文章)
│  ├─ 比较替代方案(权衡利弊)
│  ├─ 使用实际用例进行原型验证
│  └─ 记录决策(架构决策记录 ADR)
│
└─ API/库集成?
   ├─ 阅读类型要求(不要假设)
   ├─ 检查版本兼容性
   ├─ 测试最小示例
   └─ 使用实际数据验证

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

升级触发器:

  • /reflect 揭示:“我已经尝试了3次修复,都因相同的错误失败”
  • /trace 输出在多次尝试中相同
  • 模式:陷入重试循环(执行改变,结果不变)
  • 操作:使用 /hypothesis 质疑假设(切换到初始敏感)

使用的工具:

  • /observe - 注意系统行为(什么在失败)
  • /hypothesis - 生成替代解释(为什么它可能以我预期不同的方式失败?)
  • /research - 系统化地测试假设
  • /validate - 检查新的理解是否正确
  • /reflect - 在调查后综合所学

为何有效:研究技能自然地契合初始敏感循环——你在质疑假设,而不仅仅是在修正执行。

有关结构概览,请参见思考过程架构 - 反馈循环。


核心研究原则

原则1:先研究,后迭代

来自 CLAUDE.md:

“当同一错误经过2次修复尝试后仍然存在时,停止迭代,开始研究。投入30-60分钟理解根本原因,而不是部署更多猜测。”

为何重要:

  • ❌ 迭代:反馈快,但在2+次失败尝试后变得浪费
  • ✅ 研究:前期成本,防止3+次失败的部署循环

模式:

尝试 1:假设 + 部署(8分钟)
  ↓ 失败
尝试 2:不同假设 + 部署(8分钟)
  ↓ 失败
尝试 3:❌ 停止 - 不要再部署猜测

切换到研究模式:
  - 阅读规格/文档(15分钟)
  - 检查真实数据(10分钟)
  - 本地复现(20分钟)
  - 识别根本原因(15分钟)
  ↓ 总计:60分钟研究

尝试 3(基于根本原因):部署修复(8分钟)
  ✅ 成功

总时间:76分钟(对比盲目迭代的120+分钟)

原则2:阅读原始资料

信息质量层次:

来源类型可靠性何时使用
官方文档最高了解API行为、类型要求的第一站
源代码非常高当文档不清晰或不完整时
GitHub Issues高已知Bug、边界情况、临时解决方案
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:本地复现

在部署修复之前,先在本地复现问题。

益处:

  • ✅ 快速迭代(秒级而非分钟级)
  • ✅ 可以使用断点调试
  • ✅ 没有云成本
  • ✅ 可以轻松测试边界情况

模式:

# 步骤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/缺失)
  • 假设类型(可能是string而非int)

模式:

# ❌ 不要:假设
# “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不用于异步工作)

何时应用:

  • “代码看起来正确但不起作用”的Bug
  • 多服务工作流(Lambda → Aurora → S3)
  • 2次部署尝试后失败(基础设施问题)
  • 在得出结论“代码是正确的”之前(验证执行上下文)

验证工作流:

1. 识别执行边界(代码 → 运行时, 代码 → 数据库, 服务 → 服务)
2. 识别物理实体(哪个Lambda、哪个Aurora、哪个S3存储桶)
3. 验证配置是否满足要求(超时、内存、并发)
4. 验证意图是否匹配用途(异步Lambda不用于同步API)
5. 逐层推进证据(代码 → 配置 → 运行时 → 真实情况)

与研究 work flow 的集成:

  • 阶段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:类型系统不匹配

症状:相同错误经过2次尝试,静默失败

研究步骤:

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

相关技能