Claude Code와 Prettier 설정 실전 가이드

Claude Code에 구현을 맡기기 시작하면 코드 포맷은 사소한 취향 문제가 아닙니다. 한 번의 작업에서 컴포넌트, 테스트, JSON, Markdown, CI 설정이 함께 바뀔 수 있습니다. 이때 들여쓰기, 따옴표, 줄바꿈, trailing comma가 제각각이면 리뷰어는 실제 기능 변경보다 형식 차이를 먼저 해석해야 합니다.

Prettier는 코드의 모양을 자동으로 맞추는 formatter입니다. formatter는 코드의 동작을 판단하는 도구가 아니라, 공백과 줄바꿈, 인용부호, 쉼표 같은 표현을 일관되게 정리하는 도구입니다. Claude Code가 코드를 잘 작성하더라도, 프로젝트 안에 명확한 Prettier 설정이 있어야 결과가 매번 안정적입니다.

이 글에서는 npm 기반 JavaScript/TypeScript 프로젝트를 기준으로 Prettier를 설정합니다. 설치, .prettierrc, .prettierignore, package.json scripts, VS Code 설정, CI 확인, staged formatting, 그리고 Claude Code가 지켜야 할 프로젝트 지시까지 한 번에 정리합니다.

전체 흐름

Prettier는 마지막에 떠올리는 정리 명령이 아니라 개발 흐름 곳곳에 들어가는 작은 품질 장치로 보는 것이 좋습니다.

flowchart LR
  A["Claude Code가 파일 수정"] --> B[".prettierrc가 규칙 정의"]
  B --> C["VS Code 저장 시 포맷"]
  C --> D["npm run format:check"]
  D --> E["lint-staged가 staged files 처리"]
  E --> F["CI가 PR에서 확인"]

.prettierrc는 팀의 포맷 규칙입니다. .prettierignore는 건드리지 말아야 할 파일 목록입니다. package.json scripts는 사람, Claude Code, CI가 같은 명령을 쓰게 해주는 입구입니다. VS Code는 작성 중 피드백을 주고, lint-staged는 커밋 대상만 정리하며, CI는 리뷰 전에 마지막으로 확인합니다.

Claude Code에게 매번 “포맷도 맞춰줘”라고 말하는 방식은 약합니다. 저장소에 규칙 파일과 검증 명령을 두면, 새 세션에서도 같은 기준을 따르게 만들 수 있습니다.

Prettier 로컬 설치

Prettier는 전역 설치보다 프로젝트 로컬 devDependency로 고정하는 것이 안전합니다. 공식 Prettier Install 문서는 로컬 설치와 정확한 버전 고정을 안내합니다. 개발자 PC, Claude Code 실행 환경, CI가 같은 포맷터 버전을 써야 불필요한 diff를 줄일 수 있습니다.

npm install --save-dev --save-exact prettier

처음 도입할 때는 한 번 전체 포맷을 실행합니다.

npx prettier . --write

이미 운영 중인 프로젝트라면 이 전체 포맷은 기능 변경과 분리하세요. formatter-only 커밋 또는 PR을 먼저 만들고, 그다음부터 Claude Code에게 기능 작업을 맡기면 리뷰가 훨씬 단순해집니다.

.prettierrc 작성

Prettier 설정은 .prettierrc, prettier.config.mjs, package.json의 prettier 키 등으로 둘 수 있습니다. 공식 Configuration File 문서에 따르면 Prettier는 포맷 대상 파일 위치에서 위쪽 디렉터리로 설정을 찾고, 전역 설정을 지원하지 않습니다. 이 덕분에 프로젝트를 다른 컴퓨터로 옮겨도 같은 결과를 기대할 수 있습니다.

처음에는 JSON 기반 .prettierrc가 가장 읽기 쉽습니다.

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "proseWrap": "always"
      }
    },
    {
      "files": ["*.yml", "*.yaml"],
      "options": {
        "singleQuote": false
      }
    }
  ]
}

printWidth는 반드시 그 길이에서 줄을 끊는 제한이 아니라 Prettier가 줄바꿈을 판단할 때 쓰는 기준입니다. endOfLine: "lf"는 Windows, macOS, Linux, CI 사이의 줄바꿈 차이를 줄입니다. trailingComma: "all"은 배열이나 객체에 새 항목을 추가할 때 diff를 작게 만드는 데 도움이 됩니다.

