Harper 문법 검사기 실전 가이드: 오프라인 설치부터 LSP 연동, 사전 등록, CI 자동화까지

Q: 오탐이 너무 많은데 어떻게 줄이나요?

규칙 전체를 끄기 전에 세 단계를 순서대로 시도하는 것이 좋다. 고유명사 오탐이면 .harper-dictionary.txt에 등록하고, 특정 문장 하나만 문제라면 ignoredLintsPath로 해당 건만 무시 목록에 넣는다. 규칙 자체가 프로젝트와 맞지 않을 때만 linters에서 끈다. LongSentences는 기술 문서에서 오탐률이 높아 처음부터 꺼두는 팀이 많다.

Q: CI에서 오타가 있는데도 빌드가 통과하는 이유는 뭔가요?

파이프를 썼기 때문일 가능성이 높다. harper-cli는 지적 사항을 발견하면 종료 코드 1을 반환하므로 원래는 CI가 실패한다. 그런데 harper-cli lint ... | tee harper.log처럼 파이프를 쓰면 GitHub Actions의 기본 셸(bash -e)에 pipefail이 없어 마지막 명령의 종료 코드만 반영된다. 파이프 없이 harper-cli lint --format compact $(git ls-files '*.md')를 그대로 실행하거나, 로그가 필요하면 스텝에 shell: bash를 명시하면 된다.

Harper 문법 검사기는 Automattic이 Apache-2.0으로 공개한 오프라인 영문 문법 검사기다. Rust로 작성돼 제안 생성에 약 10ms가 걸리고, 텍스트가 네트워크로 나가지 않으며, harper-ls 바이너리로 LSP를 네이티브 구현해 VS Code와 IntelliJ, Neovim에 그대로 붙는다. 코드 주석과 커밋 메시지, 마크다운 문서를 대상으로 삼는다는 점에서 범용 문법 도구와 갈린다.

영어권 오픈소스 저장소에 PR을 올려본 적이 있다면, 리뷰어가 코드가 아니라 주석 오타를 지적하는 경험을 한 번쯤 해봤을 것이다. 정작 로직에는 아무 문제가 없는데 Javadoc의 recieve나 커밋 메시지의 seperate 같은 단어 하나가 리뷰 스레드를 차지한다. 사내 프로젝트라고 사정이 다르지도 않다. README와 API 문서를 영어로 쓰는 팀에서는 오타가 그대로 문서에 박제되고, 몇 달 뒤 누군가 검색으로 찾다가 발견한다. 그렇다고 코드 편집기에서 나와 브라우저 문법 검사기에 붙여넣는 습관을 유지하기도 어렵고, 사내 코드를 외부 서비스에 전송하는 것 자체가 막혀 있는 조직도 많다. 이번 포스팅에서는 Automattic이 개발하고 오픈소스로 공개한 Harper 문법 검사기를 설치해 에디터에 붙이고, 규칙을 프로젝트에 맞게 조정한 뒤 CI에서 문서 오타까지 막는 방법을 정리하고자 한다.

왜 영문 주석 오타는 코드 리뷰를 그냥 통과하는가

리뷰어가 관대해서가 아니라, 리뷰 시점에는 이미 늦었기 때문이다. IDE의 기본 맞춤법 검사기는 단어 단위 사전 대조만 하므로 it's와 its, affect와 effect처럼 철자는 맞고 문법만 틀린 표현을 잡지 못한다. 결국 사람 눈에 의존하게 되고, 사람은 코드를 볼 때 주석을 건너뛴다. 문법 검사를 코드 작성 시점으로 당겨야 해결되는 문제다.

Harper 문법 검사기는 이 지점을 정확히 겨냥한 도구다. 공식 저장소 기준 13,945개의 스타와 539개의 포크를 기록하고 있다. 라이선스는 Apache-2.0이고 2026년 7월 28일 v2.7.0이 릴리스됐다. Homebrew 공식 포뮬러의 설명문이 “Grammar Checker for Developers”인 데서 드러나듯, 처음부터 산문가가 아니라 개발자를 대상으로 설계됐다.

