Communitygithub.com

majiayu000/claude-skill-registry-data

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

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

이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트가 버그 수정 또는 아키텍처 결정을 내리기 전에 체계적인 조사와 근본 원인 분석을 수행하도록 설계되었습니다. 동일한 버그가 2번 이상의 수정 시도 후에도 지속될 때, 복잡한 시스템 상호 작용을 디버깅할 때, 또는 생산 장애를 조사할 때 '연구 모드'로 전환하도록 에이전트를 안내하는 CLAUDE.md 파일의 조사 원칙을 기반으로 합니다. 이 스킬은 에이전트가 명확한 의사 결정 트리, 반복적인 조사 워크플로우(관찰-가설 수립-연구-검증-반영), 그리고 공식 문서, 소스 코드, 실제 데이터와 같은 1차 소스를 읽는 것의 중요성을 강조하는 핵심 원칙을 제공합니다. 또한 경계 검증(분산 시스템에서 코드가 실제로 실행되는 컨텍스트 확인) 및 아키텍처 조사(OWL 기반 관계 분석을 사용한 기술 비교)에 대한 고급 기술을 다루며, AWS CLI, Git, ripgrep, jq, curl과 같은 도구를 사용한 실제 예제를 포함합니다. 이 스킬은 로컬 재현, 실제 데이터 검사, 디버깅을 위한 구조화된 체크리스트 사용을 강조합니다. 잘못된 가정, 유형 불일치, 환경 구성 오류와 같은 일반적인 함정을 방지하는 데 도움이 되며, 첫 번째 수정 시도나 시간이 중요한 장애에는 사용하지 말아야 합니다.

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

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

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

문서

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

다섯 가지 정확성 계층:

  1. 구문: 코드 컴파일 (Python 구문 유효)
  2. 의미: 코드가 주장하는 대로 작동 (논리적 정확성)
  3. 경계: 코드가 필요한 것에 도달 가능 (네트워크, 권한)
  4. 구성: 엔터티 구성이 코드 요구 사항과 일치 (시간 초과, 메모리)
  5. 의도: 사용법이 설계된 목적과 일치 (동기 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 기반 관계 분석 프레임워크 적용

단계:

  1. 비교할 개념 정의

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

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

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

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

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

예제 사용 사례:

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

일반적인 연구 시나리오

시나리오 1: 유형 시스템 불일치

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

연구 단계:

  1. 대상 시스템 문서 읽기

    # PyMySQL 문서
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # 찾을 내용: execute()는 어떤 유형을 허용합니까?
    
  2. 최소 예제 테스트

    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 문자열 성공")
    
  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
    
    # 배포 diff 가져오기
    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-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

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".

관련 스킬