Tailwind CSS 프로젝트라면 나중에 prettier-plugin-tailwindcss를 고려할 수 있습니다. 다만 처음부터 plugin을 많이 넣으면 문제 원인을 찾기 어렵습니다. 먼저 기본 Prettier가 안정적으로 통과하는 상태를 만든 뒤 필요한 plugin만 추가하세요.

.prettierignore 정리

.prettierignore는 Prettier가 수정하지 않을 파일을 지정합니다. 빌드 결과물, 캐시, 생성 코드, 압축된 파일, package manager가 관리하는 lockfile은 일반적인 포맷 대상이 아닙니다.

node_modules
dist
build
coverage
.next
.nuxt
.astro
.vercel
.cache
*.min.js
package-lock.json
pnpm-lock.yaml
yarn.lock

Prettier는 실행 위치의 .gitignore도 참고합니다. 하지만 .gitignore는 Git 추적 여부, .prettierignore는 포맷 여부를 결정합니다. 목적이 다르므로 생성물과 큰 파일은 .prettierignore에 명확히 남겨두는 편이 좋습니다.

실패 사례로는 자동 생성 API client를 빼먹는 경우가 많습니다. Claude Code가 작은 UI 수정만 했는데 src/generated/ 아래 수천 줄이 포맷되면 리뷰가 어려워집니다. 생성 파일은 원본 schema를 수정하고 다시 생성하는 방식으로 관리하세요.

package.json scripts 추가

npm 공식 문서에서 scripts는 package 안에 실행 명령을 정의하는 위치입니다. Claude Code 워크플로에서는 이 이름이 중요합니다. 사람도, agent도, CI도 같은 명령을 쓰게 만들 수 있기 때문입니다.

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

로컬 수정에는 format, 자동 검증에는 format:check를 씁니다.

npm run format
npm run format:check

format은 파일을 실제로 고칩니다. format:check는 이미 포맷되어 있는지만 확인하고 실패 코드를 반환합니다. CI에서는 format:check만 실행하는 구성이 가장 이해하기 쉽습니다. 실패하면 로컬에서 npm run format을 실행한 뒤 수정 diff를 다시 올리면 됩니다.

VS Code 저장 시 포맷

에디터 저장 시 포맷을 켜두면 commit 전에 흔들림을 줄일 수 있습니다. 개인 설정에 맡기지 말고 저장소의 .vscode/settings.json에 워크스페이스 설정을 두세요.

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true,
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[mdx]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

prettier.requireConfig가 true이면 Prettier 설정이 있는 프로젝트에서만 확장이 동작합니다. 여러 저장소를 오가는 개발자에게 특히 중요합니다. Prettier를 쓰지 않는 저장소에서 의도치 않은 포맷 변경이 생기는 일을 막을 수 있습니다.

CI에서 포맷 확인

GitHub Actions에서는 다음 정도면 시작하기 충분합니다.

name: format

on:
  pull_request:
  push:
    branches: [main]

jobs:
  prettier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run format:check

Claude Code가 PR까지 만드는 흐름에서는 CI의 format:check가 큰 역할을 합니다. 리뷰어가 보기 전에 기계가 단순한 포맷 누락을 잡아 줍니다. 더 넓은 품질 검사는 Claude Code ESLint 설정 가이드를 함께 사용하되, formatter와 linter 실패는 분리해서 보여주는 것이 좋습니다.

staged files만 포맷

큰 저장소에서 매번 전체 포맷을 돌리면 느리고 불필요한 diff가 생길 수 있습니다. Husky와 lint-staged를 쓰면 git add된 파일만 포맷할 수 있습니다. 전체 pre-commit 설계는 Husky + lint-staged 설정 가이드를 참고하고, 여기서는 최소 구성만 봅니다.

npm install --save-dev --save-exact husky lint-staged
npm pkg set scripts.prepare="husky"
npx husky init

package.json에는 다음을 추가합니다.

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,css,md,mdx,json,yml,yaml}": "prettier --write"
  }
}

.husky/pre-commit은 단순하게 유지합니다.

npx lint-staged

이 구성의 장점은 범위 제어입니다. Claude Code가 세 파일만 고쳤다면 commit 직전에도 그 세 파일만 포맷됩니다. 오래된 파일 전체가 갑자기 바뀌지 않습니다.

Claude Code에 규칙 전달