검사 전 과정이 로컬에서 끝나 텍스트가 네트워크로 나가지 않는다. 여기에 Language Server Protocol을 직접 구현한 harper-ls 바이너리를 제공해 별도 어댑터 없이 에디터에 붙는다. 사내 코드를 다루면서 실시간 피드백까지 받고 싶은 백엔드 개발자에게는 이 조합이 꽤 현실적인 선택지다.

10ms와 4000ms 사이, Harper가 내세우는 숫자

Harper 문법 검사기의 가장 큰 무기는 속도와 메모리다. 저장소의 COMPARISON.md는 경쟁 도구와의 지표를 직접 공개하고 있는데, 제안 생성 시간이 Harper 10ms, LanguageTool 650ms, Grammarly 4000ms다. README는 여기에 더해 LanguageTool 메모리 사용량의 50분의 1 미만으로 동작한다고 밝히고 있다.

아래 수치는 Harper 개발팀이 COMPARISON.md에 공개한 자체 측정값이고, 제안 생성 시간은 단일 문서 기준이다(2026년 7월, v2.7.0). LanguageTool은 JVM 위에서, Grammarly는 원격 API 호출로 동작하는 반면 Harper는 로컬 네이티브 바이너리라는 구조적 차이가 있어, 자릿수 수준의 격차 자체는 납득할 만하다.

항목	Harper	LanguageTool	Grammarly	hunspell
제안 생성 시간	10ms	650ms	4000ms	비교 대상 외
라이선스	Apache-2.0	LGPL-2.1	독점	LGPL/GPL/MPL
LSP 지원	네이티브 (`harper-ls`)	`ltex-ls` 경유	`grammarly-language-server` 경유	없음
다국어	영어만	지원 (동시 사용 불가)	방언 동시 처리 불가	지원 (동시 사용 불가)
규칙 방식	자체 룰셋	자체 룰셋 + N-Gram + LLM	비공개	hunspell/MySpell

맞바꿈이 분명하다. 다국어를 포기하는 대신 영어 한 언어에서 10ms대 응답과 네이티브 LSP를 얻는 구조다. 에디터 통합은 타이핑할 때마다 문서를 다시 검사해도 체감 지연이 없어야 의미가 있는데, 650ms와 10ms 사이 어딘가에 그 경계선이 있다. 반대로 한국어 맞춤법까지 기대하고 도입하면 Harper 문법 검사기는 실망스러운 도구다.

brew 한 줄로 끝나는 Harper 문법 검사기 설치

설치는 brew install harper 한 줄로 끝난다. 이 명령은 바이너리 두 개를 함께 올리는데, 터미널과 CI에서 파일을 일괄 검사하는 harper-cli와 에디터가 붙는 language server인 harper-ls다. Windows는 scoop install harper, Arch Linux는 sudo pacman -S harper로 같은 결과를 얻는다. 대부분 공식 패키지 매니저에 올라가 있어 소스 빌드가 필요 없다.

# macOS / Linux
brew install harper

# Windows
scoop install harper

# Arch Linux
sudo pacman -S harper

# Nix
nix shell 'nixpkgs#harper'

# Rust 툴체인이 있다면 (language server만)
cargo install harper-ls --locked

# macOS / Linux
brew install harper

# Windows
scoop install harper

# Arch Linux
sudo pacman -S harper

# Nix
nix shell 'nixpkgs#harper'

# Rust 툴체인이 있다면 (language server만)
cargo install harper-ls --locked

ShellScript

brew install harper는 Homebrew 공식 포뮬러 정의상 harper-cli와 harper-ls 두 바이너리를 함께 설치한다. 앞의 것은 터미널과 CI에서 파일을 일괄 검사하는 프론트엔드이고, 뒤의 것은 에디터가 붙는 language server다. 반면 cargo install harper-ls는 이름 그대로 language server만 설치한다는 점에 주의해야 한다. crates.io에 harper-cli는 배포돼 있지 않아, Rust 경로로 CLI까지 원한다면 저장소를 직접 지정해야 한다.

