Claude CodeでPrettier設定を整える実践ガイド

Claude Codeに実装を任せるほど、コードの見た目は「あとで直せばいい小さな問題」ではなくなります。1回の作業でコンポーネント、テスト、設定ファイル、ドキュメントが同時に変わるため、インデントや改行の差分が混ざるとレビューで本当に見たい変更が埋もれます。

Prettierは、コードの見た目を自動でそろえるフォーマッタです。フォーマッタとは、動作を変えずに空白、改行、引用符、末尾カンマなどの表記を機械的に整えるツールのことです。Claude Codeを使うなら、人間の好みを毎回プロンプトで説明するより、リポジトリにPrettier設定を置き、Claude Codeにもその設定を読ませる方が安定します。

この記事では、npmプロジェクトにPrettierを入れ、.prettierrc、.prettierignore、package.json scripts、VS Code設定、CI、staged formatting、Claude Code用の指示までを一通り整えます。手元の小さなAstro/TypeScriptリポジトリで実際にコマンドを流し、コピーして使える構成だけに絞りました。

全体像

まず、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で再チェック"]

役割は分けて考えると迷いません。.prettierrcはチームの見た目のルール、.prettierignoreは触らないファイルのルール、package.json scriptsは人間とCIが同じコマンドを使うための入口です。VS Codeは作業中の即時フィードバック、lint-stagedはコミット直前の保険、CIはレビュー前の最終確認です。

Claude Codeには「整形して」と毎回頼むだけでは足りません。Claude Codeは文脈にある指示を守りますが、実際に存在する設定ファイルと検証コマンドがある方がはるかに確実です。公式ドキュメントでも、Claude CodeのCLAUDE.mdはプロジェクトのコマンド、コーディング標準、共通ワークフローを書く場所として説明されています。

Prettierをローカルにインストールする

Prettierはグローバルではなく、プロジェクトのdevDependenciesに固定して入れます。公式のPrettier Installでも、ローカルインストールとバージョン固定が推奨されています。理由は単純で、開発者のPC、Claude Codeの実行環境、CIで同じバージョンを使いたいからです。

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

初回だけ全体を整形します。

npx prettier . --write

既存プロジェクトでは、このコマンドを機能追加の差分と混ぜないでください。最初に「Prettier導入だけ」の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の改行差分を減らすために入れています。trailingComma: "all"は、配列やオブジェクトに項目を追加したときの差分を小さくしやすい設定です。

もしTailwind CSSのクラス順を自動整理したいなら、別途prettier-plugin-tailwindcssを検討します。ただし、最初からプラグインを増やしすぎると原因切り分けが難しくなります。まず素のPrettierで安定させ、必要が出てから追加する方が安全です。

.prettierignoreで触らないファイルを決める

.prettierignoreは、Prettierに整形させないファイルを指定するリストです。生成物、ビルド成果物、キャッシュ、ロックファイルなどは、人間やClaude Codeが読みやすくする目的で整形する必要がありません。

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にも明示しておくと、Claude Codeにも意図が伝わりやすくなります。

失敗例として、src/generated/やAPIクライアントの自動生成コードを無視し忘れるケースがあります。Claude Codeが小さな修正をしただけなのに、生成コードが数千行整形されるとレビュー不能になります。生成コードは、生成元のスキーマやOpenAPI定義を直して再生成するのが基本です。

package.json scriptsをそろえる

npmのpackage.json documentationでは、scriptsはプロジェクトで実行するコマンドを定義する場所です。人間、Claude Code、CIが同じ名前のコマンドを使えるようにしておくと、作業の再現性が上がります。

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

普段の修正後は次の2つを使い分けます。

npm run format
npm run format:check

formatは実際にファイルを書き換えます。format:checkは、未整形のファイルがあるかだけを確認します。CIではformat:checkだけを使い、CI上で自動修正しないのが分かりやすいです。CIが勝手にコミットを直す構成も作れますが、初心者チームでは「落ちたら手元でnpm run format」の方がトラブルが少ないです。

VS Codeで保存時に整形する

エディタで保存時に整形できると、Claude Codeが作った差分を人間が軽く直す場面でも同じルールを保てます。VS Codeでは、ワークスペースに.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設定ガイドと組み合わせてnpm run lintも別ジョブで実行します。

