Communitygithub.com

majiayu000/claude-skill-registry

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

claude-skill-registry 是什么?

该技能为AI助手(如Claude Code)提供了一个结构化的研究方法论,专注于在多次修复尝试失败后停止迭代、转而进行深度调查。它基于CLAUDE.md中的调查原则,强调在部署猜测性修复前,优先阅读官方文档、源码和测试最小示例等一手资料。技能详细描述了何时使用(如相同bug持续、生产事故调查、架构决策前)、何时不应使用(首次尝试修复、时间紧迫的问题),并提供了快速决策树帮助用户选择正确策略。它支持AWS CLI、Git、ripgrep、jq等工具,覆盖从类型系统不匹配到生产事故、再到不熟悉代码库的常见研究场景,并引入了执行边界验证和基于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、浏览器开发者工具

来源:从CLAUDE.md的调查原则和调试模式中提取


何时使用此技能

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

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

请勿使用此技能的场景:

  • ✗ 首次修复尝试(首先尝试显而易见的解决方案)
  • ✗ 已充分理解的问题(直接修复即可)
  • ✗ 时间紧迫的事故(先修复,事后调查)

快速研究决策树

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

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

升级触发器:

  • /reflect 显示:“我尝试了3次修复,都以相同错误失败”
  • /trace 输出在多次尝试中完全相同
  • 模式:陷入重试循环(执行改变,但结果未变)
  • 行动:使用 /hypothesis 质疑假设(切换到初始敏感)

使用的工具:

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

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

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


核心研究原则

原则1:研究先于迭代

来自CLAUDE.md:

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

为什么这很重要:

  • ❌ 迭代:反馈快,但在两次以上失败尝试后浪费
  • ✅ 研究:前期成本,防止三次以上失败的部署周期

模式:

尝试 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 accepted")
except TypeError as e:
    print(f"❌ Dict rejected: {e}")
    # 尝试JSON字符串
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("✅ JSON string accepted")
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

# 检查结构:
# - 是列表还是字典?
# - 存在哪些字段?
# - 它们是什么类型?
# - 有无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不用于异步工作)

何时应用:

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

验证工作流:

1. 识别执行边界(代码→运行时、代码→数据库、服务→服务)
2. 识别物理实体(哪个Lambda、哪个Aurora、哪个S3 bucket)
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 docs
    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 failed: {e}")
    
    # 测试2:JSON字符串
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("JSON string succeeded")
    
  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.

相关技能