CLAUDE.mdとskill、重複を断つ3つの質問

アポロ

2026年8月16日 17:27

「直したはずなのに、直っていない」。ターミナルの前で、しばらく固まりました。

原因は単純でした。同じルールをCLAUDE.mdとskillの両方に書いていて、片方しか直していなかっただけです。

この記事で渡すのは2つ。指示の置き場所を1つに決める「3つの質問」と、散らかった設定を洗い出す15分の棚卸し手順です。Claude Code で CLAUDE.md と skill を両方書いている人向けに書きます。

二重に書いた結果、何が起きたか

わたしがやった失敗は2つです。

ひとつは、CLAUDE.md に書いたルールを、skill にもそのまま書いたこと。しばらく運用したあと手順を変えて、skill だけ直しました。CLAUDE.md には古い手順が残ったままです。

すると Claude は、日によって新しい手順に従ったり、古い手順に従ったりしました。どちらが読まれているのか、ログを見ても分かりません。

もうひとつは、似た役割の skill を増やしたこと。「レビュー用」「チェック用」と、名前だけ違うものが並びました。呼びたいときに呼ばれず、呼びたくないときに勝手に呼ばれます。ぐるぐる直しているうちに、どれが生きているのか分からなくなりました。

原因はどちらも同じで、同じ情報の置き場所が1つに決まっていなかったことです。

二重化が壊れる理由は、公式ドキュメントに書いてある

これは相性の問題ではなく、仕様です。以下の引用は公式ドキュメント（英語）からの筆者訳。

1. 矛盾したルールは、どちらかが任意に選ばれます

メモリの解説ページには、こうあります。「2つのルールが矛盾している場合、Claude はどちらか一方を任意に選ぶことがある」。

つまり、二重管理を放置すると挙動が運任せになります。再現しない不具合は直せません。

2. CLAUDE.md は長さに関係なく、全文が読み込まれます

読み込みは2種類。作業ディレクトリと、その上の階層にある CLAUDE.md は、セッション開始時に全文がコンテキストへ入ります。サブディレクトリの CLAUDE.md は遅れて、そのディレクトリのファイルを Claude が読んだ時点で入ります。

公式の目安は1ファイル200行未満。上限ではないので超えても全文は読まれますが、長いファイルは指示の遵守率を下げると明記されています。

一方 skill は、セッション開始時に載るのが name と description だけ。本体は使うときに初めて読まれます。

3. description が曖昧だったり重なったりすると、選択を誤ります

拡張機能の使い分けを説明したページには、こうあります。「description が曖昧だったり重複していたりすると、Claude は誤った skill を読み込むか、役立つはずの skill を読み落とすことがある」。

わたしが「呼ばれない・衝突する」と感じていたものの正体は、これでした。

skill が呼ばれない、もうひとつの理由

skill の一覧（名前と description）には文字数の予算があり、既定では**モデルのコンテキストウィンドウの1%**です。

予算を超えても、名前は全部残ります。削られるのは使用頻度の低い skill の description のほう。description は呼び出し判定の材料そのものなので、削られた skill は、ぱたっと呼ばれなくなります。

似た skill を増やすほど、本当に使いたい skill のキーワードが押し出される。そういう構造です。

置き場所を決める3つの質問

置き場所は、実はもう1か所あります。パスを限定して読み込ませる .claude/rules/ です。CLAUDE.md と合わせて3か所。書く前に、上から順に答えます。最初に「はい」になったところが置き場所です。

Q1. そのセッションが何をしていても必要か

→ はい。CLAUDE.md に書きます。ビルドコマンド、命名規約、「常に〜する」の類。「2スペースインデントを使う」のように、守れたかどうか検証できる粒度まで具体化します。

Q2. 特定のファイルやディレクトリを触るときだけ必要か

→ はい。.claude/rules/ に置きます。ファイルの先頭に、次の3行（フロントマター）を付けます。

---
paths: "src/api/**/*.ts"
---

こう書くと、そのパターンに合うファイルを Claude が読んだときだけ読み込まれます。ふだんのコンテキストを汚しません。

Q3. 2ステップ以上の手順か、長い参照資料か

