코드 품질 자동화: Claude Skills로 테스트 작성, 수정, 리뷰하기
Claude Skills를 사용하여 테스트 작성, 테스트 수정, 코드 리뷰를 자동화하는 방법을 알아보세요. 2025년 Claude Code를 사용하는 팀을 위한 실용 가이드와 예제입니다.
수동 코드 품질 작업의 숨겨진 비용
모든 엔지니어링 팀은 각 스프린트에서 필요하지만 결코 완전히 끝나지 않는 작업에 상당한 시간을 할애합니다: 새 코드의 테스트 작성, 리팩토링 후 깨진 테스트 수정, 머지 전 풀 리퀘스트 리뷰. 이것들은 선택적인 활동이 아닙니다 — 팀이 코드베이스에 대한 신뢰를 유지하는 방법입니다. 하지만 수동으로 수행하면 느리고, 일관성이 없으며, 마감이 촉박해지면 가장 먼저 삭제됩니다.
Claude Skills는 이를 직접 해결합니다. 목적에 맞게 구축된 소수의 Skills — write-tests, fix-tests, review-pr, review-local-changes — 가 로컬 머신의 Claude Code 내부에서 실행되는 완전한 코드 품질 자동화 계층을 형성합니다. 함께 사용하면 품질 루프에서 가장 시간이 많이 걸리는 부분을 처리하여, 팀이 실제로 인간의 판단이 필요한 결정에 집중할 수 있게 합니다.
이 가이드는 각 Skill의 작동 방식, 어떻게 함께 맞추는지, 더 높은 품질의 코드를 더 빠르게 출시하는 개발 워크플로에 어떻게 통합하는지를 안내합니다.
write-tests: 대규모 자동 테스트 생성
write-tests Skill은 모든 코드베이스에서 가장 흔한 격차를 해결합니다: 테스트를 작성하는 데 기능 구현만큼 시간이 걸리기 때문에 적절한 테스트 커버리지 없이 출시되는 코드입니다.
/write-tests를 실행하면, Skill이 먼저 테스트 인프라를 탐색합니다. 기존 테스트 설정 파일(jest.config.js, pytest.ini, go.mod 등)을 읽고, 이미 사용 중인 테스팅 패턴을 식별하며, 커버리지를 원하는 파일을 매핑합니다. 이 탐색 단계를 통해 생성된 테스트가 팀이 이미 확립한 규칙에 맞게 됩니다 — 동일한 파일 네이밍, 동일한 어설션 스타일, 동일한 모킹 패턴.
탐색 후, write-tests는 범위 내 각 모듈이나 함수에 대해 테스트를 작성하기 위해 병렬 서브 에이전트를 배포합니다. 에이전트가 병렬로 실행되므로 10개 파일 모듈의 커버리지도 1개 파일과 거의 같은 시간이 걸립니다. 각 에이전트는 테스트 대상 함수의 전체 컨텍스트, 스타일 참조로서의 기존 테스트, 그리고 행복한 경로뿐만 아니라 엣지 케이스, 오류 경로, 경계 조건을 테스트하라는 명시적 지침을 받습니다.
출력은 검토, 실행, 커밋할 수 있는 테스트 파일 세트입니다. Skill은 동작을 발명하지 않습니다; 코드의 실제 함수 시그니처와 독스트링에서 테스트를 도출합니다. 함수의 엣지 동작이 불분명하면, 생성된 테스트가 그 모호성을 노출하며, 이것 자체로 유용한 정보입니다.
# 예시: 특정 모듈에 write-tests 실행
# Claude Code 안에서, Skill 설치 후:
/write-tests src/payments/processor.ts
# Skill이 수행하는 작업:
# 1. 프로젝트 설정에서 Jest + TypeScript 자동 감지
# 2. processor.ts 분석: 함수, 타입, 오류 처리
# 3. 단위 + 통합 테스트를 위한 병렬 에이전트 배포
# 4. src/payments/processor.test.ts 작성
# 5. 모든 새 테스트 통과 확인을 위해 테스트 스위트 실행
레거시 코드베이스를 가진 팀의 경우, write-tests는 커버리지 향상 스프린트 중에 특정 디렉토리에 지정하여 사용하면 특히 유용합니다. 수백 개의 함수에 대해 수동으로 테스트를 작성하는 대신, Skill을 디렉토리에 지정하고, 출력을 검토하고, 반복합니다.
fix-tests: 실패하는 테스트 스위트의 체계적 수리
리팩토링은 테스트를 깨뜨립니다. 의존성 업그레이드도 테스트를 깨뜨립니다. 단순한 이름 변경도 수십 개의 실패하는 스펙으로 이어질 수 있습니다. fix-tests Skill은 정확히 이런 상황을 위해 존재합니다.
Skill은 자동 탐색으로 시작합니다: 테스트 스위트를 실행하고, 모든 실패하는 테스트를 수집하며, 실패 유형별로 그룹화합니다 — 어설션 불일치, 누락된 모킹, 타입 오류, 변경된 API 시그니처. 그룹화가 중요합니다. 대부분의 깨진 테스트 스위트는 소수의 근본 원인을 가지고 있기 때문입니다; 한 유형의 실패를 수정하면 종종 한 번에 여러 테스트가 해결됩니다.
그룹화 후, fix-tests는 각 실패 클래스를 수리하기 위해 병렬 에이전트를 배포합니다. 각 에이전트는 실패하는 테스트, 테스트 출력, 관련 소스 코드를 받습니다. 에이전트의 목표는 프로덕션 코드를 변경하지 않고 테스트를 수정하는 것입니다 — 이 제약은 어설션을 약화시켜 테스트를 통과시키는 대신 시스템의 실제 새 동작을 반영하도록 수리를 강제합니다.
에이전트가 수리를 완료한 후, Skill은 확인을 위해 전체 스위트를 다시 실행합니다. 새로운 실패가 나타나면 (드물지만 수리의 부작용으로 가능), 또 다른 수리 사이클을 실행합니다. 결과는 코드의 현재 상태를 정확하게 반영하는 깨끗한 테스트 스위트입니다.
# 예시: 리팩토링 후 모든 실패하는 테스트 수정
/fix-tests
# 출력 요약 (예시):
# 8개 파일에서 23개의 실패하는 테스트 발견
# 3가지 실패 유형으로 그룹화:
# - API 시그니처 변경 (14개 테스트)
# - 누락된 모킹 설정 (6개 테스트)
# - 타입 어설션 오류 (3개 테스트)
# 3개의 병렬 수리 에이전트 배포 중...
# 스위트 재실행: 0개 실패
# 모든 테스트 통과. 커밋 전에 변경 사항을 검토하세요.
중요한 설계 선택 하나: fix-tests는 스위트를 통과시키기 위해 테스트를 삭제하거나 어설션을 약화하는 것을 거부합니다. 어설션을 변경하지 않으면 정말로 수정할 수 없는 테스트는 조용히 커버리지를 낮추는 대신 사람의 검토를 위해 플래그합니다. 이로 인해 Skill은 사람의 승인을 위한 수리를 제안하는 CI 단계로서 안전하게 실행할 수 있습니다.
playwright-skill을 사용한 브라우저 테스팅
웹 애플리케이션을 구축하는 팀의 경우, 테스트 커버리지는 단위 테스트를 넘어 실제 브라우저 동작까지 확장되어야 합니다. playwright-skill은 Claude Code 워크플로에 브라우저 자동화를 직접 추가합니다.
Playwright Skill은 실행 중인 개발 서버를 자동 감지하여 E2E 테스트 설정에서 가장 답답한 부분을 제거합니다. 사용자 흐름을 설명하면 — 로그인, 설정으로 이동, 기본 설정 변경, 변경이 유지되는지 확인 — Skill이 적절한 셀렉터, 어설션, 재시도 로직을 갖춘 잘 구조화된 Playwright 테스트를 생성합니다. 각 단계에서 스크린샷을 찍어 실패를 쉽게 진단할 수 있습니다.
playwright-skill이 빛나는 곳은 단위 테스트하기 어려운 상호작용을 커버하는 것입니다: 폼 유효성 검사 흐름, 낙관적 UI 업데이트, 세션 만료 처리, 반응형 레이아웃 전환. 이러한 시나리오는 실제 브라우저가 필요하며, Skill이 배관 작업을 처리하여 어설션에 집중할 수 있게 합니다.
review-local-changes와 review-pr: 멀티 에이전트 코드 리뷰
테스트 작성과 유지보수는 품질 이야기의 절반에 불과합니다. 나머지 절반은 프로덕션에 도달하는 코드가 철저히 리뷰되었는지 확인하는 것입니다. 수동 코드 리뷰는 가치가 있지만 팀 규모에 따라 확장성이 떨어집니다; 리뷰어는 사각지대를 발달시키며, 같은 카테고리의 버그가 매년 포스트모템에 나타납니다.
review-local-changes와 review-pr은 Claude Code에 구조화된 멀티 에이전트 코드 리뷰를 도입합니다.
두 Skill 모두 6개의 전문 리뷰어 에이전트를 병렬로 배포하며, 각각 코드 품질의 다른 차원에 집중합니다:
- 보안 리뷰어: OWASP Top 10 취약점, 코드 내 시크릿, 인젝션 위험 확인
- 버그 리뷰어: 논리 오류, off-by-one 조건, null 역참조 식별
- 품질 리뷰어: 네이밍, 구조, DRY 준수, 복잡도 평가
- 계약 리뷰어: API 계약이 문서 및 호출자와 일치하는지 확인
- 테스팅 리뷰어: 커버리지 격차 식별 및 잘못된 이유로 통과하는 테스트
- 히스토리 리뷰어: 이전에 수정된 이슈에 대한 회귀 확인
병렬 실행으로 전체 리뷰가 순차적 리뷰보다 훨씬 짧은 시간에 완료됩니다. 6개 에이전트의 발견 사항은 단일 보고서로 통합되고, 중복 제거되며, 심각도별로 정렬됩니다.
# 예시: review-pr 출력 구조
review:
pr_number: 142
summary: "결제 프로세서 리팩토링 — 심각 3개, 보통 7개, 낮음 12개 발견"
findings:
- severity: critical
agent: security
file: src/payments/processor.ts
line: 87
message: "사용자 입력이 SQL 쿼리에 직접 사용됨 — 파라미터화하세요."
- severity: moderate
agent: testing
file: src/payments/processor.test.ts
line: 34
message: "테스트가 상태 코드만 검증하고 응답 본문은 검증하지 않음 — 부분 커버리지."
- severity: low
agent: quality
file: src/payments/utils.ts
line: 12
message: "`buildPayload` 함수가 45번 줄의 `formatRequest` 로직을 중복함."
review-local-changes는 커밋 전에 사용하도록 설계되었습니다 — 커밋하지 않은 diff에 대해 실행하여 PR에 도달하기 전에 문제를 잡습니다. review-pr은 GitHub CLI와 통합하여 풀 리퀘스트에 직접 인라인 코멘트를 게시하며, 팀이 이미 코드를 리뷰하는 곳에서 발견 사항을 볼 수 있게 합니다.
완전한 품질 워크플로 구축
이 네 가지 Skill은 파이프라인으로 함께 사용할 때 가장 효과적입니다:
- 새 코드 작성 후,
/write-tests를 실행하여 초기 커버리지를 생성합니다. - 리팩토링 후,
/fix-tests를 실행하여 깨진 스펙을 수리합니다. - 커밋 전,
/review-local-changes를 실행하여 이슈를 조기에 잡습니다. - 머지 전,
/review-pr을 실행하여 구조화된 인라인 코멘트를 게시합니다.
이 파이프라인은 외부 CI 설정, 추가 서비스, 에디터 밖으로의 컨텍스트 전환이 필요 없습니다. 모든 단계가 Claude Code 내부에서 실행되며, 모든 단계가 즉시 실행할 수 있는 출력을 생성합니다.
이 워크플로를 일관되게 채택한 팀들은 두 가지 개선을 보고합니다: 프로덕션 리뷰에서 잡히는 버그 감소, PR당 반복적인 피드백에 소비하는 시간 감소. 반복적인 피드백 — "오류 경로에 대한 테스트를 추가하세요", "이 변수 이름이 불분명합니다", "해당 쿼리를 파라미터화하세요" — 가 자동화 계층으로 이동하여, 리뷰어가 아키텍처 결정과 비즈니스 로직에 집중할 수 있게 합니다.
이미 CI를 사용하는 팀의 경우, 이 Skills는 기존 파이프라인을 대체하기보다 보완합니다. 빠른 피드백을 위해 로컬에서 실행하고, CI를 최종 게이트로 유지하세요.
시작하기
이 Skills 중 하나를 설치하려면 Claude Skills Hub에서 .md 파일을 다운로드하여 프로젝트의 .claude/skills/ 디렉토리(또는 모든 프로젝트에서 사용하려면 전역 ~/.claude/skills/ 디렉토리)에 배치하세요. 대부분의 프로젝트에서 추가 설정이 필요하지 않습니다 — Skills가 자동으로 테스트 프레임워크와 코드 구조를 탐색합니다.
커버리지가 낮다면 write-tests부터 시작하고, 실패하는 테스트 백로그가 있다면 fix-tests, 마찰 없이 즉각적인 가치를 원한다면 review-local-changes를 사용하세요. 네 가지 모두 현재 Claude Skills Hub 카탈로그에서 사용할 수 있습니다.
코드 품질은 개발 끝에 있는 체크포인트가 아닙니다 — 작업의 지속적인 속성입니다. 이 Skills는 그 속성을 유지하기 더 쉽게 만듭니다.
