biome

biome — SKILL.md

バリアント： 標準 · 使用する場面： Biome v2 で JS/TS プロジェクトのリンティングとフォーマットを行うとき。

概要

Biome は、JavaScript、TypeScript、JSX、JSON、CSS、GraphQL のリンティング、フォーマット、インポートの整理を行う単一の Rust バイナリです。ESLint + Prettier の構成を、1 つのツールと 1 つの biome.json で置き換えます。Python の ruff に相当する JS/TS 向けツールであり、高速で、明確なデフォルト設定と単一の設定ファイルが特徴です。このスキルでは、Biome（v2）のインストール、biome.json の記述、現在の CLI（biome ci によるゲートを含む）、既存の ESLint/Prettier 構成からの移行、古い知識では混乱しやすい v1→v2 の変更点、GritQL プラグインとしてのカスタム lint ルールの作成を扱います。Biome v2 で検証済みです。インストール時に正確な最新バージョンを確認してください。

使用するタイミング

• ✅ JS/TS プロジェクトに lint + format を追加するとき（新規、または ESLint/Prettier からの置き換え）。
• ✅ biome.json（フォーマッター、リンタールール、インポートの整理、VCS、オーバーライド）を作成または修正するとき。
• ✅ lint/format の CI ゲートを設定するとき。
• ✅ ESLint/Prettier から移行するとき、または GritQL プラグインとしてカスタムルールを作成するとき。

次の場合は有効にしないでください：

• Turborepo/pnpm パイプラインのタスクとして Biome を設定する必要がある場合 — turborepo スキルと組み合わせてください。このスキルが扱うのは Biome 自体であり、タスクグラフではありません。
• プロジェクトが Python の場合 — その場合は ruff を使用してください（Biome は JS/TS 向けの相当ツールであり、ここでは類似性を示すためにのみ言及しています）。

ワークフロー

ステップ 1：インストール + 初期化

npm install --save-dev --save-exact @biomejs/biome   # i.e. -D -E
npx biome init                                        # writes biome.json

ステップ 2：biome.json を設定する

{
  "$schema": "https://biomejs.dev/schemas/<version>/schema.json",
  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
  "files": { "includes": ["src/**", "!**/dist"] },
  "formatter": { "enabled": true, "indentStyle": "space", "lineWidth": 100 },
  "linter": { "enabled": true, "rules": { "recommended": true } },
  "assist": { "enabled": true, "actions": { "source": { "organizeImports": "on" } } }
}

（biome init は、バージョンを固定した URL を含む $schema を書き込みます。<version> という文字列をそのまま出荷しないでください。）ルールグループと linter.domains、言語ブロック、overrides、モノレポの extends/root を含むスキーマ全体については、references/config.md を参照してください。

ステップ 3：実行する

npx biome check --write .          # lint + format + organize imports, apply SAFE fixes
npx biome check --write --unsafe . # also apply unsafe fixes
npx biome format --write .         # format only;  npx biome lint .  # lint only

biome check は 3 つすべて（フォーマット、lint、インポートのソート）を実行します。コマンドとフラグの完全なリファレンス、および v1→v2 の CLI 変更点については、references/cli.md を参照してください。

ステップ 4：CI ゲート

npx biome ci .     # read-only: format + lint + import-sort checks, never writes

CI では biome ci を使用してください（ruff check に相当します）。変更を加える check --write は決して使用しないでください。lint/format ジョブとして設定し、パイプラインとキャッシュの設定は turborepo スキルに任せてください。

ステップ 5：ESLint / Prettier から移行する（該当する場合）

npx biome migrate eslint --write     # ports .eslintrc / flat config + .eslintignore
npx biome migrate prettier --write   # ports .prettierrc

詳細と注意事項については、references/migration-monorepo.md を参照してください。

ステップ 6：カスタムルール（任意）— GritQL プラグイン

.grit プラグインを biome.json の plugins に登録し、パターンを記述します。パターン構文、register_diagnostic、完全な例、制限事項を含む作成ガイド全体については、references/gritql-plugins.md を参照してください。まず組み込みルールの使用を検討し、該当するルールがない場合にのみプラグインを使用してください。

ルール

必ず守るルール（例外なし）：

