Spotless를 활용한 팀 코드 컨벤션 자동화하기

프로젝트에서 팀원 간의 코드 스타일을 일관되게 유지하는 것은 쉽지 않습니다. 특히 협업 환경에서는 들여쓰기, 공백, import 정렬 등 사소한 코드 스타일 차이로 인해 리뷰 효율이 떨어지거나 커밋 히스토리가 어지러워지기 쉽습니다.

이 글에서는 Kotlin 프로젝트에 Spotless와 Ktlint를 적용하여 코드 스타일을 자동화하고, Git Hook과 CI까지 연동하는 방법을 설명합니다. 팀의 컨벤션을 강제할 수 있는 환경을 구축해 코드 품질과 협업 효율을 함께 높이는 것이 목적입니다.

1. Ktlint란?

Ktlint는 Kotlin 공식 스타일 가이드를 기반으로 하는 코드 린터(Linter)이자 포맷터입니다. 들여쓰기, 공백, 줄 끝 개행, import 순서 등 다양한 코드 스타일 규칙을 검사하고, 일부는 자동으로 수정해줍니다.

Spotless는 Kotlin 포맷터로 Ktlint를 내부적으로 사용하며, Ktlint 설정값을 그대로 적용할 수 있습니다. 예를 들어 다음과 같은 스타일 규칙을 강제할 수 있습니다:

• 공백과 들여쓰기 스타일 (예: indent_size 4, indent_style space)
• 마지막 줄 개행 여부 (insert_final_newline)
• trailing comma 허용 여부 (ij_kotlin_allow_trailing_comma)
• 와일드카드 import 금지 등

2. Spotless란?

Spotless는 다양한 언어의 코드 포맷터를 Gradle에 통합할 수 있는 플러그인입니다. Kotlin에서는 내부적으로 Ktlint를 실행하여 포맷팅을 수행합니다.

Gradle 프로젝트에 Spotless를 적용하면 ./gradlew spotlessApply, ./gradlew spotlessCheck 명령어로 코드 스타일을 통일할 수 있으며, 빌드 시 자동으로 스타일을 점검하거나 수정할 수 있도록 구성할 수 있습니다.

3. Gradle 설정 방법

먼저 루트 build.gradle.kts에 플러그인을 추가합니다.

plugins {
    id("com.diffplug.spotless") version "6.25.0"
}

이후 subprojects 블록에서 Spotless 설정을 적용합니다.

subprojects {
    plugins.apply("com.diffplug.spotless")

    configure<com.diffplug.gradle.spotless.SpotlessExtension> {
        val commonEditorConfig = mapOf(
            "charset" to "utf-8",
            "end_of_line" to "lf",
            "insert_final_newline" to true,
            "trim_trailing_whitespace" to true,
            "indent_style" to "space",
            "indent_size" to 4,
            "ij_kotlin_allow_trailing_comma" to true,
            "ij_kotlin_allow_trailing_comma_on_call_site" to true
        )

        kotlin {
            target("**/*.kt")
            targetExclude("$buildDir/**/*.kt", "bin/**/*.kt")
            ktlint("1.5.0").editorConfigOverride(commonEditorConfig)
            indentWithSpaces()
            endWithNewline()
        }

        kotlinGradle {
            target("**/*.gradle.kts")
            ktlint("1.5.0").editorConfigOverride(commonEditorConfig)
            indentWithSpaces()
            endWithNewline()
        }

        format("misc") {
            target("**/*.yml", "**/*.yaml", "**/*.json")
            trimTrailingWhitespace()
            indentWithSpaces(4)
            endWithNewline()
        }
    }
}

4. 주요 명령어

Spotless 설정 후에는 다음 명령어를 통해 코드 스타일을 적용하거나 검사할 수 있습니다.

• ./gradlew spotlessApply: 코드 자동 포맷을 수행합니다. 지정된 스타일 규칙에 따라 파일이 수정됩니다.
• ./gradlew spotlessCheck: 코드 스타일 위반 여부만 검사합니다. CI 환경에서 PR을 통과시키기 위한 검증용으로 사용됩니다.

5. Git pre-commit hook 적용

코드를 커밋하기 전에 자동으로 포맷을 적용하려면 Git pre-commit hook을 설정하는 것이 좋습니다. hook을 통해 포맷팅되지 않은 코드가 커밋되는 것을 사전에 방지할 수 있으며, 팀의 코드 컨벤션을 강제하는 데 효과적입니다.

A. scripts/pre-commit.sh

#!/bin/sh

PROJECT_ROOT=$(git rev-parse --show-toplevel)
stagedFiles=$(git diff --staged --name-only)

echo "Running spotlessApply. Formatting code..."
cd "$PROJECT_ROOT" && ./gradlew spotlessApply

if [ $? -ne 0 ]; then
  echo "Spotless apply failed!"
  exit 1
fi

for file in $stagedFiles; do
  if test -f "$file"; then
    git add "$file"
  fi
done

이 스크립트는 커밋 직전에 spotlessApply를 실행하여 코드 스타일을 자동으로 정리하고, 포맷된 파일을 다시 staging 영역에 반영합니다.

B. scripts/install-git-hooks.sh

#!/bin/sh

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"

echo "Installing Git hooks..."
cp "$PROJECT_ROOT/scripts/pre-commit" "$PROJECT_ROOT/.git/hooks/pre-commit"
chmod +x "$PROJECT_ROOT/.git/hooks/pre-commit"
echo "Git hooks installed."

이 스크립트는 위의 pre-commit 스크립트를 Git 훅 디렉토리인 .git/hooks에 복사하여, 커밋 시 자동으로 실행되도록 등록하는 역할을 합니다.

sh scripts/install-git-hooks.sh

pre-commit.sh/install-git-hooks.sh 스크립트 파일 작성이 완료되셨으면, sh scripts/install-git-hooks.sh명령으로 Git pre-commit hook을 적용할 수 있습니다.

7. CI 연동

CI 환경에서는 ./gradlew spotlessCheck를 실행하여 코드 스타일이 올바른지 검사할 수 있습니다.

정리

Kotlin 프로젝트에서 Spotless와 Ktlint를 활용하면 코드 스타일을 자동화하여 팀 컨벤션을 강제할 수 있습니다. 이를 통해 코드 리뷰에서 불필요한 스타일 지적을 줄이고, 변경 이력도 깔끔하게 유지할 수 있습니다.

1. Gradle에 Spotless 설정을 추가하고 Ktlint를 연동합니다.
2. Git pre-commit 훅을 설정하여 커밋 전 자동 포맷을 적용합니다.
3. CI에서 spotlessCheck를 실행하여 스타일 위반을 사전에 차단합니다.

이와 같은 설정을 통해 코드의 일관성과 협업 효율성을 동시에 높일 수 있으며, 실무에 즉시 적용 가능한 표준으로 자리잡을 수 있습니다.