→ はい。skill（.claude/skills/<名前>/SKILL.md）にします。本体はオンデマンド読み込みなので、長い資料を置いても待機コストはほぼゼロです。

3問とも「いいえ」なら、まだファイルに書く段階ではありません。ただし、同じ訂正を2回打ったら、それは毎回必要な情報だったということ。その時点で Q1 が「はい」に変わります。

そのうえで、守る原則が1つあります。

同じ事実は1か所にだけ書く。他の場所からは参照だけする。

手順を skill に移したら、CLAUDE.md 側には1行だけ残します。たとえば「リリース手順は /release を使う」。skill には、description を見た Claude が自分で呼ぶ道と、/名前で人が明示的に呼ぶ道の2つがあり、/release は後者です。中身を要約して残すと、それがまた古くなります。

補足：description の書き方

公式の推奨は、「何をするか」と「いつ使うか」の両方を、第三人称で書くことです。

良い例：PDFからテキストと表を抽出する。PDFやフォーム、書類の抽出を頼まれたときに使う。
悪い例：書類まわりのお手伝いをします。

自分が実際に打つ言葉を、トリガー語として入れます。役割が重なった skill が2つあったら、統合するか片方を消します。

分量の目安も覚えておくと迷いません。CLAUDE.md は200行未満、SKILL.md の本体は500行まで。どちらも目安です。description は長く書いても、一覧に載るのは1件1,536文字まで。要点は先頭に置きます。

15分でやる棚卸し

いま散らかっている人向けの手順です。上から順に実行できます。

① 現状を見る（3分） セッションで /context を開きます。見るのは Memory files と Skills の2行。Memory files に並ぶのは、起動時に無条件で読まれたファイルです。サブディレクトリの CLAUDE.md と paths: 付きの rules は、該当ファイルを触るまで出てきません。出ていない＝効いていない、と早合点しないこと。

② 削れる分を出す（3分） /doctor を実行します。CLAUDE.md のうち、コードから読み取れる内容（ディレクトリ構成や依存一覧）を削る提案と、未使用 skill をコストと突き合わせた検出が出ます。この削減提案は Claude Code v2.1.206 以降の機能なので、古ければ先に更新を。更新の時間は、この15分に入れていません。

③ 重複を探す（5分） CLAUDE.md と skill を並べて、同じ動詞が両方に出てくる場所を探します。手で追うと見落とすので、検索をかけます。

rg -n "test|commit|deploy|lint|レビュー" CLAUDE.md .claude/

rg（ripgrep）が無ければ grep -rEn "test|commit|deploy" CLAUDE.md .claude/ でも同じです。キーワードはあくまで例なので、自分のファイルによく出てくる動詞に置き換えてください。個人用の skill を使っているなら、~/.claude/skills/ もパスに足します。

同じ動詞が2ファイル以上でヒットしたら、それが二重管理の候補です。

④ 1か所に寄せる（4分） 候補ごとに3つの質問を通し、置き場所を1つ決めます。残った側は1行のポインタに置き換えること。description が似ている skill は統合します。どうしても両方残すなら、使わないほうの SKILL.md のフロントマターに disable-model-invocation: true を追記し、一覧から隠します。

最後に、次のセッションで /context を開き直します（30秒）。Skills 行のトークンが減っていれば、一覧の予算に余裕が戻っています。

つまずくとしたら③です。「これは重複ではなく補足だ」と思った箇所こそ、たいてい重複でした。迷ったら消す側に倒すほうが、あとで楽になります。

おさらい

矛盾したルールは任意に選ばれます。二重管理は運任せと同じです
CLAUDE.md は全文が読まれ、skill は本体がオンデマンドで読まれます
skill 一覧の文字予算はコンテキストの1%。似た skill を増やすと description が削られ、呼ばれなくなります
置き場所は3つの質問で決めます。毎回必要か／特定パスだけか／手順か
同じ事実は1か所だけ。他所からは1行で参照します

設定は、増やすより置き場所を1つに決めるほうが効きます。

参照ソース

調査実施日：2026年8月16日（コマンドの挙動はバージョンで変わります）