• v2 CLI を使用すること。 修正を適用するには --write / --write --unsafe を使用します。v1 の --apply / --apply-unsafe は廃止されています。--apply の出力は、古い知識に起因する最大の誤りです。落とし穴を参照してください。
• CI ゲートには check --write ではなく biome ci を使用すること。 CI は読み取り専用でなければなりません。check --write はツリーを変更します。
• プロジェクトごとに biome.json を 1 つ使用すること（ネストした設定やモノレポの設定には extends を使用してください）。同じ目的で ESLint/Prettier も実行しないでください。Biome がこれらを置き換えます。

推奨事項（変更可）：

• Biome のフォーマッターは、デフォルトで タブ、幅 2 スペース、lineWidth 80 を使用します。チームの標準がスペースの場合（例：Prettier から移行する場合）は、formatter.indentStyle / lineWidth を明示的に設定してください。
• Biome が .gitignore を尊重するよう、vcs.useIgnoreFile を有効にしてください。
• rules.recommended から始め、必要に応じてルールグループごとに厳格化してください。

注意点

• --apply は削除されました（v1→v2）。 v1では biome check --apply ／ --apply-unsafe を使用していましたが、v2では --write ／ --write --unsafe を使用します（--fix は --write のエイリアスです）。古いコード例や以前の操作の癖で --apply を指定すると、現在はエラーになります。詳しくは references/cli.md を参照してください。
• インポートの整理方法が変わりました。 v1のトップレベル設定 organizeImports は廃止され、v2では assist.actions.source.organizeImports の下にあるアシストアクションになりました。v1形式の設定では、インポートは整理されません。
• include／ignore から includes に変更されました（v2）。 v2の files.includes は、! を先頭に付けた否定パターンを含む単一の glob リストで、v1の個別の include／ignore に代わるものです。v1形式の files ブロックは正しくありません。
• フォーマッターのデフォルトはタブです。 スペースを想定している Prettier ユーザーは、indentStyle: "space" を設定しないとタブが使われます。biome migrate prettier を実行すると設定が引き継がれますが、新規に biome init を実行しても引き継がれません。
• GritQL プラグインが対象にできるのは、現時点では JavaScript と CSS のみです。 ほかの言語用のプラグインは動作しません。

アンチパターン

• 同じファイルに ESLint ＋ Prettier と Biome の両方を実行する。 ツールが重複し、修正が競合して、処理が遅くなります。Biome はこれらに置き換わるものです。併用するのではなく、移行してください。
• CI で biome check --write を実行する。 CI がツリーを変更し、差分を見えにくくするおそれがあります。biome ci を使用してください。
• 組み込みルールがあるのに GritQL プラグインを使う。 まずルールグループを確認してください。プラグインは、本当に独自のチェックが必要な場合に使用します。
• ここで Turborepo のパイプラインを重複して定義する。 Biome をキャッシュ対象のタスクとして接続する設定は turborepo スキルの担当です。このスキルの範囲は Biome コマンドまでです。

出力

設定済みの biome.json と、ローカル（biome check --write）および CI（biome ci）で接続された lint／format コマンドです。必要に応じて ESLint／Prettier の設定から移行し、独自の GritQL ルールを追加できます。これらを使うのは、整合性が保たれ lint エラーのないコードベースを維持する開発ワークフローと CI ゲートです。

関連項目

• turborepo — biome ci／check をキャッシュ対象のパイプラインタスクとして実行します。このスキルは Biome を担当し、そちらはタスクグラフを担当します。
• vite — lint／format 済みのコードを通常ビルドするツールです。
• ruff — Biome が概念的に対応する Python の lint＋format ツールです（別のツールです）。

段階的な開示

• references/config.md — biome.json を記述する際に読み込みます。トップレベルのスキーマ全体、formatter／linter／assist の各オプション、ルールグループ、overrides、モノレポの extends／root、v2での設定形式の変更を説明しています。
• references/cli.md — Biome の実行時や CI の接続時に読み込みます。すべてのコマンドとフラグ、--write／ci の動作、v1→v2 の CLI 差分表を説明しています。
• references/gritql-plugins.md — 独自ルールを作成する際に読み込みます。プラグインの登録、GritQL パターン構文、register_diagnostic、完全な例、制限事項を説明しています。
• references/migration-monorepo.md — ESLint／Prettier からの移行時や、モノレポの設定時に読み込みます。migrate コマンドと注意事項、extends／root によるモノレポモデルを説明しています。
• references/sources.md — 調査の出典情報です。

本文の上限

• description は 1,024 文字以下、本文は約 500 行／5,000 トークン以下にしてください。大きな内容は references/ に置いてください。