IntelliJ CheckStyle 설정 가이드: Google Style Formatter로 코드 품질 높이기

혼자 코딩할 때는 크게 신경 쓰지 않았던 문제들이 팀 프로젝트를 시작하면 수면 위로 떠오릅니다. 그중 가장 대표적인 것이 바로 ‘코드 스타일’입니다. 괄호의 위치, 들여쓰기 간격, Import 순서 등 사소해 보이는 차이가 코드 리뷰 시간을 잡아먹고 가독성을 떨어뜨리는 주범이 되곤 합니다.

오늘은 Java 개발자들이 가장 많이 사용하는 IDE인 Intellij IDEA에서 IntelliJ CheckStyle 설정과 Google Style Formatter를 적용하여, 팀원 모두가 숨 쉬듯 자연스럽게 코드 컨벤션을 지키는 환경을 만드는 방법을 상세히 알아보겠습니다.

왜 CheckStyle과 Google Style을 사용해야 할까요?

설정 방법에 앞서, 왜 이 귀찮은(?) 작업을 해야 하는지 짚고 넘어가겠습니다. 단순히 “보기에 좋아서”만은 아닙니다.

1. 일관된 코드 품질 유지: Google Style Formatter를 사용하면 누가 작성했든 마치 한 사람이 짠 코드처럼 통일감을 줍니다.
2. 오류 사전 방지: CheckStyle 플러그인은 코드가 컴파일되기 전에 스타일 오류를 실시간으로 잡아줍니다.
3. 생산성 향상: 코드 리뷰 시간에 “여기 들여쓰기 안 맞네요” 같은 소모적인 논쟁 대신, 로직과 아키텍처에 집중할 수 있게 해 주어 개발 생산성을 높여줍니다.

1. IntelliJ IDEA에 CheckStyle 플러그인 설정하기

가장 먼저 할 일은 스타일 검사를 도와줄 CheckStyle-IDEA 플러그인을 설치하는 것입니다.

1.1. 플러그인 설치

1. IntelliJ IDEA를 실행합니다.
2. Windows/Linux: File → Settings, Mac: IntelliJ IDEA → Settings (단축키 Cmd + ,)로 진입합니다.
3. 좌측 메뉴에서 Plugins(플러그인)을 선택합니다.
4. 상단 탭을 Marketplace(마켓플레이스)**로 변경하고 검색창에 CheckStyle-IDEA를 입력합니다.
5. 검색 결과에 나온 플러그인의 Install(설치) 버튼을 클릭합니다.
6. 설치가 완료되면 Restart IDE(재시작) 버튼을 눌러 변경 사항을 반영합니다.

1.2. CheckStyle 세부 설정

플러그인이 설치되었다면, 이제 어떤 규칙으로 검사할지 알려줘야 합니다. 우리는 가장 널리 쓰이는 Google Style을 기준으로 설정하겠습니다.

1. 설정 창(Settings)을 다시 엽니다.
2. Tools(도구) → CheckStyle 메뉴로 이동합니다.
3. Scan Scope(스캔 범위)를 Only Java Sources (including tests)로 변경합니다. 불필요한 파일까지 검사하는 것을 막아 속도를 높여줍니다.
4. Configuration file(설정 파일) 목록에서 Google Checks 항목을 찾아 체크박스(Active)를 활성화합니다. (기본 내장되어 있어 별도 파일이 필요 없습니다.)

1.3. Git Commit 시 자동 검사 설정

코드를 커밋하기 전에 스타일 위반 사항이 있다면 커밋을 막아주는 안전장치를 걸어봅시다.

1. 설정 창에서 Version Control(버전 관리) → Commit으로 이동합니다.
2. Commit Checks 섹션에서 Scan with CheckStyle 옵션을 찾아 활성화합니다.
3. 이제 컨벤션을 지키지 않은 코드는 커밋 단계에서 경고가 발생하여 실수를 원천 차단할 수 있습니다.

2. Google Style 기반 Formatter 설정하기

