[TIL] Claude Code 커스텀 스킬로 반복 작업 자동화하기

매번 비슷한 요청을 타이핑하고 있었다 

"테스트 실패 원인 분석해줘 allure-results 확인하고 
에러 메시지 파싱해서 로케이터 문제인지 확인하고"

복붙하기도 귀찮고 매번 미묘하게 다르게 써서 결과도 들쭉날쭉 

💡 해결: 커스텀 스킬 

Claude Code 의 슬래시 명령어(/commit, /review 등)를 직접 만들 수 있다 

.claude/commands/ 폴더에 마크다운 파일 추가하면 끝 

📁 디렉토리 구조 

.claude/
└── commands/
    ├── coverage_check.md
    ├── create_e2e_test.md
    ├── find_e2e_test.md
    ├── health_check.md
    ├── init_plan_mode.md
    ├── lint.md
    ├── mcp_login.md
    ├── quality_gate.md
    ├── run_suite.md
    └── update_issue.md

📝 스킬 파일 형식

---
name: health_check
description: 로케이터 헬스체크 및 자동 복구
allowed-tools:
  - Bash
  - Read
  - Edit
  - mcp__playwright__*
---

# 로케이터 헬스체크

모든 로케이터를 **실제 페이지에서 검증**하고
깨진 로케이터를 **자동으로 수정**한다

## 워크플로우

