코딩 중 에러/삽질을 만났을 때 컨텍스트를 자동 수집하고 분석하는 스킬. "에러 감지", "트러블 감지", "삽질 기록", "trouble detect" 요청에 사용.
| 구분 | 항목 | 설명 | 기본값 |
|---|---|---|---|
| 선택 | 트러블 리포트 경로 | 트러블슈팅 리포트가 저장될 디렉토리 경로 (프로젝트 루트 기준 상대경로) | docs/troubles/ |
에러나 삽질을 만났을 때, 문제 해결에 필요한 컨텍스트를 자동으로 수집하고 구조화한다.
/my-trouble-detect
또는 자연어로: "에러 감지해줘", "삽질 기록", "트러블 감지", "trouble detect"
| 상황 | 예시 |
|---|---|
| 빌드가 안 될 때 | npm run build 했는데 에러가 쏟아질 때 |
| 실행은 되는데 에러가 날 때 | 화면에 빨간 에러 메시지가 뜰 때 |
| 원하는대로 안 될 때 |
| 버튼을 눌렀는데 아무 반응이 없을 때 |
| 배포가 실패할 때 | Vercel/Netlify 배포 후 에러가 날 때 |
| 같은 문제가 반복될 때 | "이거 전에도 겪은 것 같은데..." 싶을 때 |
나: /my-trouble-detect
Claude: "어떤 문제를 만났나요?" → "빌드/컴파일 에러" 선택
Claude: "에러 메시지를 붙여넣어 주세요"
나: "Module not found: Can't resolve '@/components/Button'"
Claude: (자동으로 에러 로그, git 변경사항, 환경 정보를 수집)
Claude: (트러블슈팅 리포트 출력)
Claude: "다음에 뭘 할까요?" → "바로 해결 시도" + "리포트 저장" 선택
{설정의 트러블 리포트 경로}/YYYY-MM-DD-에러-키워드.md에 저장됩니다.
저장된 리포트가 쌓이면, 다음에 비슷한 에러가 발생했을 때 과거 기록과 비교 분석합니다.
┌─────────────────────────────────────────────────────┐
│ Step 1: 문제 상황 파악 │
│ ─ 사용자에게 어떤 문제인지 간단히 확인 │
├─────────────────────────────────────────────────────┤
│ Step 2: 3개 컨텍스트 수집 에이전트 (병렬 실행) │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ error-log │ git-context │ env-context │ │
│ │ (에러 로그) │ (변경 이력) │ (환경 정보) │ │
│ └──────────────┴──────────────┴──────────────┘ │
├─────────────────────────────────────────────────────┤
│ Step 3: 패턴 분석 에이전트 (순차 실행) │
│ ─ pattern-analyzer: 과거 트러블과 비교 분석 │
├─────────────────────────────────────────────────────┤
│ Step 4: 트러블슈팅 리포트 출력 │
│ ─ 수집된 컨텍스트 + 분석 결과를 구조화 │
├─────────────────────────────────────────────────────┤
│ Step 5: 다음 행동 선택 │
│ ─ 바로 해결 시도 / Notion에 기록 / 리포트만 저장 │
└─────────────────────────────────────────────────────┘
사용자에게 AskUserQuestion으로 문제 상황을 확인한다.
"어떤 문제를 만났나요?"
- 빌드/컴파일 에러 (npm run build, tsc 등이 실패)
- 런타임 에러 (실행은 되지만 에러 발생)
- 예상과 다른 동작 (에러는 없지만 원하는대로 안 됨)
- 배포 에러 (Vercel, Netlify 등 배포 실패)
- 직접 설명
사용자의 답변을 trouble_type 변수로 저장한다.
추가로 묻는다:
"에러 메시지나 증상을 붙여넣어 주세요. (없으면 '없음')"
사용자의 답변을 error_message 변수로 저장한다.
Step 1의 정보를 바탕으로 3개의 수집 에이전트를 동시에 실행한다. 각 에이전트는 Task 도구(subagent_type: "general-purpose")로 병렬 호출한다.
trouble_type이 빌드 에러인 경우: npm run build 2>&1 | tail -50 실행하여 최신 빌드 에러 확인trouble_type이 런타임 에러인 경우: 브라우저 콘솔 에러는 사용자가 붙여넣은 error_message를 분석trouble_type이 배포 에러인 경우: 배포 로그 파일이 있는지 확인error_message에서 핵심 에러 메시지, 파일 경로, 라인 번호를 추출🔴 에러 로그
- 에러 유형: (빌드/런타임/동작/배포)
- 핵심 메시지: (추출된 에러 메시지)
- 관련 파일: (파일 경로:라인 번호)
- 전체 로그: (축약된 로그)
git diff --stat — 현재 변경된 파일 목록git diff — 실제 변경 내용 (너무 길면 변경된 파일별 요약)git log --oneline -5 — 최근 5개 커밋git stash list — 숨겨둔 변경사항이 있는지📂 변경 이력
- 변경 파일: (개수)개
- 최근 커밋: (최근 커밋 메시지)
- 주요 변경: (가장 많이 바뀐 파일과 변경 요약)
- 의심 포인트: (에러와 관련될 수 있는 변경)
node -v, npm -v — Node.js 버전package.json에서 주요 의존성 버전 (react, next, vite, typescript 등)tsconfig.json의 주요 설정.env 파일 존재 여부 (내용은 수집하지 않음, 보안)⚙️ 환경 정보
- Node: (버전), npm: (버전)
- 주요 의존성: (패키지명@버전)
- TypeScript 설정: (주요 설정값)
- 환경 변수: .env 파일 (있음/없음)
Step 2의 3개 에이전트 결과를 모두 받은 뒤, 패턴 분석을 실행한다.
{설정의 트러블 리포트 경로} 폴더가 있으면 과거 기록과 비교하여 반복 패턴 감지🔍 분석 결과
- 추정 원인: (1순위 원인)
- 근거: (왜 그렇게 판단했는지)
- 관련 변경: (git diff에서 관련된 부분)
- 반복 패턴: (과거에 비슷한 문제가 있었는지)
- 해결 방향: (시도해볼 수 있는 접근법 1~2가지)
모든 에이전트 결과를 하나의 리포트로 통합한다.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚨 트러블슈팅 리포트
날짜: (오늘 날짜)
프로젝트: (프로젝트명)
문제 유형: (trouble_type)
🔴 에러 요약
- (error-log 결과 요약)
📂 최근 변경 사항
- (git-context 결과 요약)
⚙️ 환경
- (env-context 결과 요약)
🔍 분석
- 추정 원인: (pattern-analyzer 결과)
- 해결 방향: (제안된 접근법)
📌 반복 패턴 알림
- (과거 비슷한 문제가 있었으면 여기에 표시)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
리포트를 터미널에 출력한다.
리포트를 보여준 뒤, AskUserQuestion으로 다음 행동을 선택받는다.
{설정의 트러블 리포트 경로}/YYYY-MM-DD-제목.md로 저장 (나중에 패턴 분석에 활용){설정의 트러블 리포트 경로} 폴더에 마크다운 파일로 저장한다docs/troubles/YYYY-MM-DD-에러-키워드.md:
# (에러 키워드)
- **날짜**: (오늘 날짜)
- **문제 유형**: (trouble_type)
- **해결 여부**: 미해결 / 해결
## 에러 내용
(에러 로그 요약)
## 원인
(분석된 원인)
## 해결 방법
(적용한 해결법 또는 "미해결")
## 배운 점
(이 에러에서 배운 것)