Claude Codeでknipを使う — 未使用のexportと依存を削って検証する

knipは、TypeScript/JavaScriptのプロジェクトから未使用のファイル・依存・exportを見つけるリンターです。Claude Codeと組み合わせると、役割がきれいに分かれます。見つけるのはknip、消すのはClaude Code、消して壊れていないかを確かめるのはテストです。

なお、スキルなどClaude Code側の設定の未使用はknipの対象外で、skill-doctorが扱います。この記事は、コードと依存について3者をつなぐ手順を扱います。knipのレポートを渡して削除させる流れ、削る範囲を決める権限設定、誤検出に見える結果の扱い、CIへの残し方まで順に追います。

knipが報告するものと、Claude Codeに渡す意味

knipはエントリーファイルから辿れるモジュールグラフを作り、そこに載らないコードを報告します。未使用ファイルは「プロジェクトのファイル群から、エントリーと解決済みファイルを引いた残り」という定義です。

Claude Codeに「使っていないコードを探して」と頼む方法でも似た結果は出ます。ただ、全ファイルを読ませるとコンテキストを食い、見落としも出ます。grepで探す方式は、動的な参照や設定ファイル経由の利用を取りこぼします。knipに探索を任せ、Claude Codeには結果の判断と編集だけを任せるほうが、作業が小さく収まります。

knipが報告する主な種類は次のとおりです。

自動修正が「なし」の種類は、knipに任せられない判断が絡みます。unlistedの依存をdependenciesとdevDependenciesのどちらに入れるか、重複exportのどちらを消すかは、knip側では決められません。ここはClaude Codeに判断材料を渡して直させる領域です。

knipを入れてレポートを取る

動作にはNode.js v20.19.0以上、またはBunが要ります。導入は雛形ツールが勧められています。

npm init @knip/config
npm run knip

手動で入れるなら、knip と typescript、@types/node を開発依存に加え、package.json の scripts に "knip": "knip" を足します。インストールせず試すだけなら npx knip で動きます。この場合、typescript と @types/node はプロジェクトに入っている前提です。

最初のレポートは、そのまま信じず眺めるだけにします。件数が多すぎる、明らかに使っているファイルが未使用扱いになっている、といったときは、削除の前に設定を直す段階です。

掃除の順番は、ファイル、import、export、依存

報告は上から順に片付けるのが、knipの推奨です。順序は未使用ファイル、解決できないimport、未使用export、未使用依存です。報告は連鎖して出るため、先にファイルが減ると、そのファイルが使っていたexportと依存の報告も自然に減ります。

逆順で進めると、依存を消した後に未使用ファイルの削除でまた依存が浮く、という往復になります。Claude Codeへの指示も、この順に1種類ずつ出すと扱いやすくなります。種類ごとにコミットを分ければ、問題が出たときの切り戻しも1種類単位で済みます。

絞り込みにはフラグが使えます。--files で未使用ファイルだけ、--exports でexportだけ、--dependencies で依存だけに報告を絞れます。

npx knip --files
npx knip --exports
npx knip --dependencies

削らせる前に決める3つ: 権限、検証、ブランチ

削除は元に戻しにくい操作です。Claude Codeに任せる前に、3点を決めます。

1. knipの実行だけを許可し、削除は都度確認にする

.claude/settings.json に、読み取りだけのコマンドを許可として書きます。許可ルールは、書いた形と一致するコマンドだけを通します。たとえば Bash(npm run build) は npm run build --watch には当てはまりません。この性質を使って、レポートの取得だけを許可し、--fix 付きの実行は許可から外します。