staged formattingを入れる

大きなリポジトリでは、毎回prettier . --writeを実行すると時間がかかります。コミット対象だけ整形したい場合は、Huskyとlint-stagedを使います。詳しいGit hook運用はHusky + lint-staged設定ガイドで扱っていますが、Prettierだけならこの最小構成で始められます。

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

package.jsonにlint-staged設定を追加します。

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

.husky/pre-commitは次のようにします。

npx lint-staged

staged formattingの利点は、Claude Codeが触っていない古いファイルまで急に整形しないことです。既存コードの整形負債が大きいリポジトリでは、これだけでレビューのノイズがかなり減ります。

Claude Codeにルールを守らせる

Claude Codeには、口頭で「Prettierに合わせて」と頼むだけでなく、リポジトリ内の指示として残します。公式のClaude Code memory documentationでは、./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には、PostToolUseのEdit|Write後にPrettierを走らせる例があります。

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

このhookは便利ですが、jqとシェル環境に依存します。Windows中心のチームでは、まずCLAUDE.mdにコマンドを明記し、Claude Codeの作業終わりにnpm run format:checkを実行させる運用から始める方が堅いです。hookは、チーム全員の環境で同じように動くことを確認してから共有設定に入れてください。

3つのユースケース

ユースケース	何が嬉しいか	Claude Codeへの頼み方
TypeScriptアプリ	コンポーネント、テスト、型定義の差分が読みやすい	変更後に npm run format:check を実行して
AstroやMDXブログ	記事、frontmatter、JSON設定の表記がそろう	本文だけでなくMDXのコードフェンスも崩れていないか確認して
チーム開発のPR	レビューで機能差分だけを見やすい	フォーマットだけの差分を混ぜないで

私が特に効果を感じるのは、MDX記事をClaude Codeで直す場面です。文章、コード例、YAML風のfrontmatterが同じファイルに入るため、手作業だと空白や引用符が揺れます。Prettierを通すと見た目の揺れが減り、記事の正確性や構成に集中できます。

よくある落とし穴

1つ目は、npx prettier . --writeだけを使い、Prettierを依存関係に入れないことです。毎回その時点の最新版を一時取得すると、ある日突然整形結果が変わる可能性があります。必ず--save-exactでローカルに固定します。

2つ目は、ESLintとPrettierの責務を混ぜることです。Prettierは見た目、ESLintはバグや品質ルールを担当します。ESLint側にフォーマット系ルールが残っていると衝突しやすいので、必要に応じてeslint-config-prettierで競合ルールを無効化します。

3つ目は、機能変更と全体整形を同じPRに入れることです。Claude Codeに大きなリファクタリングを頼む前に、整形だけの差分を先に片付けてください。これはレビュー時間だけでなく、バグが入ったときの原因調査にも効きます。

4つ目は、.prettierignoreを広くしすぎることです。src/**のように主要コードを無視すると、Prettierを入れた意味がなくなります。無視するのは生成物、キャッシュ、巨大ファイル、外部ツールが管理するファイルに絞ります。

収益化につなげるなら

Claude Codeを個人開発やチーム導入で使うなら、Prettier設定だけでなく、CLAUDE.md、レビュー手順、検証チェックリスト、PRテンプレートまでまとめておくと再利用できます。ClaudeCodeLabでは、そうした運用テンプレートをプロダクトページに整理しています。この記事の設定を自分のリポジトリで試したあと、チーム標準に落とし込む材料として使ってください。

まとめ

Prettier設定は、Claude Code時代の小さな基盤です。.prettierrcでルールを固定し、.prettierignoreで触らない場所を決め、npm run formatとnpm run format:checkを用意し、VS Code、staged formatting、CIに同じルールを通します。最後にCLAUDE.mdへ「このプロジェクトではどう整形するか」を書くと、Claude Codeの出力も人間の作業も同じ線に乗ります。

この記事で紹介した内容を実際に試した結果、既存の小さなTypeScript/MDXプロジェクトでは、初回の全体整形後にnpm run format:checkが安定して通り、Claude Codeに記事修正を頼んだ後のレビュー差分も読みやすくなりました。特に.prettierignoreで生成物を外したことと、format:checkをCI向けに分けたことが効きました。