Claude Code가 매번 같은 방식으로 행동하게 하려면 프로젝트 지시를 CLAUDE.md에 남깁니다. 공식 Claude Code memory 문서는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md를 팀 공유 지시 파일로 설명합니다.

## Formatting

- Read `.prettierrc` and `.prettierignore` before formatting files.
- Do not reformat unrelated files while implementing a feature.
- After changing JavaScript, TypeScript, CSS, Markdown, JSON, or YAML, run `npm run format:check`.
- Keep formatter-only changes separate from behavior changes.

더 자동화하고 싶다면 Claude Code hooks를 쓸 수 있습니다. 공식 hooks guide는 Edit|Write 이후 Prettier를 실행하는 예시를 제공합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

이 hook은 편리하지만 jq와 shell 환경에 의존합니다. Windows 중심 팀이라면 처음에는 CLAUDE.md에 규칙과 npm run format:check만 명확히 적고, 환경이 정리된 뒤 hook을 공유 설정으로 올리는 편이 안전합니다.

세 가지 활용 사례

활용 사례	Prettier가 주는 이점	Claude Code에 줄 지시
TypeScript 제품 앱	컴포넌트, 테스트, 타입 유틸 diff가 읽기 쉬워짐	변경 후 npm run format:check를 실행해
Astro 또는 MDX 콘텐츠	frontmatter, Markdown, code fence, JSON 표기가 안정됨	MDX code fence가 깨지지 않았는지 확인해
팀 PR 리뷰	리뷰어가 기능 변경에 집중할 수 있음	포맷만의 diff를 기능 변경에 섞지 마

제가 가장 효과를 크게 느끼는 곳은 MDX 문서입니다. 한 파일 안에 본문, frontmatter, shell command, JSON, JSX가 섞이기 때문에 사람이 직접 고치거나 Claude Code가 수정할 때 형식이 쉽게 흔들립니다. Prettier가 있으면 리뷰 초점이 문장, 정확성, 실행 가능한 예시로 돌아옵니다.

흔한 실수

첫 번째 실수는 Prettier를 설치하지 않고 npx prettier . --write만 쓰는 것입니다. 의존성에 고정하지 않으면 어느 날 다른 버전이 실행되어 포맷 결과가 바뀔 수 있습니다.

두 번째는 ESLint와 Prettier가 같은 규칙을 담당하게 두는 것입니다. Prettier는 모양, ESLint는 bug 가능성과 유지보수 규칙을 담당하게 나누세요. 충돌한다면 eslint-config-prettier로 포맷 관련 ESLint 규칙을 끄는 것을 검토합니다.

세 번째는 기능 PR에서 전체 저장소를 포맷하는 것입니다. 기존 코드가 많이 흔들려 있다면 먼저 formatter-only 변경을 만들고, 이후 기능 작업에서 Claude Code가 관련 없는 포맷을 건드리지 않게 해야 합니다.

네 번째는 .prettierignore를 너무 넓게 잡는 것입니다. src/**처럼 주요 코드를 통째로 제외하면 formatter를 도입한 의미가 사라집니다. 생성물, 캐시, 큰 파일, 외부 도구가 관리하는 파일만 제외하세요.

수익화 CTA

Claude Code를 여러 프로젝트에 적용한다면 재사용 가치가 있는 것은 .prettierrc 하나가 아닙니다. CLAUDE.md, 검증 명령, 리뷰 checklist, PR template, handoff 규칙까지 묶인 운영 방식이 자산입니다. ClaudeCodeLab의 products page에는 이런 템플릿을 정리해 두었습니다. 이 글의 설정을 적용한 뒤 팀 표준으로 확장할 때 참고할 수 있습니다.

정리

Prettier는 Claude Code 작업의 작은 기반입니다. 로컬에 고정 설치하고, .prettierrc로 규칙을 정하며, .prettierignore로 제외 범위를 명확히 하고, format과 format:check scripts를 제공합니다. 여기에 VS Code, lint-staged, CI를 연결하고, CLAUDE.md에 같은 기대치를 쓰면 사람과 Claude Code가 같은 규칙 위에서 작업하게 됩니다.

실제로 작은 TypeScript/MDX 프로젝트에 적용해 보니, 첫 전체 포맷 이후 npm run format:check가 안정적으로 통과했고 Claude Code가 만든 문서 수정 diff도 훨씬 읽기 쉬워졌습니다. 특히 생성물을 ignore한 것과 format과 format:check를 분리한 것이 가장 효과적이었습니다.