研究技能
技术栈: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、测试访问?)
正确性的五个层次:
- 句法:代码可编译(Python语法有效)
- 语义:代码执行其声称的功能(逻辑正确)
- 边界:代码能够到达其所需的目标(网络、权限)
- 配置:实体配置满足代码要求(超时、内存)
- 意图:使用方式符合设计目的(同步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的关系分析框架进行系统化比较
步骤:
-
定义正在比较的概念
- X是什么?(定义、位置、目的、示例)
- Y是什么?(定义、位置、目的、示例)
-
应用4种关系类型:
- 部分-整体:一个是另一个的一部分,还是它们是同级的?
- 互补:它们是否处理非重叠的关注点,并且可以协同工作?
- 替代:一个可以取代另一个吗?在什么条件下?
- 组合:它们能否被分层/组合成一个多层系统?
-
用具体示例记录
- 提供真实场景,而非抽象理论
- 包括权衡分析(你得到什么 vs 失去什么)
-
基于分析提出建议
- 基于关系分析,而非直觉
- 包括应避免的反模式
参见:关系分析指南 了解全面的方法论
示例用例:
- “我应该使用Redis还是DynamoDB进行缓存?” → 应用替代和组合分析
- “CDN和应用缓存有什么关系?” → 应用互补和组合分析
- “微服务 vs 单体?” → 应用部分-整体和权衡分析
常见研究场景
场景1:类型系统不匹配
症状:相同错误经过2次尝试,静默失败
研究步骤:
-
阅读目标系统文档
# PyMySQL 文档 open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # 查找:execute() 接受什么类型? -
测试最小示例
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字符串成功") -
自信地应用修复
# 现在我们知道了 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:生产事故
症状:用户报告错误,仪表盘显示峰值
研究步骤:
-
分类 (< 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 -
立即缓解 (< 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" -
事后分析 (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:不熟悉的代码库
任务:在从未见过的模块中添加功能
研究步骤:
- 找到入口点
# 搜索main函数 rg "def main"