Claude Code Skill로 라이브러리 업그레이드 체크리스트 자동 적용하기

라이브러리 버전을 올릴 때마다 확인하는 항목은 거의 매번 똑같은데, 그때그때 프롬프트에 체크리스트를 다시 적어 넣는 게 번거로웠습니다. 슬래시 커맨드처럼 매번 이름을 외워 직접 호출하는 대신, 관련 대화가 나오면 알아서 불러와지는 Claude Code Skill로 이 체크리스트를 고정해봤습니다.

어떤 작업이었나

libs.versions.toml에서 kotlinx-coroutines를 1.6.x에서 1.8.x로 올리는 작업이었습니다. 이 구간에는 kotlinx-coroutines-test의 TestCoroutineDispatcher, TestCoroutineScope가 runTest 기반 API로 대체되면서 옛 테스트 유틸리티가 지속적으로 deprecated 처리된 이력이 있습니다. 버전만 올리고 넘어가면 컴파일은 되지만 경고가 쌓이고, 나중에 완전히 제거되는 시점에 한 번에 몰아서 고쳐야 하는 상황이 됩니다.

이런 라이브러리 업그레이드마다 "버전 diff 확인 → 릴리스 노트에서 breaking change 확인 → deprecated API 사용처 검색 → 테스트 실행"을 매번 프롬프트로 풀어서 설명하고 있었는데, 이 순서 자체를 파일로 고정하기로 했습니다.

AI를 어떻게 활용했나

프로젝트 루트에 .claude/skills/dependency-upgrade-check/SKILL.md를 만들었습니다.

---
name: dependency-upgrade-check
description: build.gradle.kts나 libs.versions.toml에서 라이브러리 버전을 올렸을 때 확인할 체크리스트를 적용한다. "버전 올렸다", "업그레이드했다", "라이브러리 버전 바꿨다" 같은 말이 나오면 사용한다.
---

라이브러리 버전이 바뀐 것을 확인하면 다음 순서로 점검한다.

1. `git diff`로 `libs.versions.toml`에서 어떤 라이브러리가 몇 버전에서 몇 버전으로 바뀌었는지 정리한다.
2. 버전이 마이너 이상 올라갔다면, 해당 라이브러리 이름과 버전 구간을 언급하며 알려진 breaking change나 deprecation이 있는지 알고 있는 범위에서 짚어준다.
3. commonMain, androidMain, iosMain 전체에서 이번에 바뀐 라이브러리의 deprecated API를 사용하는 곳이 있는지 `Grep`으로 찾는다.
4. 찾은 사용처마다 새 API로 바꿀 수 있는지, 바꾼다면 어떤 형태가 되는지 예시를 보여준다.
5. 코드는 직접 고치지 않고, 확인 결과와 권장 조치만 정리해서 보고한다.

이후 슬래시 커맨드를 따로 입력하지 않고 그냥 "코루틴 버전 1.8.1로 올렸는데 문제 없는지 봐줘"라고만 말했습니다. Claude Code가 이 문장을 Skill의 description과 매칭해서 dependency-upgrade-check를 자동으로 불러왔고, 정의해둔 순서대로 점검을 진행했습니다.

commonTest에서 다음과 같은 사용처를 찾아서 알려줬습니다.

// commonTest/kotlin/.../ItemRepositoryTest.kt
private val testDispatcher = TestCoroutineDispatcher()

@Test
fun `아이템을 저장하면 목록에 반영된다`() = testDispatcher.runBlockingTest {
    // ...
}

빌드 로그에는 이런 경고가 남아 있었습니다.

warning: 'TestCoroutineDispatcher()' is deprecated. Use StandardTestDispatcher() instead.
warning: 'fun TestCoroutineScope.runBlockingTest(...)' is deprecated. Use runTest instead.

Skill이 제안한 형태로 바꿨습니다.

@Test
fun `아이템을 저장하면 목록에 반영된다`() = runTest {
    // ...
}

TestCoroutineDispatcher를 명시적으로 주입하던 부분도 runTest가 기본 제공하는 TestScope로 대체되면서 별도 디스패처 선언이 필요 없어졌습니다.

결과와 얻은 팁

description에 실제로 말할 법한 문장("버전 올렸다", "업그레이드했다")을 그대로 넣어두니, 명령어를 외우지 않고 평소 말투로 이야기해도 관련 Skill이 자동으로 걸렸습니다. 슬래시 커맨드는 이름을 정확히 기억해야 하는데, Skill은 그 부담이 적었습니다.
"코드는 직접 고치지 않고 보고만 한다"는 조건을 5번 항목에 넣지 않았다면, 점검하다가 눈에 띈 부분을 바로 고치려고 시도했을 것 같습니다. 라이브러리 업그레이드처럼 여러 파일에 걸쳐 영향이 퍼지는 작업은 먼저 범위를 보고받고 직접 판단해서 고치는 편이 안전합니다.
Skill 안에 점검 순서를 번호로 못박아두니, 어느 날은 breaking change부터 찾고 어느 날은 deprecated API부터 찾는 식으로 순서가 들쭉날쭉해지는 일이 없어졌습니다.
이 방식은 이미 알려진 패턴(deprecated API 치환처럼 정형화된 점검)에는 잘 맞지만, 라이브러리 자체의 동작 변경처럼 코드 검색만으로는 드러나지 않는 문제까지 잡아주지는 않아서 업그레이드 후 테스트 실행은 별도로 챙겨야 했습니다.