설치가 끝났는지는 짧은 마크다운 파일 하나로 확인하는 것이 가장 빠르다.

cat > /tmp/test.md <<'EOF'
# Hello Harper

This is an example to ensure language detection works properly.
EOF

harper-cli lint --dialect American /tmp/test.md
# /tmp/test.md: No lints found

cat > /tmp/test.md <<'EOF'
# Hello Harper

This is an example to ensure language detection works properly.
EOF

harper-cli lint --dialect American /tmp/test.md
# /tmp/test.md: No lints found

ShellScript

문제가 없으면 No lints found가 출력된다. Harper 문법 검사기의 이 검증 절차는 Homebrew 포뮬러의 test do 블록에 들어 있는 것과 동일하므로, 여기서 실패한다면 설치 자체가 잘못된 것이다. --dialect는 American, British, Australian, Canadian, Indian을 받으며 us, gb 같은 약어도 인식한다. CLI의 기본값은 us다.

Java 주석만 골라 읽는 파서의 정체

Harper 문법 검사기는 소스 파일을 통째로 영어 문서로 취급하지 않고 주석만 골라내 검사한다. Map<String, List<Order>> 같은 코드는 건드리지 않고 그 위의 Javadoc만 읽는다는 뜻이다. 개발자용을 표방하는 근거가 여기 있다.

주석 단위로 검사하는 언어는 31종이다.

C, C++, C#, Clojure, CMake, DAML, Dart, Gleam, Go, Groovy,
Haskell, Literate Haskell, Java, JavaScript, JSX, Kotlin, Lua,
Nix, PHP, PowerShell, Python, Ruby, Rust, Scala, Shell,
Solidity, Swift, TOML, TypeScript, TSX, Zig

C, C++, C#, Clojure, CMake, DAML, Dart, Gleam, Go, Groovy,
Haskell, Literate Haskell, Java, JavaScript, JSX, Kotlin, Lua,
Nix, PHP, PowerShell, Python, Ruby, Rust, Scala, Shell,
Solidity, Swift, TOML, TypeScript, TSX, Zig

Plaintext

문서 전체를 검사 대상으로 삼는 형식은 따로 분류돼 있다. Markdown, AsciiDoc, HTML, Plain Text, LaTeX/TeX, Typst, Ink, 이메일, 그리고 Git Commit과 Jujutsu Description이 여기 속한다. 커밋 메시지가 독립된 파서로 잡혀 있다는 점이 특히 실용적인데, git commit 편집 화면에서 곧바로 문법 지적을 받을 수 있다는 의미이기 때문이다.

이 구조는 저장소 구성에서도 확인된다. Harper 모노레포에는 harper-comments, harper-tree-sitter, harper-git-commit, harper-tex 같은 크레이트가 언어·형식별로 분리돼 있다. harper-comments는 tree-sitter 문법 크레이트 25종에 직접 의존하면서 노드 종류에 comment가 들어간 것만 골라내는데, 덕분에 정규식 기반 도구처럼 문자열 리터럴 안의 //에 속아 넘어가지 않는다. Java와 Kotlin, Groovy가 모두 지원 목록에 있어 Spring Boot 프로젝트라면 Javadoc, Gradle 빌드 스크립트, 테스트 코드 주석이 전부 검사 범위에 들어온다.

Harper 문법 검사기를 에디터에 붙이는 세 가지 경로

Harper 문법 검사기를 에디터에 붙이는 경로는 세 가지다. VS Code는 code --install-extension elijah-potter.harper, IntelliJ 계열은 JetBrains 마켓플레이스의 Harper 플러그인, Neovim은 nvim-lspconfig의 harper_ls 정의 한 줄이다. 셋 모두 설치 시 함께 올라오는 동일한 harper-ls language server를 구동하므로 팀원이 서로 다른 에디터를 써도 검사 결과는 같다.

