AIへの指示書(CLAUDE.md)を診断したら、効いていない指示が38件あった — 直したのは29箇所。消さなかった理由

AIに仕事を頼むとき、毎回同じ前提を説明しなくて済むように、あらかじめ「こう動いてほしい」を書いておくファイルがある。Claude Codeでは「CLAUDE.md」と呼ばれるものだが、ここでは「指示書」と呼ぶ。

私の指示書は、2026年7月の終わりから少しずつ育ってきた。事故が起きるたびにルールを1行足してきたので、冷蔵庫に貼り紙が増えていくのと同じで、どの紙がまだ要るのか、書いた本人にも分からなくなっていた。

それをまとめて診断にかけたら、効いていない指示が38件見つかった。その日のうちに直したのは29箇所。5件は「直すとAIの振る舞いが変わる」ので別扱いにし、そのうち2件は直さないと決めた。

数字だけ見ると「掃除が捗った」話に見える。実際に時間を食ったのは、消す作業ではなく、消さない判断のほうだった。

何を診断したか

対象は、常に読ませている指示書、役割ごと(調査係・整理係など)の定義、特定の場所を触るときだけ読ませるルール、作業手順の定義。合わせて54ファイル、約5,300行あった。

診断には、Claude Codeに同梱されている「prompt-audit」という手順を使った。AIの提供元が配布しているもので、やることは「古い世代のモデル向けに書かれた具体的な指示」を探すこと。診断だけをさせ、ファイルは1文字も編集させなかった。直すかどうかは自分で決めたかったからだ。

意外だったこと: 古い言い回しは1件もなかった

診断前の見込みは、「ステップバイステップで考えて」のような昔のモデル向けの定型文がたくさん残っているだろう、というものだった。

0件だった。特定のモデル名を決め打ちした指示も0件。

代わりに見つかった38件のうち、目立ったのは次の3種類だった。

• 同じ手順を2箇所に書いて、片方だけ直した矛盾。 5件。全体のルールでは「こちらが正式な版、あちらは使わない」と決めているのに、個別の手順書は使ってはいけない側を名指ししたままだった。
• 経緯や履歴の説明と、「前の版と比べて」の書き方。 14件。「旧記述は誤りだった」「以前の言い方から読み替え」のような文は、旧版を見ていないAIにとって「別の案があるらしい」とほのめかすだけで、何をすればいいかは増えない。
• 進捗報告を抑える1文。 「細かな実況はいらない」という趣旨の行が、必要な報告まで抑えていた。重要度の高い所見は6件あったが、AIの振る舞いに直接効くものはこの1件だけで、残りは上の「矛盾した複製」など、事実の食い違いだった。

つまり、指示書を重くしていたのは「古い言葉」ではなく、「更新のたびに残った差分の痕跡」だった。

三つの問いで仕分けた

1行ずつ、次の順に問いを当てた。

• 問い1: その行は、過去の事故や失敗から生まれたか。 はいなら残す。理由が別ファイルにあっても残す。
• 問い2: コードやファイルを読めば分かることか。 はいなら消す。指示書に書かなくてもAIは読める。
• 問い3: 「〜するな」の列挙になっていないか。 はいなら、判断基準の1行に書き直す。禁止を並べるより「何を基準に決めるか」を1つ書いたほうが、書いていない場面にも当てはめやすい、と考えてのことだ。

どれにも当たらない行は、残したうえで根拠を1行添えた。

この仕分けで気づいたのは、「消してよいか」の判断は行の中身ではなく、行の出自で決まるということだった。いつ、どの失敗から生まれたかを1行で言える行は、残すか消すかがすぐ決まる。言えない行ほど時間がかかった。

薬箱の整理に似ている。いつ、何の症状で出された薬か分かっているものは、捨てるか取っておくかがすぐ決まる。由来の分からない薬ほど、手が止まる。固定費の見直しで「これ何の契約だっけ」と手が止まるのも、同じ構造だと思う。

事実の訂正と、振る舞いの変更を分けた

診断が付けた文面の修正案は34箇所。ほかに、「数える処理はプログラムに任せるべき」のような仕組み側の指摘や、強調の使いすぎという方針の話もあり、こちらはその場で直す文面が無い。

