Research Skill
기술 스택: AWS CLI, Git, ripgrep, jq, curl, 브라우저 DevTools
출처: CLAUDE.md 조사 원칙 및 디버깅 패턴에서 추출됨.
이 스킬을 사용해야 할 때
다음과 같은 상황에서 research 스킬을 사용하세요:
- ✓ 동일한 버그가 2번 이상 수정 시도 후에도 지속될 때
- ✓ 익숙하지 않은 코드베이스를 이해해야 할 때
- ✓ 프로덕션 인시던트를 조사할 때
- ✓ 아키텍처 결정을 내릴 때
- ✓ 복잡한 시스템 상호 작용을 디버깅할 때
- ✓ 새로운 기술/라이브러리를 학습할 때
다음 상황에서는 이 스킬을 사용하지 마세요:
- ✗ 첫 번째 수정 시도 (먼저 명백한 해결책을 시도하세요)
- ✗ 잘 이해된 문제 (그냥 수정하세요)
- ✗ 시간이 중요한 인시던트 (먼저 수정하고, 나중에 조사하세요)
빠른 연구 결정 트리
문제가 무엇인가요?
├─ 이 문제를 처음 보시나요?
│ ├─ 예 → 명백한 수정 시도 (반복)
│ └─ 아니오 → 2번 시도 후에도 동일한 버그? → 연구
│
├─ 프로덕션 인시던트인가요?
│ ├─ 지금 사용자에게 영향을 주나요? → 먼저 롤백/핫픽스, 나중에 연구
│ └─ 사후 분석인가요? → 심층 연구
│
├─ 코드베이스를 이해해야 하나요?
│ ├─ 특정 함수/모듈? → 코드 + 테스트 읽기
│ ├─ 시스템 아키텍처? → 요청 흐름 추적
│ └─ 과거 컨텍스트? → Git blame + 커밋 히스토리
│
├─ 기술 결정인가요?
│ ├─ 공식 문서 읽기 (블로그 게시물이 아님)
│ ├─ 대안 비교 (트레이드오프)
│ ├─ 실제 사용 사례로 프로토타이핑
│ └─ 결정 문서화 (ADR)
│
└─ API/라이브러리 통합인가요?
├─ 타입 요구 사항 읽기 (추측하지 마세요)
├─ 버전 호환성 확인
├─ 최소 예제 테스트
└─ 실제 데이터로 검증
루프 패턴: 메타-루프 → 초기-민감
에스컬레이션 트리거:
/reflect가 공개: "3번 수정 시도했지만 모두 동일한 오류로 실패"/trace출력이 시도 간에 동일함- 패턴: 재시도 루프에 갇힘 (실행은 변경되지만 결과는 변경되지 않음)
- 조치:
/hypothesis를 사용하여 가정에 의문 제기 (초기-민감으로 전환)
사용 도구:
/observe- 시스템 동작 관찰 (무엇이 실패하는지)/hypothesis- 대체 설명 생성 (내 생각과 다르게 실패하는 이유는?)/research- 가설을 체계적으로 테스트/validate- 새로운 이해가 올바른지 확인/reflect- 조사 후 학습 내용 종합
이것이 효과적인 이유: Research 스킬은 자연스럽게 초기-민감 루프에 적합합니다—실행을 수정하는 것이 아니라 가정에 의문을 제기하는 것입니다.
구조적 개요는 사고 프로세스 아키텍처 - 피드백 루프를 참조하세요.
핵심 연구 원칙
원칙 1: 반복 전 조사
CLAUDE.md에서:
"동일한 버그가 2번 수정 시도 후에도 지속되면, 반복을 멈추고 조사를 시작하세요. 더 많은 추측을 배포하는 대신 근본 원인을 이해하는 데 30-60분을 투자하세요."
이것이 중요한 이유:
- ❌ 반복: 빠른 피드백이지만, 2번 이상 실패 후에는 낭비적임
- ✅ 연구: 선행 비용이 들지만, 3번 이상의 실패한 배포 주기를 방지함
패턴:
시도 1: 가설 + 배포 (8분)
↓ 실패
시도 2: 다른 가설 + 배포 (8분)
↓ 실패
시도 3: ❌ 중지 - 또 다른 추측을 배포하지 마세요
연구 모드로 전환:
- 사양/문서 읽기 (15분)
- 실제 데이터 검사 (10분)
- 로컬에서 재현 (20분)
- 근본 원인 식별 (15분)
↓ 총: 60분 연구
시도 3 (근본 원인 파악): 수정 배포 (8분)
✅ 성공
총 시간: 76분 (맹목적인 반복으로 120분 이상인 것과 비교)
원칙 2: 1차 출처 읽기
정보 품질 계층:
| 출처 유형 | 신뢰도 | 사용 시기 |
|---|---|---|
| 공식 문서 | 가장 높음 | API 동작, 타입 요구 사항의 첫 번째 접근처 |
| 소스 코드 | 매우 높음 | 문서가 불명확하거나 불완전할 때 |
| GitHub 이슈 | 높음 | 알려진 버그, 엣지 케이스, 해결 방법 |
| Stack Overflow | 중간 | 일반적인 문제, 문서를 읽은 후 |
| 블로그 게시물 | 낮음 | 일반 개념, 구현 세부 사항은 아님 |
| ChatGPT/AI | 가장 낮음 | 시작점으로만 사용, 항상 검증 필요 |
예: 타입 시스템 통합
# ❌ 하지 마세요: ChatGPT에게 "PyMySQL이 JSON 컬럼에 대해 dict를 허용하나요?"라고 묻지 마세요.
# ChatGPT는 환각을 일으키거나 오래된 답변을 줄 수 있습니다.
# ✅ 하세요: PyMySQL 문서 읽기
open https://pymysql.readthedocs.io/en/latest/
# ✅ 하세요: 최소 예제로 테스트
python3 << 'EOF'
import pymysql
import json
# 테스트: PyMySQL이 JSON 컬럼에 대해 dict를 허용하나요?
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
# CloudWatch 로그를 위해 30초 대기...
# ✅ 좋음: 로컬에서 재현
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이거나 없을 수 있음)
- 타입을 가정 (int가 아닌 string일 수 있음)
패턴:
# ❌ 하지 마세요: 추측
# "API가 티커 목록을 반환합니다"
# ✅ 하세요: 확인
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json
# 구조 검사:
# - list인가요 dict인가요?
# - 어떤 필드가 있나요?
# - 어떤 타입인가요?
# - null 값이 있나요?
# - 중첩 구조가 있나요?
예제: Aurora 스키마 조사
# SSM 터널을 통해 Aurora에 연결
aws ssm start-session \
--target i-1234567890abcdef0 \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'
# 실제 스키마 검사 (추측하지 마세요)
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 스키마, S3 버킷, API 형식?)
- 엔터티 속성은 무엇입니까? (Lambda 타임아웃/메모리, Aurora 연결 제한, 의도된 사용법)
- 계약을 어떻게 검증합니까? (Terraform 구성, SHOW COLUMNS, 테스트 액세스?)
다섯 가지 정확성 계층:
- 구문: 코드가 컴파일됨 (Python 구문 유효)
- 의미: 코드가 주장하는 대로 작동함 (로직 올바름)
- 경계: 코드가 필요한 것에 도달할 수 있음 (네트워크, 권한)
- 구성: 엔터티 구성이 코드 요구 사항과 일치함 (타임아웃, 메모리)
- 의도: 사용법이 설계된 목적과 일치함 (동기 Lambda는 비동기 작업에 사용되지 않음)
적용 시기:
- "코드는 올바르게 보이지만 작동하지 않음" 버그
- 다중 서비스 워크플로우 (Lambda → Aurora → S3)
- 2번의 실패한 배포 시도 후 (인프라 문제)
- "코드가 올바르다"고 결론 내리기 전 (실행 컨텍스트 검증)
검증 워크플로우:
1. 실행 경계 식별 (코드 → 런타임, 코드 → 데이터베이스, 서비스 → 서비스)
2. 물리적 엔터티 식별 (어떤 Lambda, 어떤 Aurora, 어떤 S3 버킷)
3. 구성이 요구 사항과 일치하는지 확인 (타임아웃, 메모리, 동시성)
4. 의도가 사용법과 일치하는지 확인 (비동기 Lambda는 동기 API에 사용되지 않음)
5. 증거 계층을 통해 진행 (코드 → 구성 → 런타임 → 실측 데이터)
연구 워크플로우와 통합:
- 1단계 (관찰): 경계 관련 실패 발견 (타임아웃, 권한 거부, 스키마 불일치)
- 2단계 (가설): 위반될 수 있는 경계 식별
- 3단계 (연구): 경계 검증 체크리스트를 체계적으로 적용
- 4단계 (검증): 실측 데이터를 통해 계약 확인 (실제 실행 테스트)
참조: 포괄적인 검증 워크플로우는 실행 경계 체크리스트를 참조하세요.
관련 원칙:
- 원칙 #20 (실행 경계 규율) - CLAUDE.md
- 원칙 #2 (점진적 증거 강화) - 모든 계층을 통해 검증
- 원칙 #15 (인프라-애플리케이션 계약) - 코드와 인프라 동기화
아키텍처 조사
시기: 기술, 패턴 또는 아키텍처 접근 방식 중에서 선택할 때
문제: "X 대 Y" 비교는 구조화된 분석 없이 모호한 "상황에 따라 다름" 답변을 얻음
해결책: 체계적인 비교를 위해 OWL 기반 관계 분석 프레임워크 적용
단계:
-
비교할 개념 정의
- X는 무엇인가? (정의, 위치, 목적, 예제)
- Y는 무엇인가? (정의, 위치, 목적, 예제)
-
4가지 관계 유형 적용:
- 부분-전체: 하나가 다른 것의 일부인가요, 아니면 동등한가요?
- 보완: 함께 작동하는 겹치지 않는 문제를 처리하나요?
- 대체: 하나가 다른 것을 대체할 수 있나요? 어떤 조건에서?
- 구성: 다중 계층 시스템으로 계층화/구성될 수 있나요?
-
구체적인 예제로 문서화
- 추상적 이론이 아닌 실제 시나리오 제공
- 트레이드오프 분석 포함 (얻는 것과 잃는 것)
-
분석을 기반으로 권장 사항 제시
- 직관이 아닌 관계 분석에 근거
- 피해야 할 안티패턴 포함
참조: 포괄적인 방법론은 관계 분석 가이드를 참조하세요.
예제 사용 사례:
- "캐싱을 위해 Redis를 사용해야 할까요, DynamoDB를 사용해야 할까요?" → 대체 및 구성 분석 적용
- "CDN과 애플리케이션 캐싱은 어떤 관계인가요?" → 보완 및 구성 분석 적용
- "마이크로서비스 대 모놀리스?" → 부분-전체 및 트레이드오프 분석 적용
일반적인 연구 시나리오
시나리오 1: 타입 시스템 불일치
증상: 2번 시도 후에도 동일한 오류, 무음 실패
연구 단계:
-
대상 시스템 문서 읽기
# PyMySQL 문서 open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # 찾아야 할 것: execute()는 어떤 타입을 허용하나요? -
최소 예제 테스트
import pymysql import json # 가설 테스트: Dict 대 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"