VS Code는 공식 확장이 마켓플레이스에 올라가 있다.

code --install-extension elijah-potter.harper

code --install-extension elijah-potter.harper

ShellScript

확장이 harper-ls 바이너리를 자체적으로 포함하므로 별도 설치 없이 바로 동작한다. 이미 brew로 설치한 바이너리를 쓰고 싶다면 harper.path 설정에 실행 파일 경로를 지정하면 된다. 팀 전체가 같은 버전을 써야 하는 상황이라면 이쪽이 안전하다.

IntelliJ 계열은 JetBrains 마켓플레이스의 Harper 플러그인을 설치한다. 이 플러그인은 harper-ls 바이너리를 자동으로 내려받고 갱신까지 처리하며 macOS, Linux, Windows를 모두 지원한다. 다만 Automattic이 직접 만든 공식 플러그인이 아니라 커뮤니티(huangcheng)가 유지보수하는 서드파티 통합이라는 점은 알고 도입하는 것이 좋다. 사내 보안 정책상 서드파티 플러그인 심사가 필요한 조직이라면 미리 확인해야 한다. IntelliJ에 외부 프로세스를 붙이는 다른 사례로는 MCP 서버 연동이 있는데, 바이너리 자동 다운로드와 보안 심사라는 고민 지점이 거의 같다.

Neovim은 nvim-lspconfig에 이미 정의가 들어 있어 한 줄로 끝난다.

require('lspconfig').harper_ls.setup {}

require('lspconfig').harper_ls.setup {}

Plaintext

harper-ls가 PATH에 있으면 이 한 줄로 붙는다. mason.nvim으로 관리하는 경우에도 동일하다. 최신 Neovim에서는 vim.lsp.config('harper_ls', {}) 형태도 함께 안내되고 있으니, 설정 스타일에 맞춰 고르면 된다. Helix, Emacs, Zed, Sublime Text도 같은 language server를 그대로 쓴다. Obsidian 플러그인과 Chrome, Firefox 확장, WordPress 블록 에디터 플러그인도 별도로 제공된다.

규칙을 프로젝트 취향에 맞게 조이고 풀기

Harper 문법 검사기의 규칙은 harper-ls 키 아래 JSON 객체로 켜고 끈다. 실무에서 먼저 손대는 값은 대체로 셋이다. diagnosticSeverity를 기본값 hint에서 warning으로 올리고, 기술 문서에서 오탐이 잦은 LongSentences를 끄고, 한영 혼용 주석이 있다면 isolateEnglish를 true로 바꾸는 것이다.

아래는 Neovim 기준 설정 예시이고, 값은 모두 공식 language server 문서에 명시된 기본값이다.

require('lspconfig').harper_ls.setup {
  settings = {
    ["harper-ls"] = {
      userDictPath = "",
      workspaceDictPath = "",
      fileDictPath = "",
      linters = {
        SpellCheck = true,             -- 철자 검사
        SpelledNumbers = false,        -- 숫자를 영단어로 쓰도록 강제
        AnA = true,                    -- a/an 오용
        SentenceCapitalization = true, -- 문장 첫 글자 대문자
        UnclosedQuotes = true,         -- 닫히지 않은 따옴표
        WrongApostrophe = false,       -- 잘못된 아포스트로피 문자
        LongSentences = true,          -- 지나치게 긴 문장
        RepeatedWords = true,          -- the the 같은 중복 단어
        Spaces = true,                 -- 연속 공백
        CorrectNumberSuffix = true     -- 1st, 2nd 같은 서수 접미사
      },
      codeActions = {
        ForceStable = false            -- 코드 액션 순서 고정
      },
      markdown = {
        IgnoreLinkTitle = false        -- 마크다운 링크 텍스트 검사 여부
      },
      diagnosticSeverity = "hint",     -- error | warning | information | hint
      isolateEnglish = false,          -- 비영어 구간 자동 제외
      dialect = "American",
      maxFileLength = 120000,          -- 이 길이를 넘으면 검사하지 않음
      ignoredLintsPath = "",
      excludePatterns = {}
    }
  }
}