CheckStyle이 “틀린 그림 찾기”라면, Formatter는 “자동 정렬 기계”입니다. 코드를 저장할 때마다 자동으로 Google Style에 맞춰 정렬되도록 설정해 보겠습니다.

2.1. Formatter 설정 파일 준비

먼저 Google에서 제공하는 공식 스타일 정의 파일이 필요합니다.

• 다운로드: Google Style Guide GitHub 저장소에서 intellij-java-google-style.xml 파일을 다운로드하여 PC에 저장합니다.

2.2. IntelliJ에 설정 파일 가져오기

1. 설정 창(Settings)에서 Editor(편집기) → Code Style(코드 스타일) → Java로 이동합니다.
2. 설정 창 상단의 Scheme 옆에 있는 톱니바퀴 아이콘(설정)을 클릭합니다.
3. Import Scheme(구성 가져오기) → Intellij IDEA Code Style XML을 선택합니다.
4. 방금 다운로드한 intellij-java-google-style.xml 파일을 선택하고 OK를 누릅니다.
5. Scheme 이름(예: GoogleStyle)을 확인하고 적용(Apply)합니다.

3. 저장 시 자동 포맷팅 (Actions on Save)

매번 단축키를 눌러 정렬하는 것은 번거롭습니다. 파일 저장(Ctrl + S 또는 Cmd + S)만 해도 알아서 정렬되도록 설정하는 것이 IntelliJ CheckStyle 설정의 화룡점정입니다.

1. 설정 창에서 Tools(도구) → Actions on Save(저장 시 액션)로 이동합니다.
2. 다음 두 가지 옵션을 반드시 체크합니다.
   • Reformat code (코드 서식 다시 지정): 줄 바꿈, 들여쓰기 등을 자동 교정합니다.
   • Optimize imports (Import문 최적화): 사용하지 않는 Import를 제거하고 순서를 정리합니다.

이렇게 설정해두면 코드를 작성하고 저장하는 순간, 마법처럼 코드가 깔끔하게 정리되는 것을 볼 수 있습니다.

4. 작업 중 유의사항 및 팁

이제 완벽한 환경이 구축되었습니다. 하지만 실제 개발 시 몇 가지 알아두면 좋은 점들이 있습니다.

• 수동 포맷 단축키: 가끔 저장하기 전에 특정 파일만 즉시 정리하고 싶다면 포맷팅 단축키를 활용하세요.
  • Mac: Cmd + Opt + L
  • Windows: Ctrl + Alt + L
• CheckStyle 에러 해결: 코드를 작성하다가 에디터 우측이나 하단에 빨간색 CheckStyle 경고가 뜬다면, 해당 부분에 마우스를 올려 어떤 규칙을 위반했는지 확인하고 수정하세요.
• 팀 공유: 이 설정 과정이 복잡하다면, settings.zip으로 설정을 내보내어 팀원들에게 공유하는 것도 좋은 방법입니다.

IDE 설정만으로는 강제되지 않는다

여기까지 하면 내 IntelliJ 에서는 규칙이 보입니다. 그런데 그게 전부입니다. IDE 설정은 각자의 환경에 있는 것이라 팀원이 설정하지 않으면 아무 일도 일어나지 않습니다. 새로 온 사람이 설정 파일을 임포트하지 않으면 그 사람 코드는 규칙 밖에 있습니다.

규칙이 실제로 지켜지게 하려면 빌드에 넣어야 합니다. 아래는 실제로 실행해서 확인한 설정입니다 — maven-checkstyle-plugin 3.6.0 / checkstyle 10.21.1 / JDK 21.

Maven 설정

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-checkstyle-plugin</artifactId>
      <version>3.6.0</version>
      <dependencies>
        <!-- 플러그인이 기본으로 물고 오는 checkstyle 은 오래된 버전이다. 명시해서 올린다 -->
        <dependency>
          <groupId>com.puppycrawl.tools</groupId>
          <artifactId>checkstyle</artifactId>
          <version>10.21.1</version>
        </dependency>
      </dependencies>
      <configuration>
        <configLocation>google_checks.xml</configLocation>
        <consoleOutput>true</consoleOutput>
        <violationSeverity>warning</violationSeverity>
      </configuration>
    </plugin>
  </plugins>
