念を押さない技術

CC BY 4.0

一番強く書いた節が、一番機構の少ない節だった

👤私の手元には、typingtube という本番プロジェクトがあります。YouTube の音楽動画でタイピング練習ができる Web サービスです。その指示ファイルは 102 行で、空行と見出しを除くと 69 行です。そのうち強調を含むのは 7 行でした。

数える前の👤私は、自分が本当に大事だと思った行に強調を付けているつもりでいました。

実際には、7 行のうち 5 行は、👤私が機構でも守らせているルールを書いた行でした。機構というのは、hookや自動テストのように、🤖AIが読まなくても動く仕組みのことです。

• 翻訳ファイルの構文チェック（pre-commit hook で走る）
• デザインのラチェット（色を直に書いた箇所などの件数が増えたら、pre-commit hook で落ちる）
• サブエージェントの起動ガード 2 行（用途カタログ = サブエージェントに任せてよい仕事と、起動前に用意しておくファイルの一覧。そこに無い仕事では、サブエージェントを起動しない）
• テストの並走ガード（並列実行の 2 本目は走らない）

🤖AIがこの 5 行のどれかを破ると、機構がその操作を止めます。強調を消しても、🤖AIの操作は同じところで止まります。

このうち翻訳ファイルとデザインの 2 行は、第 1 回で書いたとおり、👤私がチェックのスクリプトを足したのと同じコミットで、「コミット前に必ず実行」と書き足した行です。hookがそのスクリプトを実行するようになったのは、デザインのほうはその日のうちで、翻訳ファイルのほうは 5 か月あとです。hookを置いたあとも、👤私は 2 行の強調を外していません。

残る 2 行は、この指示ファイルでただ一つ、見出しに「最重要」と書いた節の行です。その節に、👤私は、RubyやNodeのコマンドを、すべてコンテナ経由で実行する、というルールを書きました。このルールを守らせる機構は、テスト実行の入口に置いた 1 か所だけです。bundle も npm も rake も、🤖AIがホスト上で直接実行すれば、そのまま動きます。

つまり、一番強く書いた節が、一番機構の少ない節でした。この節のルールを守らせているのは、ほとんど強調だけです。

強調の効き目は、測ることができません

「最重要」と書いた節のルールが破られたことがあるかを、👤私はセッション（🤖AIとの、始まりから終わりまで一続きのやり取り）の記録で探しました。残っている 5 週間ぶんの記録で、🤖AIがホスト上で ruby や npm を直接実行したコマンドは 6 回ありました。どれもファイルの中身を数える、バージョンを見る、といった短いコマンドで、6 回ともそのまま動き、作業は先へ進んでいます。

1 作目の第 6 回で、👤私は📖読者にこう問いかけました。指示ファイルの禁止事項を 1 つ選んだとき、それが先月🤖AIに何回破られたか、答えることができますか。🤖AIが禁止事項を破っても、作業はそのまま先へ進むので、答えることができないのが普通です。記録にあった 6 回でも、🤖AIの作業はそのとおりに先へ進みました。👤私が回数を数えることができたのは、記録を検索したときです。

強調の効き目には、もう一段の壁があります。6 回は、強調した行でも破られたことを示すだけです。強調が無かったら何回破られていたかは、分かりません。破られなかった場面が、強調のおかげなのか、そもそも破りそうな場面が来なかったからなのか、👤私には区別が付きません。

区別が付かないので、強調を増やしても減らしても、👤私には違いが見えません。一方で、強調を足すきっかけは、🤖AIが守らないルールを見つけるたびに来ます。減らすきっかけは来ません。翻訳ファイルとデザインの 2 行も、hookを置いたあとで強調を外すきっかけはありませんでした。強調は、足されたまま残ります。

強調した行が増えた先について、1 作目の序論で引いた Claude Code のベストプラクティスが書いているのは、多くの行を強調すれば、どれも目立たない、ということです。

📖あなたが、指示ファイルのあるルールを🤖AIが破っていたことに気づいたとします。そのルールの行は、すでに太字にしてあります。破っていた間も、作業はそのまま先へ進んでいました。📖あなたなら次のどちらで対処しますか。

• その行に ⚠️ と「必ず」を足し、指示ファイルの先頭へ動かす
• そのルールを、hookや自動テストのような機構で守らせることができるかを見る

答えは、機構で守らせることができるかを見るほうです。破っていた間も作業が進んだのは、指示ファイルの行が、🤖AIが読んだときだけ働き、破られても何も止めないからです。強調を足しても、その行が何も止めないことは変わりません。足した強調が効いたかどうかも、破られた回数が作業の側に出てこないので、見えません。👤私の手元の 6 回も、「最重要」と太字で書いた節のルールで、そのまま進みました。しかも強調は、足すきっかけだけが来て減らないので、強調した行が増えていき、多くの行を強調すれば、どれも目立たなくなります。機構に移せば、🤖AIがその行を読んだかとは別に、破った操作がその場で止まります。📖あなたが強調のまま残すのは、機構で守らせることのできないルールだけです。

理解したことは一文にできます。