{
  "permissions": {
    "allow": [
      "Bash(npx knip)",
      "Bash(npx knip --reporter json)",
      "Bash(npm test *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

このJSONはルールの書き方の例です。テストコマンドは自分のプロジェクトに合わせて置き換えてください。--fix はどの許可にも当てはまらないため、実行のたびに確認が出ます。

2. 検証できる合図を先に置く

Claude Codeのベストプラクティスは、テストやビルドの終了コードなど、会話の中で読める合図をClaudeに持たせることを勧めています。削除作業では、これが「消してもテストが通る」という担保になります。テストが薄いプロジェクトでは、削除の前に型チェックとビルドも合図に加えます。テストが無いコードを先に守る手順はClaude Codeのリファクタリング手順にあります。

CLAUDE.mdには、手順と禁止事項を短く書いておきます。

## 未使用コードの掃除
- `npx knip` の報告を種類ごとに処理する。順番は files、unresolved、exports、dependencies
- 1種類ごとに削除、テスト、ビルドを実行し、通ってからコミットする
- 設定ファイルが参照しているファイルは消さない。疑わしいものは削除せず一覧で報告する
- `ignore` に足して報告を消すのは最後の手段。先に entry と project を見直す

3. 作業ブランチを切る

削除の差分は、種類ごとに見直せる粒度にしておきます。専用ブランチで作業し、git diff で消えたものを確かめてからマージします。自動修正の説明にも、変更の確認と取り消しのためにgitなどのバージョン管理を使うよう注意があります。

レポートを渡して削除させ、テストで担保する

流れは5段階です。

最初の指示は、たとえば次のような形になります。

npx knip の報告を取得して、種類ごとに次の3つに仕分けて。ファイルは編集しないで。
1. 削除してよい(参照がどこにもない根拠を添える)
2. knip の設定漏れが疑わしい(entry や plugin の追加で解消しそうなもの)
3. 判断に迷う(理由を添える)

仕分けを見たうえで、削除に進みます。

仕分けの1だけを対象に、未使用ファイルから削除して。
削除のたびに npm test と npm run build を実行し、結果を貼って。
失敗したら、その削除だけ戻して原因を調べて。コミットは種類ごとに分けて。

「根拠を添える」と頼むのは、確認の手間を減らすためです。Claudeが「このファイルはどこからも参照されていません」と答えたとき、knipの報告に加えてgrepの結果が付いていれば、見直しが早く済みます。

knipの自動修正に任せる選択肢もある

knip --fix を使うと、knip自身が削除を行います。対象は未使用ファイル、未使用exportの export キーワード、使われていないenum・namespaceのメンバー、package.jsonの未使用依存、未使用のcatalogエントリです。ファイルの削除には --allow-remove-files が別に要ります。種類を絞るなら --fix-type です。

npx knip --fix-type exports,types
npx knip --fix --format

--format を付けると、プロジェクトのフォーマッターで変更ファイルを整えられます。対応はBiome、deno fmt、dprint、Prettierです。

自動修正は、機械的に決まる削除には速く確実です。ただし削除するのは export キーワードなど最小限の部分だけで、関数本体は残ります。その後に未使用になった変数やimportが出るため、ESLintやBiomeで直したうえで、knipをもう一度回す流れになります。この繰り返しも、Claude Codeに「lintとknipが両方クリーンになるまで繰り返して」と頼めます。

自動修正とClaude Codeの使い分け

自動修正が扱わない操作は、unlistedの依存や実行ファイルの追加、重複exportの解消です。どれも「どちらが正しいか」を決める必要があるためです。ここをClaude Codeの担当にすると、knipの強みと重ならずに済みます。

誤検出に見えるとき: ignoreの前に設定を見る

knipのドキュメントは、予想外の報告について「モジュールグラフの正直な結果であり、エントリーファイルから到達できなかったという事実」と説明しています。つまり、まず疑うのは設定側です。

未使用ファイルの原因として挙げられているものを、確認の順で並べます。

• 生成ファイルがまだ作られていない(ルート定義を生成するツールなど、knipを実行する前に生成が要る)
• 動的なimportで、パスが文字列から決まる
• スクリプトの引数やファイル形式に、knipが未対応のものがある
• プラグインが無い、または不足している

Claude Codeには、これらの原因を1つずつ照合させます。

仕分けの2について、knip のドキュメントの「未使用ファイルの主な原因」に当てはめて、
どれに当たるか理由を添えて。entry パターンの追加案を knip.json の差分で出して。

本番コードだけを対象にしたいときは、production modeが使えます。knip --production は、設定で ! を付けたエントリーとプロジェクトのパターン、プラグインが出す本番用のエントリー、start スクリプトだけを対象にします。テストコードから参照されているだけのファイルが「使用中」と扱われる状況を、避けられます。デフォルトの実行は、テストや設定ファイルも含めた全体が対象です。両方を別々に回す使い方が想定されています。

型だけを報告から外したいときは --exclude types、特定のexportを対象外にしたいときはJSDocのタグでの除外が使えます。

knipの設定をClaudeに書かせたい場合、ドキュメントはKnip Editor Extensionの組み込みMCPサーバーを紹介しています。コーディングエージェントに、プロジェクトに合ったknip.jsonを書かせるための仕組みです。

CIに残して再発を止める

一度きれいにしても、数か月で元に戻ります。knipを継続的な検査にすると、増えた時点で止められます。

終了コードは、問題が無ければ0、問題があれば1、実行自体に失敗したときは2です。--max-issues で許容件数を決められ、デフォルトは0です。設定ヒントもエラー扱いにするなら --treat-config-hints-as-errors が使えます。

件数が多いプロジェクトでは、--max-issues に現在の件数を置いて始め、Claude Codeで少しずつ減らすのが現実的です。大規模な移行と並行して減らすなら、検証の考え方はClaude Codeのコードモダナイゼーションが参考になります。

まとめ

knipが探して、Claude Codeが仕分けて消し、テストが担保する。この分担が崩れるのは、レポートを信用しすぎたときと、検証の合図を置かなかったときです。削除前にplan modeで仕分けを見て、種類ごとにテストを回し、コミットを分けておけば、戻す範囲も小さく保てます。

設定漏れが疑わしい報告は、ignore で消さずに entry と project から直します。そのほうが次回以降のレポートの精度も上がります。