</build>

violationSeverity가 핵심입니다. google_checks.xml의 규칙은 대부분 심각도가 warning인데, 이 옵션의 기본값은 error입니다. 그대로 두면 위반이 수십 건 나와도 빌드가 통과합니다. 설정했는데 아무것도 안 걸린다면 여기를 확인하세요.

일부러 어긴 코드로 확인

package demo;
import java.util.*;
public class Bad {
  private int MyField;
  public void DoSomething( int x,int y ) {
    if(x>y){ System.out.println("x"); }
    else
      System.out.println("y");
  }
  public int getMyField(){return MyField;}
}

mvn checkstyle:check 결과입니다.

[WARN] Bad.java:2:17: Using the '.*' form of import should be avoided - java.util.*. [AvoidStarImport]
[WARN] Bad.java:3:1:  Missing a Javadoc comment. [MissingJavadocType]
[WARN] Bad.java:4:15: Member name 'MyField' must match pattern
                      '^[a-z][a-z0-9][a-zA-Z0-9]*$'. [MemberName]
[WARN] Bad.java:5:15: Method name 'DoSomething' must match pattern
                      '^[a-z][a-z0-9][a-zA-Z0-9]*$'. [MethodName]
[WARN] Bad.java:5:26: '(' is followed by whitespace. [ParenPad]
[WARN] Bad.java:5:33: ',' is not followed by whitespace. [WhitespaceAfter]
[WARN] Bad.java:6:5:  'if' is not followed by whitespace. [WhitespaceAfter]
[WARN] Bad.java:6:12: '{' at column 12 should have line break after. [LeftCurlyEol]
...

[ERROR] Failed to execute goal ... :check (default-cli) on project cs:
        You have 27 Checkstyle violations.
[INFO] BUILD FAILURE

11줄짜리 파일에서 27건이 나왔습니다. 그리고 빌드가 실패합니다. 이게 IDE 설정과의 결정적인 차이입니다 — IDE 는 밑줄만 그어주고 넘어갈 수 있지만, 빌드는 넘어갈 수 없습니다.

Google Style 로 고치면

package demo;

import java.util.List;

/** Google Style 을 지킨 예. */
public class Good {

  private int myField;

  /**
   * x 가 y 보다 크면 x 를, 아니면 y 를 반환한다.
   *
   * @param x 첫 번째 값
   * @param y 두 번째 값
   * @return 더 큰 값
   */
  public int larger(int x, int y) {
    if (x > y) {
      return x;
    } else {
      return y;
    }
  }
}

[INFO] BUILD SUCCESS

들여쓰기가 2칸인 점에 주의하세요. Google Java Style 은 2칸입니다. IntelliJ 기본값은 4칸이라 포매터 설정을 함께 맞추지 않으면 저장할 때마다 위반이 새로 생깁니다.

자주 걸리는 규칙

위 실행에서 실제로 나온 것들입니다. Google Style 을 처음 적용하면 대개 여기서 막힙니다.

규칙	무엇을 요구하는가
MissingJavadocType / MissingJavadocMethod	public 타입·메서드에 Javadoc. 기존 코드에 적용하면 가장 많이 터진다
AvoidStarImport	import java.util.*; 금지
MemberName / MethodName	필드·메서드는 lowerCamelCase
Indentation	2칸 들여쓰기
WhitespaceAround / ParenPad	연산자·괄호 주변 공백 규칙
EmptyLineSeparator	package·import·클래스·메서드 사이 빈 줄
LeftCurlyEol / RightCurlySame	중괄호 위치. if/else가 여러 블록일 때 규칙이 다르다