34箇所のうち29箇所は、矛盾した複製・履歴の説明・古くなった具体値の修正で、どれも「今の事実に合わせる」だけのものだった。これは1つの束にして、その日のうちに直した。

残る5件は違った。報告の頻度、作業を任せるかどうかの判断、自己採点の止め方、手順の圧縮、確認の義務化。どれも直すとAIの振る舞いが変わる。こちらは1件ずつ、提案と一番強い反対意見と、事情を知らない第三者の見方を並べて、自分で決めた。

結果は3件採用、2件見送り。見送った理由は「任せるかどうかの判断を機械的な基準にすると、判断の質が落ちる」「手順を減らすと、途中の検証が抜ける」。どちらも、診断の提案とは逆の結論になった。分けなかったら、29箇所の訂正に紛れて、振る舞いの変更まで一気に通していたと思う。

機械で決めようとして、決められなかったこと

診断は、強調の記号(私は赤い丸を使っている)の使いすぎも指摘してきた。診断対象より範囲を広げて65ファイルを数えると、赤丸を含む行が222行。うち、隣に出典(日付や記録の番号)が無い行が63行あった。

最初は「出典が隣に無い強調は不要」と機械的に判定して、太字に格下げするつもりだった。ところが、自分の指示書には「根拠は本文に書かず、別の履歴ファイルへ移す」というルールがあった。つまり、事故から生まれた大事な行ほど、隣に出典が無い。機械判定は、自分が作ったルールと正面から衝突した。赤丸を「影響あり/なし」のようなラベルとして使っている箇所もあり、そこを太字にすると手順の形が変わってしまう。

落ち着いた先は、「候補は機械で出す。消すかどうかは人が仕分ける」だった。63行はまだ1行も外していない。次の棚卸しで候補として1行ずつ見る。機械に任せられるのは候補出しまで、という線引きが、この日いちばん腹に落ちた学びだった。

消す前にやったこと

• 旧版のバックアップを取る。 消して困ったら、元の長文ではなく簡潔な形で戻す。
• 消す文言は、削除の前に履歴ファイルへそのまま移す。 「他にも書いてあるはず」を確かめるより、移すほうが早い。
• 直したあと、意図した箇所以外が変わっていないかを照合する。 目で差分を追うだけでは、長い1行の中の変化を見落とす。
• 文案は適用前に、別のAIに監査させた。 条件付きの承認だったので、条件を全部反映してから適用した。

同じ日に同じ形の作業を繰り返すと、確認手順が「前回と同じ」に置き換わる。少し前に、それで公開前の確認工程を1つ飛ばしたことがあった。

今日やるなら、これだけ

指示書を開いて、上から10行だけ、三つの問いを当ててみる。全部やろうとしない。10行のうち「いつ、どの失敗から生まれたか」を言えない行が1つでもあれば、その行の隣に「なぜあるか」を1行書くか、履歴側へ移す。それだけで、次に読み返すときの迷いが1つ減る。

効果は、まだ測っていない

掃除したことで応答が速くなったか、確認が減ったかは、まだ測っていない。同じ依頼を掃除の前後で流して比べる作業は、これからやる。だからこの記事は「こうしたら良くなった」ではなく、「何が見つかり、何を直し、何を直さなかったか」の記録だ。

かかった手間は小さくなく、バックアップだけで19本になった。見合うかどうかも、効果を測るまでは言えない。

診断の手順は最初に「監査の仕事はプロンプトを短くすることではない」と釘を刺していた。実際、消した分より、残すと決めた行に添えた根拠のほうが多かったかもしれない。それでも、どの行が何のためにあるかを自分で説明できる状態になったことが、今回の収穫だった。

この記事は「何が起きたか」の記録で、三つの問いをどう当てるかの判定質問(全部で10問)、消してはいけない行の3つの見分け方、消す前後の手順5段、自分の指示書に当てるワークは、別途noteに手順としてまとめている(有料): 育ちすぎたCLAUDE.mdを「消す・残す・書き直す」の3区分で仕分けられるようになる棚卸しチェックリスト10問。

関連する記事: Claude CodeとObsidianで作業場を1つにした話 / ChatGPTとClaude Codeの使い分け / closedはfixedではなかった話

本記事にアフィリエイトリンクやPR案件は含まれていない。