1. 로케이터 수집
   └─ pages/locators/*.py 파일 파싱

2. 페이지별 검증
   ├─ Playwright 로 페이지 접속
   ├─ 각 로케이터 존재 여부 확인
   └─ 결과 기록

3. 자동 수정 (--fix 옵션)
   └─ Self-Healing 실행

핵심 포인트

1. frontmatter (---): name, description, allowed-tools 정의
2. allowed-tools: 필요한 도구만 허용 (보안 + 성능)
3. 워크플로우 명시: Claude 가 따라갈 단계별 지시
4. $ARGUMENTS: 사용자 입력을 받을 수 있음

🛠️ 내가 만든 스킬들

몇개만 정리한다

1. /health_check - 로케이터 검증 + 자동 복구

문제: UI 변경되면 테스트가 깨지는데, 어떤 로케이터가 문제인지 찾기 귀찮음

해결: 모든 로케이터를 실제 페이지에서 검증하고 깨진 것만 리포트

# 전체 헬스체크
/health_check

# 특정 페이지만
/health_check login

# 자동 수정 포함
/health_check --fix

워크플로우

1. pages/locators/*.py 파일 파싱 → 로케이터 목록 수집
2. Playwright 로 페이지 접속 → 각 로케이터 존재 여부 확인
3. 결과 분류:
   - ✅ OK: 정상
   - ⚠️ Changed: 요소는 있지만 속성 변경
   - ❌ Missing: 못 찾음
   - 🔄 Multiple: 여러 개 매칭
4. --fix 옵션 시 Self-Healing 자동 실행

출력 예시

# 로케이터 헬스체크 결과

## 요약
| 페이지 | 총 개수 | ✅ OK | ⚠️ Changed | ❌ Missing |
|--------|---------|-------|------------|------------|
| Login  | 10      | 8     | 1          | 1          |
| Bench  | 25      | 20    | 3          | 2          |

## 문제 로케이터
| 파일 | 변수명 | 기존 | 제안 |
|------|--------|------|------|
| login_locators.py | LOGIN_BUTTON | `로그인` | `로그인하기` |

2. /find_e2e_test - 페이지 요소 분석 + 테스트 항목 도출

문제: 새 페이지에 테스트 추가할 때 뭘 테스트해야 하는지 정리가 안 됨

해결: URL 주면 Playwright 로 접속해서 테스트 항목 자동 도출

# URL 로 페이지 분석
/find_e2e_test https://app.example.com/dashboard

워크플로우

1. Playwright MCP 로 페이지 접속
2. browser_snapshot으로 요소 분석
3. 인터랙티브 요소 파악:
   - 버튼, 입력 필드, 링크
   - 모달/팝업, 토스트
   - 로딩 상태
4. 테스트 시나리오 도출:
   - Happy Path
   - Edge Case
   - Error Path

출력 예시

# 대시보드 테스트 항목

## 테스트 대상 요소

### 1. 네비게이션
| 요소 | 타입 | 테스트 항목 | 우선순위 |
|------|------|-------------|----------|
| 프로젝트 버튼 | button | 선택 시 프로젝트 목록 | P1 |
| 설정 링크 | link | 설정 페이지 이동 | P2 |

## 추천 테스트 시나리오
1. **로그인 후 대시보드 진입**: 정상 접근 확인
2. **빈 프로젝트 상태**: 안내 메시지 표시

3. /debug_failure - 테스트 실패 원인 분석

문제: 테스트 실패하면 로그 뒤지고, Trace 열고, 코드 찾고 시간 오래 걸림

해결: 실패 정보 자동 수집 → 원인 분류 → 수정 제안

# 특정 테스트 분석
/debug_failure test_login_01

# 최근 실패 자동 탐색
/debug_failure

워크플로우

1. 실패 정보 수집
   ├─ allure-results/*.json 에서 실패 테스트 찾기
   ├─ artifacts/에서 Trace, Screenshot 찾기
   └─ 에러 메시지 파싱

2. 원인 분류
   ├─ 🔴 Locator 문제: 요소를 찾지 못함
   ├─ ⏱️ 타이밍 문제: Timeout, 로딩 지연
   ├─ 🌐 서버 에러: API 실패, 500 에러
   └─ 🐍 코드 버그: AssertionError, TypeError

3. 수정 적용
   ├─ Locator → pages/locators/ 수정
   ├─ 타이밍 → wait 로직 추가
   └─ 서버 에러 → 버그 리포트 생성

4. 재실행 검증 (2회 통과 확인)

규칙:

• ❌ assert 제거 금지
• ❌ skip 처리 금지
• ❌ timeout 무한 증가 금지
• ✅ 근본 원인만 수정

4. /lint - 코드 품질 검사 + 자동 수정

문제: flake8, black 수동으로 돌리기 귀찮음

해결: 한 번에 검사 + 자동 수정

# 검사만
/lint

# 자동 수정
/lint --fix

5. /run_suite - 테스트 실행 + 리포트 + 배포

문제: 테스트 돌리고, 리포트 만들고, 배포하고, Slack 알리고 단계가 많음

해결: 원클릭 파이프라인

# Smoke 테스트만
/run_suite smoke

# 전체 테스트 + 배포 + Slack 알림
/run_suite all --deploy --slack

# Headless 모드
/run_suite all --headless --deploy

워크플로우

1. 테스트 실행
   └─ pytest + allure 결과 수집

2. 리포트 생성
   ├─ Allure HTML 리포트
   └─ Failure Report (실패 시)

3. 배포 (--deploy)
   └─ Netlify 자동 배포

4. 알림 (--slack)
   └─ Slack 결과 메시지

출력 예시

# 테스트 스위트 실행 결과

## 결과 요약
| 상태 | 개수 | 비율 |
|------|------|------|
| ✅ Passed | 15 | 75% |
| ❌ Failed | 3 | 15% |
| ⏭️ Skipped | 2 | 10% |

## 리포트 링크
- Allure: https://your-project-report.netlify.app/allure-report/
- Failure: https://your-project-report.netlify.app/failure_report.html

6. /init_plan_mode - Plan Mode 체크리스트 자동 생성

문제: 작업 시작할 때 체크리스트 만들고 관련 docs 찾기 귀찮음

해결: 체크리스트 자동 생성 + 관련 docs 안내

/init_plan_mode

워크플로우

1. bash scripts/generate_checklist.sh 실행
2. 관련 docs 파악 및 요약
3. 작업 계획 수립 도움

참조 문서 자동 매핑:
| 작업 유형 | 참조 docs |
|----------|-----------|
| Locator 작성 | docs/LOCATOR_STRATEGY.md |
| Page Object | docs/POM_STRUCTURE.md |
| Step 정의 | docs/TEST_CASE_DESIGN_GUIDE.md |

7. /create_e2e_test - E2E 테스트 코드 생성 + 실행

문제: 테스트 코드 작성할 때 Feature → Locator → Page Object → Step 순서 지키기 번거로움

해결: 요구사항 주면 전체 코드 자동 생성

# 테스트 요구사항 전달
/create_e2e_test "로그인 후 대시보드 진입 확인"

워크플로우

1. 컨텍스트 파악
   └─ docs 읽기 + 기존 코드 패턴 확인

2. 페이지 검증
   └─ Playwright MCP 로 실제 요소 확인 (추측 금지!)

3. 코드 작성 (순서 중요)
   ├─ 1) Feature 파일 (tests/features/)
   ├─ 2) Locator 정의 (pages/locators/)
   ├─ 3) Page Object (pages/)
   └─ 4) Step 구현 (tests/step_definitions/)

4. 테스트 실행
   └─ 2회 연속 통과 확인

규칙:

• Locator 는 locators 파일에만 (하드코딩 금지)
• Step 에는 Page Object 메서드 호출만 (로직 금지)
• Assertion 2개 이상 필수
• time.sleep() 금지

🐣 스킬 작성 팁

1. allowed-tools 최소화

필요한 도구만 허용하면:

• 보안: 의도치 않은 파일 수정 방지
• 성능: 사용 가능한 도구만 로드

# 분석만 하는 스킬
allowed-tools:
  - Read
  - Glob
  - Grep

# 수정도 하는 스킬
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash

2. 워크플로우 명시

Claude 가 순서대로 따라갈 수 있게 단계별로 작성

## 워크플로우

1. 컨텍스트 파악
   └─ 관련 docs 읽기

2. 분석 수행
   └─ 파일 검색 및 파싱

3. 결과 출력
   └─ 마크다운 형식으로 정리

3. 출력 형식 정의

일관된 결과물을 위해 출력 형식 명시

## 출력 형식

# [제목]

## 요약
- ...

## 상세
| 항목 | 내용 |
|------|------|

4. 규칙 명시

하면 안 되는 것, 해야 하는 것 명확히

## 규칙

- ❌ 추측으로 코드 작성 금지
- ❌ 테스트 품질 훼손 금지
- ✅ 실제 검증 후 수정
- ✅ 2회 테스트 통과 확인

5. $ARGUMENTS 활용

사용자 입력을 받아서 동적으로 처리

## 입력

`$ARGUMENTS`로 다음을 받음:
- 페이지명: `login`, `bench`
- 옵션: `--fix`, `--deploy`
- 예시: `login --fix`

🎯 결론

반복되는 프롬프트 → 스킬로 만들어두면 /명령어 한 방에 끝

실제로 /health_check --fix 치면
로케이터 수집 → 검증 → 수정까지 알아서 해준다

굿ㅋ