Javadoc 규칙 때문에 도입을 포기하는 경우가 많습니다. 기존 프로젝트라면 google_checks.xml을 그대로 쓰지 말고 복사해서 MissingJavadoc* 모듈을 빼거나 심각도를 낮추고 시작하는 편이 현실적입니다. 공백·네이밍처럼 이견이 없는 규칙부터 강제하고, 문서화 규칙은 나중에 붙이면 됩니다.

CI 에 넣기

빌드 수명주기에 묶어 두면 별도 명령 없이 검사됩니다.

<executions>
  <execution>
    <id>checkstyle-validate</id>
    <phase>validate</phase>     <!-- 컴파일보다 먼저 검사한다 -->
    <goals><goal>check</goal></goals>
  </execution>
</executions>

validate 단계에 붙이면 컴파일 전에 걸러집니다. 테스트까지 다 돌린 뒤 스타일 때문에 실패하는 것보다 CI 시간이 절약됩니다.

이미 위반이 수백 건 쌓인 프로젝트라면 한 번에 켤 수 없습니다. <includes>로 신규 패키지만 대상으로 잡거나, 새로 만드는 모듈에만 적용해 범위를 넓혀 가는 방법이 낫습니다. 아키텍처 규칙에서 같은 문제를 다루는 방법은 ArchUnit 글의 FreezingArchRule 항목에 정리해 두었습니다.

자주 묻는 질문

CheckStyle 을 설정했는데 위반이 하나도 안 잡힙니다.

violationSeverity가 기본값 error로 남아 있을 가능성이 큽니다. google_checks.xml의 규칙은 대부분 warning 이라 기본 설정에서는 빌드가 통과합니다. <violationSeverity>warning</violationSeverity>를 명시해야 걸립니다.

IDE 플러그인과 Maven 플러그인 중 하나만 쓰면 안 되나요?

둘의 역할이 다릅니다. IDE 는 쓰는 중에 알려주고, 빌드는 어긴 코드가 들어오는 것을 막습니다. IDE 만 쓰면 설정하지 않은 사람의 코드가 그대로 들어옵니다. 빌드만 쓰면 CI 에서야 알게 되어 되돌아가는 비용이 듭니다. 둘 다 두는 것이 맞습니다.

checkstyle 버전을 왜 따로 명시하나요?

maven-checkstyle-plugin이 기본으로 물고 오는 checkstyle 버전은 플러그인 릴리스 시점에 고정돼 있어 최신 문법을 모를 수 있습니다. 레코드나 sealed 클래스 같은 최신 문법에서 파싱 오류가 나면 dependencies로 버전을 올려 해결합니다.

포매터와 CheckStyle 설정이 충돌합니다.

정상입니다. CheckStyle 은 검사만 하고 포맷을 바꾸지 않으므로, 포매터를 같은 규칙으로 맞춰야 합니다. Google Style 을 쓰면 들여쓰기 2칸이 가장 먼저 충돌하는 지점입니다. IntelliJ 의 Code Style 설정을 함께 임포트하지 않으면 저장할 때마다 위반이 생깁니다.

이 글의 Maven 설정과 실행 결과는 maven-checkstyle-plugin 3.6.0 / checkstyle 10.21.1 / JDK 21 환경에서 직접 실행해 확인한 것입니다(2026년 9월 기준). IntelliJ 플러그인 화면 구성은 IDE 버전에 따라 다를 수 있습니다.

마무리

지금까지 IntelliJ CheckStyle 설정과 Google Formatter를 통한 자동화 환경 구축 방법에 대해 알아보았습니다. 처음에는 설정 과정이 다소 번거롭게 느껴질 수 있지만, 한 번 세팅해 두면 프로젝트 내내 코드 리뷰 피로도가 확연히 줄어드는 것을 경험하실 수 있습니다.

함께 읽으면 좋은 글

• Spring AI로 MCP 서버 만들기: 코드는 쉬운데 Spring Boot 3에서 안 뜹니다
• OAuth 2.1 무엇이 달라지나: PKCE 의무화와 Implicit 퇴출 (2026년 기준)
• 슈퍼 클로드 vs 슈퍼 제미나이: 개발자와 기획자를 위한 AI 확장 프레임워크 비교