強調の効き目は測ることができず、強調は、🤖AIが守らないルールを見つけるたびに足されて、減らない。だから効き目は測らず、強調を含む行が増えるたびに、そのルールを機構で守らせることができるかを見る。

仕組み: 効き目を測らず、強調を含む行の件数をラチェットにする

👤私が置くのは、自動テスト 1 本です。ラチェットというのは、一方向にしか動かない歯止めのことです。

# test/reference/claude_md_emphasis_ratchet_test.rb（手元のコードを短くしたもの）
EMPHASIS = /\*\*|⚠️|最重要|絶対|必ず/
BASELINE = 7          # 2026-09-04 の実測。7 行のうち 5 行は機構あり

test "emphasis in the instruction file does not grow past the baseline" do
  lines = File.readlines(Rails.root.join("CLAUDE.md"))

  # ⚠️ 対象 0 件で合格にしない。読み先が壊れたらここで落ちる
  assert_operator lines.count { |l| l.strip.present? }, :>=, 50

  emphasized = lines.each_with_index
                    .select { |line, _| line.match?(EMPHASIS) }
                    .map { |line, i| "CLAUDE.md:#{i + 1}: #{line.strip}" }

  assert_operator emphasized.size, :<=, BASELINE,
                  "emphasis went past the baseline. before adding one, see whether the line " \
                  "can be guarded by a check instead. if it cannot, raise BASELINE and " \
                  "write down why\n#{emphasized.join("\n")}"
end

1 作目の第 6 回で、違反を今すぐ全部は直すことができないルールは、ラチェットにする、と書きました。いまの違反の件数を基準値として記録し、件数が増えたら落ちる自動テストにする、という形です。この自動テストは、その形を強調に当てたもので、効き目を測る代わりに、強調を含む行の件数を数えます。測ることのできない効き目を測ったふりをすると、その数字から先の判断が全部嘘になります。

この自動テストが落ちるのは、強調を含む行が足されて、件数が基準値を超えたとき、つまり強調を足すきっかけが来たその場です。そこで出る失敗のメッセージに👤私が書いたのは、その行を機構で守らせることができないかを先に見ることと、できないなら基準値を上げて理由を書くことの 2 つです。

👤私は、この自動テストに📐逃げ道明示の環境変数などで hook を素通りできる正規の出口も残してあります。基準値を上げれば、自動テストは合格します。それでいいのです。基準値を上げるときに、👤私は一度立ち止まって、「この行は機構で守らせることができないか」を考えます。この自動テストを置いたのは、その一度の立ち止まりのためで、基準値の数字は、立ち止まるきっかけにすぎません。

CC BY 4.0 はここまで

CC BY 4.0

注意: 効き目は測ることができず、見ているのは語形だけです

一つ目は、この自動テストが測っているのが、強調を含む行の件数だけだということです。強調が減れば🤖AIがルールを守るようになる、と言うことはできません。言うことができるのは、強調を増やすたびに一度、機構で守らせることのできる行が強調のまま残っていないかを👤私が見る、というところまでにとどまります。

二つ目は、この自動テストが見ているのが語形だけだということです。数えるのは、太字と ⚠️ と、「最重要」「絶対」「必ず」の 3 語を含む行です。「とても重要」や「きわめて重要」と書いた行は、強調の無い行として扱います。行の位置も見ないので、大事な行を先頭へ動かしても、件数は変わりません。第 1 回で置いた自動テストも同じです。その自動テストは、指示ファイルの中で実行を頼む行を「必ず実行」という語形で拾うので、「実行しておいてください」と言い換えた行は見逃して合格にします。

検証手順: 強調を含む行を増やして、自動テストが落ちることを確かめる

前提

強調を含む行を数える自動テストを 1 本置き、今の件数を基準値としてファイルに記録し終えておきます。その自動テストが、今は通っていることも確かめておきます。

所要時間: 10 分

手順

1. 📖あなたが、指示ファイルに太字か ⚠️ を含む行を 1 行足します。中身は何でも構いません（基準値を超えさせるのが目的です）
2. 📖あなたが、その自動テストを走らせます
3. 📖あなたが、失敗のメッセージに並んだ行を 1 行ずつ見て、そのうち何行が機構で守られているかを数えます。機構とは、hookや自動テストのように、🤖AIが読まなくても動く仕組みのことです

合格条件（すべて満たすこと）

自動テストが落ち、失敗のメッセージに、強調を含む行が全部並べば合格です。

合格しなかったとき

• 「件数が基準値を超えました」だけで、行が並ばない —— 手順 3 に進むことができません。📖あなたが自動テストを、行の一覧を出す形に直してから、やり直します
• 落ちない —— 基準値のファイルが、今の件数より大きい値になっています

手順 3 がこの検証の本体です。この自動テストが落ちたときに大事なのは、強調を含む行の一覧が目の前に出ることです。一覧の行は、機構で守られている行と、強調のほかに守るものの無い行に分かれます（この記事の例では、7 行のうち 5 行が前者でした）。前者の行は、強調が無くても、🤖AIの操作が同じところで止まります。後者の行が、機構で守らせることができるかを見る対象です。

後始末

手順 1 で足した行を消し、自動テストが合格に戻ることを確かめます。

CC BY 4.0 はここまで