研究技能
技术栈: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、测试访问?)
正确性的五个层面:
- 语法:代码编译(Python语法有效)
- 语义:代码执行其声称的功能(逻辑正确)
- 边界:代码能够访问所需资源(网络、权限)
- 配置:实体配置符合代码要求(超时、内存)
- 意图:用法符合设计目的(同步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的关系分析框架进行系统性比较
步骤:
-
定义要比较的概念
- X是什么?(定义、位置、目的、示例)
- Y是什么?(定义、位置、目的、示例)
-
应用4种关系类型:
- 部分-整体:一个是另一个的一部分,还是它们是同级的?
- 互补:它们处理不重叠的关切,且协同工作?
- 替代:一个能替代另一个?在什么条件下?
- 组合:它们能被分层/组合成多层系统?
-
用具体示例记录
- 提供真实场景,而非抽象理论
- 包含权衡分析(你得到什么 vs 失去什么)
-
基于分析提出建议
- 基于关系分析,而非直觉
- 包含要避免的反模式
参见:关系分析指南 了解全面的方法论
示例用例:
- “我应该使用Redis还是DynamoDB进行缓存?” → 应用替代和组合分析
- “CDN和应用程序缓存如何关联?” → 应用互补和组合分析
- “微服务 vs 单体?” → 应用部分-整体和权衡分析
常见研究场景
场景1:类型系统不匹配
症状:两次尝试后相同错误,静默失败
研究步骤:
-
阅读目标系统文档
# PyMySQL docs 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 failed: {e}") # 测试2:JSON字符串 cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),)) print("JSON string succeeded") -
自信地应用修复
# 现在我们确定需要 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"
...
[因篇幅原因截断]