외부 유출 없는 오프라인 문법 검사기 Harper 구축 방법

사내 보안 정책 때문에 Grammarly 같은 외부 AI 도구를 막아두면 개발자는 난감합니다. 기술 문서나 코드 주석에 오타를 남긴 채 배포하면 신뢰도가 떨어지지만, 그렇다고 하나하나 눈으로 검수하자니 시간이 너무 아깝습니다.

Harper는 이 문제를 깔끔하게 해결합니다. Rust로 개발한 오프라인 전용 문법 검사 엔진이라 외부 서버와 통신을 완전히 차단합니다. Java 기반으로 동작하며 메모리를 수백 메가바이트씩 먹던 LanguageTool과 달리 메모리 점유율이 십수 메가바이트 수준에 불과합니다. 10ms 미만의 응답 속도로 동작하므로 에디터가 느려질 일도 없습니다.

1. 개발 환경 설치와 에디터 LSP 연동

harper-ls는 단말 내부에서 로컬 CPU 자원만 사용해 구문 분석을 수행합니다. 운영체제에 맞는 패키지 매니저로 바이너리를 설치하고 에디터에 표준 LSP로 등록하면 됩니다.

패키지 설치

터미널에서 명령어를 실행해 바이너리를 설치합니다.

macOS / Linux: brew install harper
Rust 환경: cargo install harper-ls --locked
Windows: scoop install harper

Neovim 및 VS Code 연동

Neovim에서는 nvim-lspconfig로 대상 파일 타입과 린터 규칙을 설정합니다.

local lspconfig = require('lspconfig')

lspconfig.harper_ls.setup({
  filetypes = { 'markdown', 'gitcommit', 'rust', 'go', 'typescript', 'python' },
  settings = {
    ["harper-ls"] = {
      userDictPath = "~/config/harper/user_dict.txt",
      workspaceDictPath = ".harper-dictionary.txt",
      linters = {
        SpellCheck = true,
        SpelledNumbers = false,
        AnA = true,
        SentenceCapitalization = false,
        UnclosedQuotes = true,
        WrongApostrophe = false,
        LongSentences = true,
        RepeatedWords = true,
        Spaces = true,
        CorrectNumberSuffix = true
      }
    }
  }
})

Neovim 0.11 이상 네이티브 LSP API를 쓸 때는 vim.lsp.config['harper']를 구성하고 vim.lsp.enable('harper')를 호출합니다. VS Code 사용자는 elijah-potter.harper 확장 프로그램을 설치한 뒤 .vscode/settings.json에 "harper.path": "/usr/local/bin/harper-ls" 경로를 지정하면 끝납니다.

실행 코드 제외 및 검사 범위 제어

Harper는 Tree-sitter AST 파서를 내장하고 있어서 실제 소스 코드는 넘어가고 주석 블록 내 영문 텍스트만 골라 검사합니다. 특정 함수 주석을 검사 대상에서 완전히 빼고 싶다면 인라인 지시어를 넣습니다.

// harper:ignore
function processInternalSecurityToken() {
  // spellcheck:ignore
  // 내부 보안 토큰 로직
}

2. 프로젝트 커스텀 사전으로 오탐 제어

기본 영단어 사전만 돌리면 gRPC, OAuth2, Prometheus 같은 기술 용어를 전부 오류로 판단합니다. 계층형 사전 구조를 활용하면 경고 소음을 빠르게 제거할 수 있습니다.

4단계 사전 구조

Harper는 4개 계층으로 단어를 검증합니다.

사전 계층	저장 위치	목적
Static Dictionary	`harper-ls` 바이너리 내장	수정 불가능한 기본 영단어 DB
User Dictionary	`~/.config/harper-ls/dictionary.txt`	개인 개발 환경용 전역 사전
Workspace Dictionary	프로젝트 루트 `.harper-dictionary.txt`	프로젝트 전용 용어 사전 (Git 관리)
File-Local Dictionary	OS 데이터 경로 내 저장	단일 파일 전용 식별자 저장

도메인 용어 등록과 공유

프로젝트 루트 디렉터리에 .harper-dictionary.txt 파일을 만듭니다.
자주 쓰는 기술 용어를 줄바꿈으로 적어줍니다.

Kubernetes
gRPC
OAuth2
OpenTelemetry
Prometheus
mTLS
Netty
Etcd

에디터에서 오탐 경고가 떠도 당황할 필요 없습니다. Code Action 기능(VS Code: Ctrl + ., Neovim: Code Action 키 바인딩)을 눌러 해당 단어를 .harper-dictionary.txt에 바로 추가하면 됩니다.

