Claude Codeを半年ほど使い続けていると、ワークスペースが散らかってきます。ルールファイルが少しずつ増え、プロジェクト構成が変わっても古い参照パスがそのまま残り、使わなくなった設定が放置される。最初のうちは気にならないのですが、あるタイミングでClaude Codeの挙動がなんとなく不安定になっていることに気づきました。

具体的には、過去に修正した話がなぜか参照される、過去検討していて現在はステータスが違うファイルが参照される。結果として判断が古い内容などが混じり、「それは先月変えたよ」と指摘している間にトークンが最大量まで到達する、ということが起きていました。

原因を調べてみたところ、.claude/rules/ 配下のファイルが合計で600行を超えていたんですよね。後から振り返ると、ルールを追加するときは気軽にやるのに、不要になったルールを消す作業は一度もやっていなかった。これが積もり積もって、Claude Codeのパフォーマンスに影響していたようです。

この記事では、私が月1回やっているワークスペースのメンテナンス手順を書いていきます。所要時間は10〜15分程度で、これだけでClaude Codeの応答品質がかなり変わりました。CLAUDE.mdの基本的な書き方は「CLAUDE.mdの育て方」の記事に書いたので、今回はその先の「維持管理」の話です。

なぜワークスペースは散らかるのか

Claude Codeを使い込むほど設定ファイルが増えるのは自然なことです。rules、memory、エージェント定義、プロジェクトごとのCLAUDE.md...。問題は「増えること」ではなく「整理しないこと」にあります。

特にrulesは影響が大きいです。.claude/rules/ に置いたマークダウンファイルは、パス指定がないものは全セッションの開始時にコンテキストに注入される仕組みになっています。つまり、rulesに不要な100行が残っていると、今後の全てのやりとりで100行分のコンテキストを無駄に消費し続けることになる。これは地味に効いてきます。

もう一つ厄介なのが、壊れた参照パスです。ファイルを移動したりリネームしたりすると、CLAUDE.mdやエージェント定義から参照していたパスが無効になる。Claude Codeはそのパスを「あるはずだ」と思ってファイルを探しに行き、見つからないまま迷走し、最悪の場合は存在しない内容をもっともらしく語り始める。これはエージェントを複数運用していると特に起きやすいです。

メンテナンスの全体像 -- 月1回、10分でやること

私は月初に以下の7フェーズでワークスペースの衛生状態をチェックしています。全部やる必要はありません。時間がなければPhase 1（rules精査）とPhase 5（参照パス検証）の2つだけで十分効果があります。

Phase	内容	ひとこと
1	rules精査	自動ロード量を計測し、不要なルールを移動・圧縮
2	ファイル重複排除	同じ内容が複数箇所にある状態を解消
3	暗黙知の形式知化	memoryに繰り返し出るパターンをルール化すべきか判定
4	プロジェクト設定の整合性確認	CLAUDE.md・README.mdが現状と合っているか
5	参照パスの検証	設定ファイルから参照されているパスが実在するか
6	残骸の削除	空フォルダ、不要ファイルのクリーンアップ
7	レポート作成	結果を記録し、前回と比較

太字にした2つが最も効果が大きいフェーズです。Phase 2〜4、6〜7は余力があるときにやる程度で、実際に毎月必ずやっているのはPhase 1と5だけだったりします。

rulesの精査 -- 一番効くメンテナンス

7つのフェーズの中で圧倒的に効果が大きいのが、rulesの精査です。ここだけやるだけでも体感が変わります。

まず現状を把握する

コマンド1つで全rulesの行数が分かります。