require('lspconfig').harper_ls.setup {
  settings = {
    ["harper-ls"] = {
      userDictPath = "",
      workspaceDictPath = "",
      fileDictPath = "",
      linters = {
        SpellCheck = true,             -- 철자 검사
        SpelledNumbers = false,        -- 숫자를 영단어로 쓰도록 강제
        AnA = true,                    -- a/an 오용
        SentenceCapitalization = true, -- 문장 첫 글자 대문자
        UnclosedQuotes = true,         -- 닫히지 않은 따옴표
        WrongApostrophe = false,       -- 잘못된 아포스트로피 문자
        LongSentences = true,          -- 지나치게 긴 문장
        RepeatedWords = true,          -- the the 같은 중복 단어
        Spaces = true,                 -- 연속 공백
        CorrectNumberSuffix = true     -- 1st, 2nd 같은 서수 접미사
      },
      codeActions = {
        ForceStable = false            -- 코드 액션 순서 고정
      },
      markdown = {
        IgnoreLinkTitle = false        -- 마크다운 링크 텍스트 검사 여부
      },
      diagnosticSeverity = "hint",     -- error | warning | information | hint
      isolateEnglish = false,          -- 비영어 구간 자동 제외
      dialect = "American",
      maxFileLength = 120000,          -- 이 길이를 넘으면 검사하지 않음
      ignoredLintsPath = "",
      excludePatterns = {}
    }
  }
}

Plaintext

여기 적은 linters 열 개는 전체 목록이 아니라 문서의 발췌다. VS Code 확장이 등록하는 harper.linters.* 키만 800개가 넘는데, ThenThan, ItsContraction, OxfordComma 같은 개별 규칙이 전부 따로 토글된다. 전체 목록과 기본값, 설명은 harper-cli config로 출력해 볼 수 있다. diagnosticSeverity는 기본값이 hint라 에디터에 따라 표시가 흐릿하게 나오므로, 문서 품질을 실제로 관리할 생각이라면 warning으로 올려야 눈에 들어온다. excludePatterns에는 자동 생성 문서나 서드파티 코드를 넣어 검사 대상에서 빼면 된다.

isolateEnglish는 한국 개발팀에 특히 반가운 옵션이다. 주석에 한국어와 영어가 섞여 있으면 한국어 부분이 통째로 철자 오류로 잡히는데, 이 값을 true로 두면 비영어 구간을 감지해 건너뛴다. 기본값은 false다. 다만 공식 문서가 이 기능을 두고 아직 불안정하니 완벽한 동작을 기대하지 말라고 명시하고 있어, 켜둔 뒤 오탐 양상을 한 번 확인하는 편이 좋다.

VS Code에서도 같은 항목을 설정 UI의 Harper 섹션에서 조정할 수 있다. 팀 단위로 통일하려면 프로젝트의 .vscode/settings.json에 넣어 저장소에 커밋하는 방법이 무난하다.

도메인 용어를 사전에 등록해 오탐 없애기

Harper 문법 검사기의 고유명사 오탐은 세 단계 사전으로 잡는다. 프로젝트 사전은 워크스페이스 루트의 .harper-dictionary.txt, 개인 사전은 OS별 설정 디렉터리, 파일 단위 사전은 데이터 디렉터리에 놓인다. 도입 며칠이면 Kubernetes, Quarkus, 사내 서비스 이름이 전부 철자 오류로 뜨는 상황을 만나는데, 대부분 프로젝트 사전 하나로 정리된다.

프로젝트 전용 사전은 워크스페이스 루트의 .harper-dictionary.txt이며, 한 줄에 단어 하나씩 적는다.

Quarkus
Hibernate
Kubernetes
Kafka
idempotency