이 파일만 Git 저장소에 올리면 팀원 모두가 동일한 단어 목록을 공유합니다.

린터 규칙 조정

주석 작성 시 번거로운 규칙은 끕니다.

SentenceCapitalization: 주석 첫 글자 대문자 강제 규칙을 끄려면 false로 설정합니다.
LongSentences: 기술 문서 특성상 길어지는 문장 경고를 끄려면 false로 설정합니다.
SpellCheck 및 UnclosedQuotes: 철자 오류와 따옴표 닫힘 검사는 true로 둡니다.

3. GitHub Actions 기반 CI/CD 파이프라인 연동

개발자가 에디터에서 놓친 오타는 PR 단계에서 차단해야 합니다. CLI 도구인 harper-cli를 파이프라인에 연결하면 메인 브랜치 병합 전에 문법 오류를 자동으로 걸러냅니다.

GitHub Actions 워크플로 구성

.github/workflows/harper-lint.yml 파일에 변경된 마크다운만 골라 검사하는 작업을 정의합니다.

name: Technical Documentation Linting

on:
  pull_request:
    paths:
      - 'docs/<strong>'
      - '</strong>.md'

jobs:
  harper-grammar-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Rust Toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache Harper CLI Binary
        uses: actions/cache@v3
        with:
          path: ~/.cargo/bin/harper-cli
          key: ${{ runner.os }}-harper-cli-${{ hashFiles('**/Cargo.lock') }}

      - name: Install Harper CLI
        run: |
          if ! command -v harper-cli &> /dev/null; then
            cargo install harper-cli --locked
          fi

      - name: Get Changed Markdown Files
        id: changed-files
        run: |
          git fetch origin ${{ github.base_ref }}
          FILES=$(git diff --name-only --diff-filter=AM origin/${{ github.base_ref }} HEAD | grep '\.md$' || true)
          echo "files=$FILES" >> $GITHUB_OUTPUT

      - name: Run Harper Lint Check
        if: steps.changed-files.outputs.files != ''
        run: |
          ERRORS=0
          for file in ${{ steps.changed-files.outputs.files }}; do
            echo "Linting $file with Harper..."
            harper-cli lint "$file" || ERRORS=$((ERRORS+1))
          done
          
          if [ $ERRORS -gt 0 ]; then
            echo "Harper validation failed with $ERRORS error(s)."
            exit 1
          fi

프로젝트 루트의 .harper-dictionary.txt까지 함께 커밋하면 CI 러너도 에디터와 동일한 단어 목록을 기준으로 검사를 진행합니다. MkDocs나 Docusaurus 같은 정적 사이트 생성기(SSG)를 쓴다면 빌드 스크립트 실행 직전에 harper-cli lint docs/ 명령을 수행하도록 설정해 두는 편이 안전합니다.

외부 유출 없는 오프라인 문법 검사기 Harper 구축 방법

1. 개발 환경 설치와 에디터 LSP 연동

패키지 설치

터미널에서 명령어를 실행해 바이너리를 설치합니다.

macOS / Linux: brew install harper
Rust 환경: cargo install harper-ls --locked
Windows: scoop install harper

Neovim 및 VS Code 연동

Neovim에서는 nvim-lspconfig로 대상 파일 타입과 린터 규칙을 설정합니다.

local lspconfig = require('lspconfig')

lspconfig.harper_ls.setup({
  filetypes = { 'markdown', 'gitcommit', 'rust', 'go', 'typescript', 'python' },
  settings = {
    ["harper-ls"] = {
      userDictPath = "~/config/harper/user_dict.txt",
      workspaceDictPath = ".harper-dictionary.txt",
      linters = {
        SpellCheck = true,
        SpelledNumbers = false,
        AnA = true,
        SentenceCapitalization = false,
        UnclosedQuotes = true,
        WrongApostrophe = false,
        LongSentences = true,
        RepeatedWords = true,
        Spaces = true,
        CorrectNumberSuffix = true
      }
    }
  }
})

실행 코드 제외 및 검사 범위 제어

// harper:ignore
function processInternalSecurityToken() {
  // spellcheck:ignore
  // 내부 보안 토큰 로직
}

2. 프로젝트 커스텀 사전으로 오탐 제어

4단계 사전 구조

Harper는 4개 계층으로 단어를 검증합니다.

사전 계층	저장 위치	목적
Static Dictionary	`harper-ls` 바이너리 내장	수정 불가능한 기본 영단어 DB
User Dictionary	`~/.config/harper-ls/dictionary.txt`	개인 개발 환경용 전역 사전
Workspace Dictionary	프로젝트 루트 `.harper-dictionary.txt`	프로젝트 전용 용어 사전 (Git 관리)
File-Local Dictionary	OS 데이터 경로 내 저장	단일 파일 전용 식별자 저장

