Claude Code を pnpm モノレポで使いこなす — --filter と dlx の組み合わせ

pnpm のモノレポで Claude Code を使い始めて最初に困るのは、たぶん「なぜか別パッケージのファイルまで触られる」ことではないでしょうか。apps/web の修正を頼んだのに、いつの間にか packages/ui の型定義まで書き換わっている — そんな経験は意外と多くの方がしているはずです。

私もこの問題に何度かやられて、結局のところ pnpm --filter と pnpm dlx の使い分けを Claude Code 側に明示的に教える必要があると気づきました。今回は、この組み合わせを実際にどう設定して、どう運用していくかを順を追って書いていきます。

pnpm --filter で作業範囲をきっちり絞る

pnpm の --filter は、特定のワークスペースに対してだけコマンドを実行するためのフラグです。Claude Code から呼ぶときも考え方は同じで、「このパッケージのことだけお願いします」という意思表示に使います。普段ターミナルで叩いている人にとっては当たり前の話ですが、Claude Code に意図を伝える「言語」として再認識すると効果が変わってきます。

# apps/web のテストだけ実行
pnpm --filter @myorg/web test
 
# packages/ui に依存しているパッケージ全部にテスト
pnpm --filter ...@myorg/ui test
 
# apps 配下のすべてに型チェック
pnpm --filter "./apps/**" typecheck

ポイントは ...@myorg/ui のように ... を前置すると「依存している側」を、@myorg/ui... のように後置すると「依存先」を辿れることです。Claude Code に「packages/ui を変更したら影響を受けるすべてのパッケージのテストを実行してください」と頼むときは、pnpm --filter ...@myorg/ui test を CLAUDE.md か CLAUDE.local.md に書いておくと話が早く進みます。日本語で「依存元」「依存先」と書いてもよいのですが、コマンド構文そのものを見せたほうが Claude Code の解釈ブレが少なくなる印象です。

pnpm dlx の落とし穴 — CI と挙動がずれる瞬間

pnpm dlx は npm の npx と同じく、ローカルにインストールせずにパッケージを実行できる便利な仕組みです。ただし Claude Code から呼ぶときは、いくつか気をつけたい点があります。

# 一見、便利
pnpm dlx prettier --write "src/**/*.ts"

これを Claude Code に毎回叩かせると、CI と挙動がずれることが起きます。理由は dlx が 最新版を取りに行く ためで、ロックファイルに固定された prettier のバージョンとは違う結果が返ってくる可能性があるからです。フォーマット差分でレビューが荒れたり、CI だけ落ちたりしたときに、原因がここだと気づくまでに少し時間がかかります。

私は次のルールに落ち着きました。

• 使い捨てツール（一回だけ叩く CLI） → pnpm dlx で OK。例えば pnpm dlx degit のようにテンプレート展開で一度しか走らないものです
• コードベースに影響するツール（フォーマッター、リンター、ジェネレーター） → 必ず devDependencies に入れて pnpm --filter <pkg> exec <tool> で実行する

CLAUDE.md には「prettier や eslint、typescript は dlx を使わず、各ワークスペースの node_modules の実体を呼ぶこと」と一行書いておきます。これだけで Claude Code の判断ブレがかなり減りました。

.claude/settings.json で運用ルールを固定する

Claude Code のツール権限カスタムポリシーを使うと、「pnpm 関連のコマンドだけ承認なしで実行可」のような設定ができます。モノレポではこれを上手く使うと、確認回数が劇的に減ります。

{
  "permissions": {
    "allow": [
      "Bash(pnpm --filter *:*)",
      "Bash(pnpm install:*)",
      "Bash(pnpm test:*)",
      "Bash(pnpm dlx:*)"
    ],
    "deny": [
      "Bash(pnpm publish:*)",
      "Bash(pnpm -r publish:*)"
    ]
  }
}

deny に pnpm publish を入れているのは、誤って npm レジストリに勝手に公開されないための防御線です。私はこれで一度も事故を起こしていませんが、設定する前にローカルのリリース手順と矛盾しないかは確認してください。リリース作業を Claude Code に任せている方は、ここを allow 側に外すよりも、別途リリース用のセッションで --dangerously-skip-permissions を使うほうが事故が少ない気がします。

CLAUDE.md と CLAUDE.local.md の役割分担

モノレポでもう一つ整理しておきたいのが、ルートの CLAUDE.md と各パッケージの CLAUDE.local.md の使い分けです。私は次のように分けています。

• ルートの CLAUDE.md — 全パッケージ共通の規約。pnpm のフィルター構文、commit メッセージのフォーマット、リリース手順の禁止事項
• 各パッケージの CLAUDE.local.md — そのパッケージ固有の事情。例えば packages/ui なら「Storybook を必ず更新する」「Tailwind の独自プリセットを使う」など

ルートに何でも書こうとすると CLAUDE.md が肥大化して、Claude Code の文脈を圧迫します。逆に各パッケージに分散しすぎると、共通ルールがあちこちにコピペされて保守が大変になります。「3 ヶ所以上で同じことを書いていたらルートに上げる」をしきい値にすると、ちょうどよいバランスに落ち着きました。

共有パッケージ修正からテストまでを一筆書きで

ここまでの組み合わせで何ができるかを、実際のシナリオで示します。packages/ui のボタンコンポーネントに新しい variant を追加するケースです。

# 1. 該当ワークスペースに直接ジャンプ
cd packages/ui
 
# 2. Claude Code に編集してもらう（エディタ内で完結）
 
# 3. 影響範囲のテストを一発実行（依存している側を全部）
pnpm --filter ...@myorg/ui test
 
# 4. ビルドが通るかも一気に確認
pnpm --filter ...@myorg/ui build

Claude Code には「このコンポーネントを変更したら、依存している apps/web と apps/admin のテストも走らせてください」と日本語で伝えるだけで構いません。CLAUDE.md に --filter ... の構文を書いておけば、自然とその構文を使ってテストまで回してくれるようになります。

さらに大規模なリポジトリで運用するなら、Claude Code の monorepo / Turborepo 統合ガイド と組み合わせるとキャッシュも効かせられます。CI の待ち時間が短くなるのはもちろん、ローカルでの繰り返しも軽くなります。コードベースが本格的に大きくなってきたら、Claude Code の大規模コードベース運用 も合わせて読んでおくと、より深いレベルでチューニングしていけるはずです。

次の一手

まずは .claude/settings.json に上記の permissions をコピペするところから始めてみてください。設定そのものは 5 分で済み、次に Claude Code を起動した瞬間から「pnpm 系コマンドの確認ダイアログ」がかなり減ります。1 セッションあたり数十回の "Allow?" を節約できる感覚があり、思考を切らさずに作業できる時間が増えるはずです。

その上で、自分のリポジトリでよく叩くコマンドパターンを CLAUDE.md に 3〜5 行追記すれば、Claude Code は「pnpm モノレポを理解しているメンバー」として動いてくれるようになります。--filter の挙動を頭の中で正しくモデル化するのに、私自身も助けられた一冊です。