Quarkus
Hibernate
Kubernetes
Kafka
idempotency

Plaintext

이 파일을 저장소에 커밋해 두면 팀원 전원이 같은 사전을 공유하게 되고, 새로 합류한 사람이 같은 오탐을 다시 겪지 않는다. 겸사겸사 도메인 용어집이 되기도 한다. 도구 설정을 SaaS 계정이 아니라 저장소에 두는 접근은 API 컬렉션을 Git으로 관리하는 Bruno와 같은 발상이다. 리뷰 대상이 되고, 롤백이 되고, 신규 입사자가 clone 한 번으로 따라온다. 경로를 바꾸고 싶다면 설정의 workspaceDictPath에 지정하면 된다.

개인 사전과 파일 단위 사전은 OS별 표준 경로를 따른다. 개인 사전은 Linux에서 $XDG_CONFIG_HOME/harper-ls/dictionary.txt, macOS에서 $HOME/Library/Application Support/harper-ls/dictionary.txt, Windows에서는 로밍 AppData 아래 같은 이름으로 위치한다. 파일 단위 사전은 Linux 기준 $XDG_DATA_HOME/harper-ls/file_dictionaries에 저장되며 macOS는 개인 사전과 같은 디렉터리를 쓴다. Harper 문법 검사기의 에디터 통합에서 오탐 위에 코드 액션을 띄우면 어느 사전에 추가할지 고를 수 있으므로, 경로를 직접 열 일은 사실 많지 않다.

CI에서 오타를 막는 harper-cli 워크플로

CI 기본형은 harper-cli lint --format compact $(git ls-files '*.md') 한 줄이다. harper-cli는 지적 사항을 하나라도 발견하면 종료 코드 1을 반환하므로 별도 판정 스텝 없이 빌드가 실패한다. 에디터 연동만으로는 Harper 문법 검사기를 설치하지 않은 팀원의 PR이 그대로 통과하는데, 터미널·CI용 프론트엔드인 harper-cli가 이 구멍을 메운다.

# 기본 검사 (Ariadne 리포트로 소스 컨텍스트까지 출력)
harper-cli lint README.md docs/api.md

# 오류 개수만 확인
harper-cli lint --count README.md

# 특정 규칙만 실행하거나 제외
harper-cli lint --only SpellCheck,RepeatedWords README.md
harper-cli lint --ignore LongSentences README.md

# 기계 판독용 출력
harper-cli lint --format json README.md
harper-cli lint --format compact README.md

# 기본 검사 (Ariadne 리포트로 소스 컨텍스트까지 출력)
harper-cli lint README.md docs/api.md

# 오류 개수만 확인
harper-cli lint --count README.md

# 특정 규칙만 실행하거나 제외
harper-cli lint --only SpellCheck,RepeatedWords README.md
harper-cli lint --ignore LongSentences README.md

# 기계 판독용 출력
harper-cli lint --format json README.md
harper-cli lint --format compact README.md

ShellScript

--format compact는 파일:행:열: 린트종류::규칙이름: 메시지 형태로 한 줄씩 출력한다. 린트 종류는 Spelling, Typo, Repetition, WordChoice 같은 카테고리 이름이라 실제로는 README.md:12:5: Spelling::SpellCheck: Did you mean ...처럼 찍힌다. GCC나 grep과 같은 형식이라 기존 로그 파서와 에디터 quickfix에 그대로 물린다. compact 모드에서는 No lints found 같은 파일별 상태 메시지가 애초에 출력되지 않으므로 --quiet는 기본 출력 포맷에서만 의미가 있다. Harper 문법 검사기 CLI에는 lint 외에 parse, spans, annotate, metadata, words, config 서브커맨드가 있는데, 이들은 규칙을 디버깅하거나 설정을 조회할 때 쓴다.

GitHub Actions 워크플로는 이렇게 짧게 끝난다.

name: docs-lint

on: [pull_request]

