Research Skill (연구 스킬)
기술 스택: AWS CLI, Git, ripgrep, jq, curl, 브라우저 DevTools
출처: CLAUDE.md 조사 원칙 및 디버깅 패턴에서 추출
이 스킬을 사용해야 할 때
다음과 같은 경우 연구 스킬을 사용하세요.
- ✓ 동일한 버그가 2번 이상의 수정 시도 후에도 지속될 때
- ✓ 익숙하지 않은 코드베이스를 이해해야 할 때
- ✓ 생산 장애를 조사할 때
- ✓ 아키텍처 결정을 내릴 때
- ✓ 복잡한 시스템 상호 작용을 디버깅할 때
- ✓ 새로운 기술/라이브러리를 배울 때
다음과 같은 경우에는 이 스킬을 사용하지 마세요.
- ✗ 첫 번째 수정 시도 (먼저 명백한 해결책을 시도하세요)
- ✗ 잘 이해된 문제 (그냥 고치세요)
- ✗ 시간이 중요한 장애 (먼저 고치고, 나중에 조사하세요)
빠른 연구 의사 결정 트리
문제가 무엇인가요?
├─ 이 문제를 처음 보시나요?
│ ├─ 예 → 명백한 수정 시도 (반복)
│ └─ 아니오 → 2번 시도 후 동일한 버그? → 연구
│
├─ 생산 장애인가요?
│ ├─ 지금 사용자에게 영향을 미치나요? → 롤백/핫픽스 우선, 연구는 나중에
│ └─ 사후 분석인가요? → 심층 연구
│
├─ 코드베이스를 이해해야 하나요?
│ ├─ 특정 함수/모듈? → 코드 + 테스트 읽기
│ ├─ 시스템 아키텍처? → 요청 흐름 추적
│ └─ 과거 컨텍스트? → Git blame + 커밋 기록
│
├─ 기술 결정인가요?
│ ├─ 공식 문서 읽기 (블로그 게시물 말고)
│ ├─ 대안 비교 (트레이드오프)
│ ├─ 실제 사용 사례로 프로토타입
│ └─ 결정 문서화 (ADR)
│
└─ API/라이브러리 통합인가요?
├─ 유형 요구 사항 읽기 (추정하지 마세요)
├─ 버전 호환성 확인
├─ 최소 예제 테스트
└─ 실제 데이터로 검증
루프 패턴: 메타-루프 → 초기-민감
에스컬레이션 트리거:
/reflect가 다음을 드러냅니다: "3번의 수정을 시도했지만 모두 동일한 오류로 실패했습니다"/trace출력이 모든 시도에서 동일합니다- 패턴: 재시도 루프에 갇힘 (실행은 변경되지만 결과는 변경되지 않음)
- 조치:
/hypothesis를 사용하여 가정에 의문 제기 (초기-민감으로 전환)
사용되는 도구:
/observe- 시스템 동작 관찰 (무엇이 실패하는지)/hypothesis- 대체 설명 생성 (내가 생각하는 것과 다르게 실패하는 이유는 무엇일까?)/research- 가설을 체계적으로 테스트/validate- 새로운 이해가 올바른지 확인/reflect- 조사 후 학습 내용 종합
이것이 효과적인 이유: 연구 스킬은 자연스럽게 초기-민감 루프에 적합합니다. 실행을 고치는 것이 아니라 가정에 의문을 제기하는 것입니다.
구조적 개요는 Thinking Process Architecture - Feedback Loops를 참조하세요.
핵심 연구 원칙
원칙 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: 로컬에서 재현
수정을 배포하기 전에 로컬에서 문제를 재현하세요.
이점:
- ✅ 빠른 반복 (초 vs 분)
- ✅ 중단점으로 디버그 가능
- ✅ 클라우드 비용 없음
- ✅ 에지 케이스 쉽게 테스트 가능
패턴:
# 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/누락될 수 있음)
- 유형을 가정 (string이 아닌 int일 수 있음)
패턴:
# ❌ 하지 마세요: 가정
# "API가 ticker 목록을 반환합니다"
# ✅ 하세요: 확인
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. 의도가 사용법과 일치하는지 확인 (동기 API에 비동기 Lambda 사용 안 함)
5. 증거 계층을 통해 진행 (코드 → 구성 → 런타임 → 실측 자료)
연구 워크플로우와 통합:
- 1단계 (관찰): 경계 관련 실패 발견 (시간 초과, 권한 거부, 스키마 불일치)
- 2단계 (가설): 위반될 수 있는 경계 식별
- 3단계 (연구): 경계 검증 체크리스트를 체계적으로 적용
- 4단계 (검증): 실측 자료를 통해 계약 확인 (실제 실행 테스트)
참조: 포괄적인 검증 워크플로우는 실행 경계 체크리스트를 참조하세요.
관련 원칙:
- 원칙 #20 (실행 경계 규율) - CLAUDE.md
- 원칙 #2 (점진적 증거 강화) - 모든 계층을 통해 검증
- 원칙 #15 (인프라-애플리케이션 계약) - 코드와 인프라 동기화
아키텍처 조사
시기: 기술, 패턴 또는 아키텍처 접근 방식 중에서 선택할 때
문제: "X vs Y" 비교는 구조화된 분석 없이 모호한 "상황에 따라 다릅니다"라는 답변을 얻습니다.
해결책: 체계적인 비교를 위해 OWL 기반 관계 분석 프레임워크 적용
단계:
-
비교할 개념 정의
- X는 무엇인가? (정의, 위치, 목적, 예시)
- Y는 무엇인가? (정의, 위치, 목적, 예시)
-
4가지 관계 유형 적용:
- 부분-전체: 하나가 다른 것의 일부인가, 아니면 동등한가?
- 보완: 함께 작동하는 겹치지 않는 문제를 처리하는가?
- 대체: 하나가 다른 것을 대체할 수 있는가? 어떤 조건에서?
- 구성: 다중 계층 시스템으로 계층화/구성될 수 있는가?
-
구체적인 예제로 문서화
- 추상적인 이론이 아닌 실제 시나리오 제공
- 트레이드오프 분석 포함 (얻는 것과 잃는 것)
-
분석에 기반한 권장 사항 제시
- 직관이 아닌 관계 분석에 근거
- 피해야 할 안티 패턴 포함
참조: 포괄적인 방법론은 관계 분석 가이드를 참조하세요.
예제 사용 사례:
- "캐싱을 위해 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 # 배포 diff 가져오기 git diff v$PREVIOUS v$CURRENT > deployment.diff # 분석 (근본 원인 분석) # - 무엇이 변경되었나요? # - 무엇이 실패했나요? # - 왜 실패했나요? # - 어떻게 예방할 수 있나요?
시나리오 3: 익숙하지 않은 코드베이스
작업: 본 적 없는 모듈에 기능 추가
연구 단계:
- 진입점 찾기
# main 함수 검색 rg "def main"
...