研究技能
技術棧:AWS CLI、Git、ripgrep、jq、curl、瀏覽器 DevTools
來源:從 CLAUDE.md 的調查原則與除錯模式中提取。
何時使用此技能
在以下情況使用研究技能:
- ✓ 同一錯誤在兩次修復嘗試後依然存在
- ✓ 需要理解不熟悉的程式碼庫
- ✓ 調查生產事故
- ✓ 做出架構決策
- ✓ 除錯複雜的系統互動
- ✓ 學習新技術/函式庫
請勿在以下情況使用此技能:
- ✗ 第一次修復嘗試(先嘗試顯而易見的解決方案)
- ✗ 已充分理解的問題(直接修復即可)
- ✗ 時間緊迫的事故(先修復,後調查)
快速研究決策樹
問題是什麼?
├─ 第一次看到這個問題?
│ ├─ 是 → 嘗試直接修復(迭代)
│ └─ 否 → 同一錯誤在兩次嘗試後?→ 開始研究
│
├─ 生產事故?
│ ├─ 現在影響用戶?→ 先回滾/熱修復,後研究
│ └─ 事後分析?→ 深入調查
│
├─ 需要理解程式碼庫?
│ ├─ 特定函式/模組?→ 閱讀程式碼 + 測試
│ ├─ 系統架構?→ 追蹤請求流程
│ └─ 歷史脈絡?→ Git blame + 提交歷史
│
├─ 技術決策?
│ ├─ 閱讀官方文件(非部落格文章)
│ ├─ 比較替代方案(權衡取捨)
│ ├─ 用真實用例建立原型
│ └─ 記錄決策(ADR)
│
└─ API/函式庫整合?
├─ 閱讀型別要求(不要假設)
├─ 檢查版本相容性
├─ 測試最小範例
└─ 用實際資料驗證
循環模式:元循環 → 初始敏感
升級觸發條件:
/reflect顯示:「我試了 3 次修復,都以相同的錯誤失敗」/trace輸出每次嘗試都相同- 模式:陷入重試循環(執行方式改變,但結果不變)
- 行動:使用
/hypothesis質疑假設(切換到初始敏感模式)
使用的工具:
/observe- 觀察系統行為(什麼在失敗)/hypothesis- 產生替代解釋(為什麼失敗可能與我想的不同?)/research- 系統性測試假設/validate- 檢查新理解是否正確/reflect- 調查後綜合所學
為何有效:研究技能自然適合初始敏感循環——你在質疑假設,而不只是修正執行方式。
參閱 思考流程架構 - 反饋循環 以了解結構性概述。
核心研究原則
原則 1:先研究再迭代
來自 CLAUDE.md:
「當同一錯誤在兩次修復嘗試後依然存在時,停止迭代並開始研究。投入 30-60 分鐘了解根本原因,而不是部署更多猜測。」
為何重要:
- ❌ 迭代:快速反饋,但在兩次以上失敗嘗試後會造成浪費
- ✅ 研究:前期成本,可避免 3 次以上的失敗部署循環
模式:
嘗試 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 儲存桶、API 格式?)
- 實體屬性是什麼?(Lambda 逾時/記憶體、Aurora 連線限制、預期用途)
- 如何驗證合約?(Terraform 配置、SHOW COLUMNS、測試存取?)
正確性的五個層級:
- 語法層:程式碼可編譯(Python 語法有效)
- 語意層:程式碼達到其聲稱的功能(邏輯正確)
- 邊界層:程式碼可存取其所需的資源(網路、權限)
- 配置層:實體配置符合程式碼需求(逾時、記憶體)
- 意圖層:使用方式符合設計目的(同步 Lambda 不用於非同步工作)
何時應用:
- 「程式碼看似正確但無法運作」的錯誤
- 多服務工作流程(Lambda → Aurora → S3)
- 兩次部署嘗試失敗後(基礎設施問題)
- 在得出「程式碼正確」結論之前(驗證執行環境)
驗證工作流程:
1. 識別執行邊界(程式碼 → 執行環境、程式碼 → 資料庫、服務 → 服務)
2. 識別物理實體(哪個 Lambda、哪個 Aurora、哪個 S3 儲存桶)
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 文件 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"
...