jobs:
  harper:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install harper-cli
        run: |
          cargo install --git https://github.com/Automattic/harper \
            --tag v2.7.0 --locked harper-cli

      - name: Lint markdown docs
        run: harper-cli lint --format compact $(git ls-files '*.md')

name: docs-lint

on: [pull_request]

jobs:
  harper:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install harper-cli
        run: |
          cargo install --git https://github.com/Automattic/harper \
            --tag v2.7.0 --locked harper-cli

      - name: Lint markdown docs
        run: harper-cli lint --format compact $(git ls-files '*.md')

YAML

지적 사항이 하나라도 있으면 harper-cli가 stderr에 Error: Lints were found를 출력하고 종료 코드 1로 빠지므로, 판정 스텝을 따로 붙일 필요가 없다. harper-cli의 README는 스스로를 “experimental frontend”라고 표현하고 있으니, 세부 동작은 버전이 올라가면서 바뀔 수 있다고 보는 편이 안전하다.

harper-cli 결과를 파이프로 넘겼더니 CI가 통과하는 이유

파이프의 마지막 명령이 종료 코드를 결정하기 때문이다. GitHub Actions의 기본 셸은 bash -e라 pipefail이 꺼져 있어서, harper-cli lint ... | tee harper.log처럼 쓰면 harper-cli의 종료 코드 1이 tee의 0에 가려진다. 로그 파일도 함께 남기고 싶다면 스텝에 shell: bash를 명시해 pipefail을 켜야 한다. 파이프 없이 명령만 실행하는 쪽이 단순하고 안전하다.

빌드 시간도 감안해야 한다. cargo install은 Harper 워크스페이스를 통째로 컴파일하므로 캐시 없는 콜드 빌드는 러너에서 수 분 단위로 잡아야 한다. 실무에서는 Swatinem/rust-cache 같은 캐시 액션을 함께 쓰거나, GitHub Releases에 올라온 사전 빌드 바이너리를 내려받는 쪽이 훨씬 빠르다. 검사 대상도 git ls-files '*.md' 대신 변경된 파일만 넘기면 실행 시간이 줄어든다.

문법처럼 결정론적인 오류는 Harper 문법 검사기가 걸러 주지만, 로직과 설계 판단까지 자동화하려면 AI 코드 리뷰를 PR에 붙이는 방식이 짝이 된다. 규칙 기반 검사와 LLM 리뷰는 잡아내는 결함의 종류가 겹치지 않는다.

Harper가 못 하는 것부터 확인하고 도입하기

Harper 문법 검사기가 못 하는 일은 세 가지다. 한국어를 포함한 비영어 맞춤법 검사, LLM 기반 문장 재작성과 어조 조정, 그리고 오탐 없는 완결성이다. 코어가 다국어 확장을 염두에 두고 설계됐다고 밝히고 있지만 현재 구현된 언어는 영어 하나뿐이다.

Grammarly가 제공하는 어조 조정이나 문장 다듬기를 기대하면 맞지 않는다. Harper 문법 검사기는 규칙 기반 검사기이고, 잡아내는 것은 철자, 문법, 중복 단어, 대문자 처리 같은 결정론적 오류다. 대신 그 덕분에 10ms 응답과 오프라인 동작이 가능하다는 맞바꿈이다. 표현을 다듬는 작업은 여전히 다른 도구나 사람의 몫이다.

미결 이슈가 566개, 미병합 PR이 130개 쌓여 있다는 점도 감안할 만하다. 릴리스 노트를 보면 dir → directory, tho → though 같은 규칙이 매 버전 수십 개씩 추가되고 있어 개발은 활발하지만, 그만큼 오탐 보고도 꾸준히 쌓이고 있다는 뜻이기도 하다. ignoredLintsPath로 개별 지적을 무시 목록에 넣을 수 있으니, 오탐이 나올 때마다 규칙 전체를 끄기보다 해당 건만 제외하는 방식을 권한다.

자주 묻는 질문 (FAQ)

Harper 문법 검사기는 한국어 맞춤법도 검사하나요?