wc -l .claude/rules/*.md

私が使っている健全ラインの目安はこうです。

200行以下: 健全。このまま維持
200〜400行: 要注意。圧縮候補を探す
400行超: 危険。すぐに対応が必要

公式ドキュメントでもCLAUDE.mdは200行以内が推奨されていて、rulesも同じロジックで読み込まれるので、この基準で問題ないと判断しています。

各ファイルの必要性を判定する

行数を把握したら、各ルールファイルを1つずつ確認していきます。判断の軸は3つです。

全セッションで必要か？ 禁止事項や安全ルールは全セッションで必要なのでrulesに残す。特定プロジェクトでしか使わないルールは、プロジェクト配下のCLAUDE.mdに移動するだけで全体のロード量が減ります。

冗長な例示が含まれていないか？ 失敗を経験するたびに「次はこうする」と追記していると、手順の詳細解説が膨らみがちです。コアとなるルールだけ残して、詳細手順はガイドファイルに切り出すとスッキリします。ルールの分離パターンについてはrules設計パターンの記事に詳しく書いたので、そちらも参考にしてみてください。

他のファイルと重複していないか？ CLAUDE.mdに書いてある内容がrulesにも書いてある、ということがよくあります。Single Source of Truthを1つ決めて、もう一方は削除する。

移動の実行と、やりがちなミス

rulesから外したファイルは、ガイドフォルダやプロジェクト配下のCLAUDE.mdから参照させます。ここで注意なのが、参照パスの更新を忘れることです。移動したファイル名でワークスペース全体をgrepして、参照元を漏れなく更新するのが安全です。

正直、最初のメンテナンスでこれをやらかしました。ルールファイルをガイドフォルダに移動したのに、エージェント定義からの参照を放置してしまい、エージェントが毎回「ファイルが見つかりません」と迷走する状態に。たった1箇所の参照漏れでも影響は案外大きいんですよね。

私の場合の実績

このプロセスで、rulesのロード量を609行から189行に削減できました。69%減です。

具体的には、ルーティング表、用語集管理の手順書、プロジェクト固有のセッションルールの3ファイルを「全セッションでは不要」と判定して、適切な場所に移動しました。

体感としてはかなり変わりました。古い情報が扱われなくなり、作業中に「それは違うよ」と指摘する頻度が明らかに減った。プラシーボかもしれないと最初は思いましたが、指摘回数が減った事実は間違いないので、ルールの量はAIの判断品質に影響しているのだろうと考えています。

参照パスの検証 -- 壊れたリンクは放置しない

Phase 5の参照パス検証も、地味ですが重要度が高いメンテナンスです。

ファイルを移動・リネームするたびに、そこを参照していた設定ファイルが壊れる可能性がある。CLAUDE.md、エージェント定義ファイル、rulesの中から参照パスを抽出して、そのパスが実際に存在するかをチェックする作業です。

壊れた参照を1件見つけて修正するだけで、「Claude Codeが架空のファイルの内容を語り始める」問題が解消することがあります。存在しないパスを参照したまま放置していると、Claude Codeは「そのファイルにはこう書いてあるはず」と推測で話し始めてしまう。正直、これに気づくまで結構な時間を無駄にしました。

エージェントを複数運用している場合は特に価値のある作業です。エージェント定義ファイルには参照すべきガイドやスキルのパスがたくさん書かれていて、1つでもパスが壊れていると応答の品質が目に見えて下がる。フォルダ設計の話とも密接に関わるのですが、これについては別の記事で詳しく書く予定です。スキル（カスタムスラッシュコマンド）の整合性チェックも、参照パスの検証と一緒にやっておくと効率的だと思います。

メンテナンス自体をスキルにしてしまう

ここまで書いてきたチェック手順、実は私はClaude Codeの「スキル」として定義しています。スラッシュコマンド1つで7フェーズのチェックが走り、レポートが自動生成される仕組みです。

月初に /maintenance-claude-workspace と打つだけで、rulesの行数チェック、壊れた参照パスの検出、前回との比較レポートまで出してくれます。手動でやると15分かかるところが、ほぼ待っているだけで完了する。

個人的に気に入っているのは、memoryに繰り返し出てくるパターンを見つけて「これはルールにしたほうがいいかもしれません」と提案してくれる点です。ただし、実際にルールを追加するかの判断は私がしています。自動修正していいライン（壊れたパスの修正、空フォルダの削除等）と、人間が承認すべきライン（新しいルールの追加、ファイルの削除等）は分けておくのが大事です。

スキルの設計パターンについては別の記事で書く予定ですが、ポイントだけ伝えると「何を自動でやって、何を人間に確認するか」のラインを最初に決めておくこと。これがないと、かえって混乱する可能性があります。

ワークスペースは使えば散らかる。散らかればAIの応答品質が落ちる。コードのリファクタリングと同じだなと思っています。「動いているから触らない」ではなく、「動いているうちに整理する」のほうが結果的に楽です。

月1回、まずは wc -l .claude/rules/*.md を打ってみるところから始めてみてください。200行を超えていたら、それがメンテナンスのサインです。