Gradle 빌드 오류 수정

언제 쓰나

Gradle 빌드 오류가 발생할 때 사용합니다

---
description: Android 및 KMP 프로젝트의 Gradle 빌드 오류 수정
---

# Gradle 빌드 수정

Android 및 Kotlin Multiplatform 프로젝트의 Gradle 빌드 및 컴파일 오류를 점진적으로 수정합니다.

## 1단계: 빌드 구성 감지

프로젝트 유형을 식별하고 적절한 빌드를 실행합니다:

| 표시기 | 빌드 명령어 |
|---|---|
| `build.gradle.kts` + `composeApp/` (KMP) | `./gradlew composeApp:compileKotlinMetadata 2>&1` |
| `build.gradle.kts` + `app/` (Android) | `./gradlew app:compileDebugKotlin 2>&1` |
| `settings.gradle.kts` 모듈 포함 | `./gradlew assemble 2>&1` |
| Detekt 설정됨 | `./gradlew detekt 2>&1` |

또한 구성을 위해 `gradle.properties` 및 `local.properties`를 확인합니다.

## 2단계: 오류 구문 분석 및 그룹화

1. 빌드 명령어를 실행하고 출력을 캡처합니다.
2. Kotlin 컴파일 오류와 Gradle 구성 오류를 분리합니다.
3. 모듈 및 파일 경로별로 그룹화합니다.
4. 정렬: 구성 오류를 먼저, 다음으로 종속성 순서에 따라 컴파일 오류를 정렬합니다.

## 3단계: 수정 루프

각 오류에 대해:

1. **파일 읽기** — 오류 줄 주변의 전체 컨텍스트를 확인합니다.
2. **진단** — 일반적인 범주:
   - 누락된 import 또는 확인되지 않은 참조
   - 유형 불일치 또는 호환되지 않는 유형
   - `build.gradle.kts`에 누락된 종속성
   - expect/actual 불일치 (KMP)
   - Compose 컴파일러 오류
3. **최소한으로 수정** — 오류를 해결하는 가장 작은 변경을 적용합니다.
4. **빌드 재실행** — 수정을 확인하고 새 오류가 있는지 확인합니다.
5. **계속 진행** — 다음 오류로 이동합니다.

## 4단계: 가드레일

다음과 같은 경우 사용자에게 중지하고 문의합니다:

- 수정으로 인해 해결된 것보다 더 많은 오류가 발생하는 경우
- 3번의 시도 후에도 동일한 오류가 지속되는 경우
- 오류 해결을 위해 새 종속성을 추가하거나 모듈 구조를 변경해야 하는 경우
- Gradle 동기화 자체가 실패하는 경우(구성 단계 오류)
- 생성된 코드(Room, SQLDelight, KSP)에서 오류가 발생하는 경우

## 5단계: 요약

다음 항목을 보고합니다:

- 수정된 오류 (모듈, 파일, 설명)
- 남은 오류
- 새로 발생한 오류 (0이어야 함)
- 제안된 다음 단계

## 일반적인 Gradle/KMP 수정

| 오류 | 수정 |
|---|---|
| `commonMain`에서 확인되지 않은 참조 | 종속성이 `commonMain.dependencies {}`에 있는지 확인합니다. |
| `actual` 선언 없이 `expect` 선언 | 각 플랫폼 소스 세트에 `actual` 구현을 추가합니다. |
| Compose 컴파일러 버전 불일치 | `libs.versions.toml`에서 Kotlin 및 Compose 컴파일러 버전을 일치시킵니다. |
| 중복 클래스 | `./gradlew dependencies`로 충돌하는 종속성을 확인합니다. |
| KSP 오류 | `./gradlew kspCommonMainKotlinMetadata`를 실행하여 다시 생성합니다. |
| 구성 캐시 문제 | 직렬화할 수 없는 작업 입력을 확인합니다. |

1. 1

   SKILL.md 저장

   아래 버튼으로 복사 → 다음 경로로 저장.

   SKILL.md 복사

   macOSLinuxWindows

   ~/.claude/skills/everything-claude-code-gradle/SKILL.md경로 복사
2. 2

   호출

   Claude Code 채팅창에서 자연어로 부르면 자동 발동:

   예) Gradle 빌드 오류가 발생할 때 사용합니다

   트리거가 안 잡히면 SKILL.md의 description 줄에 더 구체적인 한국어 키워드를 추가해보세요.