검사하지 않는다. 현재 영어만 지원하며 다국어 지원은 로드맵상 목표일 뿐 구현돼 있지 않다. 한영 혼용 주석을 쓰는 프로젝트라면 isolateEnglish 옵션을 true로 설정해 한국어 구간을 검사에서 제외하는 방식으로 대응하는 것이 현실적이다.

Harper 문법 검사기로 Grammarly를 완전히 대체할 수 있나요?

용도가 다르다. 코드 주석, 커밋 메시지, README처럼 개발 워크플로 안의 영문 텍스트에는 Harper가 더 낫다. 오프라인으로 동작하고 응답이 10ms 수준이며 LSP로 에디터에 직접 붙기 때문이다. 반면 어조 조정이나 문장 재작성 같은 LLM 기반 기능은 Harper에 없으므로, 대외 문서나 이메일 작성까지 대체하려면 부족하다.

사내 코드를 검사해도 외부로 전송되지 않나요?

전송되지 않는다. Harper는 로컬 바이너리로 동작하며 검사 과정에서 네트워크 요청을 하지 않는다. 사전과 규칙 데이터가 모두 바이너리에 포함돼 있기 때문이다. 다만 IntelliJ 플러그인처럼 harper-ls 바이너리를 자동으로 내려받는 통합은 최초 설치와 업데이트 시점에 네트워크를 사용한다.

오탐이 너무 많은데 어떻게 줄이나요?

규칙 전체를 끄기 전에 세 단계를 순서대로 시도하는 것이 좋다. 고유명사 오탐이면 .harper-dictionary.txt에 등록하고, 특정 문장 하나만 문제라면 ignoredLintsPath로 해당 건만 무시 목록에 넣는다. 규칙 자체가 프로젝트와 맞지 않을 때만 linters에서 끈다. LongSentences는 기술 문서에서 오탐률이 높아 처음부터 꺼두는 팀이 많다.

CI에서 오타가 있는데도 빌드가 통과하는 이유는 뭔가요?

파이프를 썼기 때문일 가능성이 높다. harper-cli는 지적 사항을 발견하면 종료 코드 1을 반환하므로 원래는 CI가 실패한다. 그런데 harper-cli lint ... | tee harper.log처럼 파이프를 쓰면 GitHub Actions의 기본 셸(bash -e)에 pipefail이 없어 마지막 명령의 종료 코드만 반영된다. 파이프 없이 harper-cli lint --format compact $(git ls-files '*.md')를 그대로 실행하거나, 로그가 필요하면 스텝에 shell: bash를 명시하면 된다.

마치며

지금까지 Harper 문법 검사기의 설치부터 에디터 연동, 규칙 조정, CI 자동화까지 정리해 보았다.

개인적으로 이 도구에서 가장 크게 체감한 건 문법 교정 자체가 아니라 .harper-dictionary.txt였다. 처음에는 오탐을 없애려고 만든 파일인데, 몇 주 지나니 이 프로젝트에서 어떤 용어를 어떤 철자로 쓰기로 했는지가 그 안에 다 들어 있었다. idempotency인지 idempotence인지, 서비스 이름의 대소문자를 어떻게 쓰는지 같은 것들이다. 리뷰에서 매번 반복되던 사소한 지적이 파일 하나로 정리된 셈이다.

반대로 기대를 접은 부분도 있다. 도입 첫날 LongSentences를 켜둔 채로 기존 문서를 전부 검사했다가 지적이 수백 개 쏟아졌는데, 절반 이상이 그냥 기술 문서 특유의 긴 문장이었다. 규칙을 한 번에 다 켜고 시작하기보다 SpellCheck와 RepeatedWords처럼 이견이 없는 것부터 켜고, 팀이 익숙해지면 하나씩 늘리는 편이 훨씬 덜 피곤하다. 문법 검사기는 결국 매일 보는 도구라, 잔소리가 많으면 며칠 안에 꺼버리게 된다.