도메인 용어 등록과 공유

프로젝트 루트 디렉터리에 .harper-dictionary.txt 파일을 만듭니다.
자주 쓰는 기술 용어를 줄바꿈으로 적어줍니다.

Kubernetes
gRPC
OAuth2
OpenTelemetry
Prometheus
mTLS
Netty
Etcd

에디터에서 오탐 경고가 떠도 당황할 필요 없습니다. Code Action 기능(VS Code: Ctrl + ., Neovim: Code Action 키 바인딩)을 눌러 해당 단어를 .harper-dictionary.txt에 바로 추가하면 됩니다.

이 파일만 Git 저장소에 올리면 팀원 모두가 동일한 단어 목록을 공유합니다.

린터 규칙 조정

주석 작성 시 번거로운 규칙은 끕니다.

SentenceCapitalization: 주석 첫 글자 대문자 강제 규칙을 끄려면 false로 설정합니다.
LongSentences: 기술 문서 특성상 길어지는 문장 경고를 끄려면 false로 설정합니다.
SpellCheck 및 UnclosedQuotes: 철자 오류와 따옴표 닫힘 검사는 true로 둡니다.

3. GitHub Actions 기반 CI/CD 파이프라인 연동

GitHub Actions 워크플로 구성

.github/workflows/harper-lint.yml 파일에 변경된 마크다운만 골라 검사하는 작업을 정의합니다.

name: Technical Documentation Linting

on:
  pull_request:
    paths:
      - 'docs/<strong>'
      - '</strong>.md'

jobs:
  harper-grammar-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Rust Toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache Harper CLI Binary
        uses: actions/cache@v3
        with:
          path: ~/.cargo/bin/harper-cli
          key: ${{ runner.os }}-harper-cli-${{ hashFiles('**/Cargo.lock') }}

      - name: Install Harper CLI
        run: |
          if ! command -v harper-cli &> /dev/null; then
            cargo install harper-cli --locked
          fi

      - name: Get Changed Markdown Files
        id: changed-files
        run: |
          git fetch origin ${{ github.base_ref }}
          FILES=$(git diff --name-only --diff-filter=AM origin/${{ github.base_ref }} HEAD | grep '\.md$' || true)
          echo "files=$FILES" >> $GITHUB_OUTPUT

      - name: Run Harper Lint Check
        if: steps.changed-files.outputs.files != ''
        run: |
          ERRORS=0
          for file in ${{ steps.changed-files.outputs.files }}; do
            echo "Linting $file with Harper..."
            harper-cli lint "$file" || ERRORS=$((ERRORS+1))
          done
          
          if [ $ERRORS -gt 0 ]; then
            echo "Harper validation failed with $ERRORS error(s)."
            exit 1
          fi

외부 유출 없는 오프라인 문법 검사기 Harper 구축 방법

관련 영상

Harper: Rust로 제작된 무료 개인정보 보호 Grammarly 대체 프로그램

외부 유출 없는 오프라인 문법 검사기 Harper 구축 방법

1. 개발 환경 설치와 에디터 LSP 연동

패키지 설치

Neovim 및 VS Code 연동

실행 코드 제외 및 검사 범위 제어

2. 프로젝트 커스텀 사전으로 오탐 제어

4단계 사전 구조

도메인 용어 등록과 공유

린터 규칙 조정

3. GitHub Actions 기반 CI/CD 파이프라인 연동

GitHub Actions 워크플로 구성

커뮤니티의 다른 글

사내 시스템에 llm api 붙일 때 마주하는 현실적인 한계와 대응법

레거시 백엔드에 GPT-6 Astra 붙일 때 예산 승인과 보안 통과를 먼저 끝내는 법이 있습니다

에이전트끼리 대화하다 6천만 원 청구서가 나오는 이유

사내 RAG 벡터 검색에 Okta 권한 필터를 직접 거는 방법

브라우저 에이전트에게 내 구글 계정을 통째로 넘기면 안 되는 이유

Apple Won the AI Race

댓글 (0)

외부 유출 없는 오프라인 문법 검사기 Harper 구축 방법

1. 개발 환경 설치와 에디터 LSP 연동

패키지 설치

Neovim 및 VS Code 연동

실행 코드 제외 및 검사 범위 제어

2. 프로젝트 커스텀 사전으로 오탐 제어

4단계 사전 구조

도메인 용어 등록과 공유

린터 규칙 조정

3. GitHub Actions 기반 CI/CD 파이프라인 연동

GitHub Actions 워크플로 구성