Communitygithub.com

majiayu000/claude-skill-registry

체계적인 조사와 근본 원인 분석. 지속적인 문제 디버깅, 복잡한 시스템 이해, 또는 아키텍처 결정을 내리기 전에 사용하세요.

claude-skill-registry란 무엇인가요?

이 스킬은 개발자가 반복적인 디버깅 루프에 갇히거나 복잡한 시스템을 이해해야 할 때, 체계적인 조사 방법을 통해 근본 원인을 찾도록 도와줍니다. AWS CLI, Git, ripgrep, jq, curl, 브라우저 DevTools 같은 도구를 활용하여 문제를 재현하고, 실제 데이터를 검사하며, 공식 문서나 소스 코드 같은 1차 출처를 읽는 원칙을 강조합니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있으며, '반복 전 조사', '1차 출처 읽기', '로컬 재현', '실제 데이터 검사' 같은 핵심 원칙을 따릅니다. 또한 분산 시스템을 조사할 때 필요한 실행 경계 검증 프레임워크와 아키텍처 결정을 위한 관계 분석 방법론도 제공합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/analysis/research-awannaphasch2016-jousef-landing

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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, 테스트 액세스?)

다섯 가지 정확성 계층:

  1. 구문: 코드가 컴파일됨 (Python 구문 유효)
  2. 의미: 코드가 주장하는 대로 작동함 (로직 올바름)
  3. 경계: 코드가 필요한 것에 도달할 수 있음 (네트워크, 권한)
  4. 구성: 엔터티 구성이 코드 요구 사항과 일치함 (타임아웃, 메모리)
  5. 의도: 사용법이 설계된 목적과 일치함 (동기 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 기반 관계 분석 프레임워크 적용

단계:

  1. 비교할 개념 정의

    • X는 무엇인가? (정의, 위치, 목적, 예제)
    • Y는 무엇인가? (정의, 위치, 목적, 예제)
  2. 4가지 관계 유형 적용:

    • 부분-전체: 하나가 다른 것의 일부인가요, 아니면 동등한가요?
    • 보완: 함께 작동하는 겹치지 않는 문제를 처리하나요?
    • 대체: 하나가 다른 것을 대체할 수 있나요? 어떤 조건에서?
    • 구성: 다중 계층 시스템으로 계층화/구성될 수 있나요?
  3. 구체적인 예제로 문서화

    • 추상적 이론이 아닌 실제 시나리오 제공
    • 트레이드오프 분석 포함 (얻는 것과 잃는 것)
  4. 분석을 기반으로 권장 사항 제시

    • 직관이 아닌 관계 분석에 근거
    • 피해야 할 안티패턴 포함

참조: 포괄적인 방법론은 관계 분석 가이드를 참조하세요.

예제 사용 사례:

  • "캐싱을 위해 Redis를 사용해야 할까요, DynamoDB를 사용해야 할까요?" → 대체 및 구성 분석 적용
  • "CDN과 애플리케이션 캐싱은 어떤 관계인가요?" → 보완 및 구성 분석 적용
  • "마이크로서비스 대 모놀리스?" → 부분-전체 및 트레이드오프 분석 적용

일반적인 연구 시나리오

시나리오 1: 타입 시스템 불일치

증상: 2번 시도 후에도 동일한 오류, 무음 실패

연구 단계:

  1. 대상 시스템 문서 읽기

    # PyMySQL 문서
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # 찾아야 할 것: execute()는 어떤 타입을 허용하나요?
    
  2. 최소 예제 테스트

    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 문자열 성공")
    
  3. 자신 있게 수정 적용

    # 이제 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: 프로덕션 인시던트

증상: 사용자가 오류 보고, 대시보드에 스파이크 표시

연구 단계:

  1. 트라이지 (< 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
    
  2. 즉시 완화 (< 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로 롤백됨"
    
  3. 사후 분석 (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: 익숙하지 않은 코드베이스

작업: 본 적 없는 모듈에 기능 추가

연구 단계:

  1. 진입점 찾기
    # main 함수 검색
    rg "def main"
    

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

관련 스킬