番外編 C-2 仕組みと人を分ける技術 —— 自動テストを置いたその手で、自動テストの外側で 2 度転んだ日

前章で、校正の方法を書いた文に本編を当てて、地雷を 10 個見つけました。次にやったのは仕分けです。どれを仕組みに任せ、どれを人が読むのか。

仕分けは 1 枚の表になり、そこから自動テストを 1 本置きました。置いてみて分かったことのほうが、表より重要でした。

先に結論を 3 つ置きます。

• 分ける線は「仕組みで真偽が決まるか」ではありませんでした。10 個のうち 5 個は真偽が決まります（もう 1 個は条件つき）。それでも仕組みに渡せないものが残ったのは、その文が、どの自動テストの走査対象にも入っていないからです
• 自動テストを置く理由に書いた数が、置いてみたら再現しませんでした。その案には「置く前に 7 件の付け替えが要る」と書いてあります。実際に数えたら、付け替えるものは 1 件もありませんでした
• ⚠️ 🤖私はその自動テストを書いているあいだに、同じ地雷を 2 度踏みました。どちらも自動テストは合格のままです。踏んだのは、自動テストを説明する文の中だからです

仕分けの物差し —— 足す前に問う 2 つ

🧩 これを意識して読み進めてみましょう。

症状「テストを足しても、それが何をどこまで守っているのかを数字で言えない」 ⭐ 本文では、ハイライトした部分がその場面です。

• No.10 要約 —— 数値の行に決まった書き出しを付け、一字一句コピーされたかを hook で見ます。
• No.31 走査 —— 走査しているのに件数の下限を持たない自動テストを、外から数えて見つけます。
• No.3 陽性対照 —— 🤖AI にミューテーションテストを指示します。

仕分けを始めたのは、🤖私の思いつきではありません。前章の 10 個を出したあと、👤著者から 2 行が来ました。

👤依頼者

地雷を踏んでしまった方針も、仕組みの追加でカバーできるかもしれません。もう少し、検討進めてください。

一般的な校閲だけど、どうしても採用難しかったものがあれば教えてください。

章の構成は、この 2 行のとおりに割れています —— 1 行目が前半（仕組みの追加でカバーできるか）、2 行目が後半（一般の校閲で、どうしても採用が難しかったもの）。

物差しには、番外編 A-1 に置いた問いをそのまま使いました。

⭐⭐⭐ 仕組みを足す前に問うことが 2 つある。 ① それは真偽が決まるか。② 何回起きたか。 ⚠️ どちらも通らないものは、数えるだけの道具にするか、何も作らない。

3 行目まで引いたのは、下の表の「案のまま」がこの行だからです。

これを、前章の 10 個にそのまま当てました。🤖私は②「何回起きたか」を、記憶ではなく記録で数えます。会話の記録と git の履歴です。

10 個のうち、仕組みで覆えたのは 4 つでした（スクリプト 1・自動テスト 1・既にあったもの 2）。案のまま置いたのが 1 つ、人が読むしかないのが 4 つ、既にある書き方で足りたのが 1 つです。

この内訳は、🤖私が表を作ったあとに数え直して直したものです。最初は「案のみ 2」と書いていました。1 つの地雷を 2 行に割るか 1 行にまとめるかで、内訳は動きます。前章の「母数を直したら分類が動いた」と同じことが、同じ表で起きました。

人が読む 4 つは、並べると全部同じ種類でした —— 根拠を超えていないか。頼まれていないか。前のパターンではないか。逆を言っていないか。これは校閲の中身そのものです。

新しく作るものは 2 つだけだった

4 つのうち 2 つは既にあるので、新しく作るのは、記録から原文を写すスクリプトと、節番号の参照が解けるかの自動テストの 2 つになりました。スクリプトは先に置きました。この章は、残った自動テストの話です。

自動テストの案には、手順が 1 つ付いていました。同じ日の 38 分前に、🤖私が書いた表のいちばん右の欄です。

✅ 採用候補（検査）。⚠️ 置く前に 7 件の付け替えが要る

その「7 件」の出どころは、同じ表に貼った 1 行です。

[observed] README / handoff への「リンク直後の §参照」 179 件 / 見出しに無い 7 件

[observed] という書き出しが付いています。この本で「測った数」を示すのに使っているものです。つまりこの数は、スクリプトが数えた数のつもりで書かれていました。

手順の理由は本編のとおりです。最初から失敗する自動テストを置くと、失敗が当たり前になって誰も見なくなります。だから先に直す。手順としては正しい形です。

付け替えるものが、1 件もなかった

自動テストを書き、走らせました。

[observed] §参照 201 件を解いた（範囲外 35 件 / 宛先を持つファイル 10 本 / 宛先の総数 1,052 件）
[observed] 解決しない 0 件

7 件がありません。付け替える作業は、始める前に消えました。

参照の宛先は、2 通りある

🤖私が管理しているドキュメントでは、節の参照が 2 通りの書かれ方をしています。

②を宛先に数えないと、実際には解けている参照が落ちます。

[observed] 見出しだけを宛先にすると、解決しない 25 件（25 件とも ② の形）

①だけなら 25、①と②の両方なら 0。どちらの数え方でも 7 は出ませんでした。母数も合いません（179 に対して、実測は 199。この章の後半で抜け穴を 1 つ塞いで 201 になりました）。

つまり「179 件中 7 件」は、数え方が残っていない数でした。どう数えたのかが書かれていないので、🤖私は同じ数を二度と出せません。取り消して、スクリプトが出した数に置き換えました。[observed] という書き出しが付いていても、数え方までは残りません。

⚠️ なぜ 7 件と書いたのかは、この章に書いていません。記録に残っているのは、そのとき書いた数と、数え直した数の 2 つだけです。

これは前章の 1 番目と同じ形です。数えるスクリプトを置く前に、数を書いた。違うのは、今回はその数が「自動テストを置く理由」に使われていたことです。数から手順が生まれ、その手順は空振りしました。

置いた自動テストが、見ているもの / 見ていないもの

自動テストが見るのは、番号が実在するかどうかだけです。見出しの文言が、参照元の説明と合っているかは見ません。合っているかは、読まないと決まらないからです。

壊れ方を 3 つ作って、落ちることを確かめました。

[observed] 変異注入 3 種（§番号違い / 宛先を別の器へ / 参照されている見出しを消す）= 3/3 検出

ただし、限界が 1 つあります。節を別のファイルへ移したときに壊れる形は、番号がかぶっていると通り抜けます。

[observed] 2 つの引き継ぎファイルの宛先は 100 件中 51 件が共通

この自動テストは、半分ほどしか捕まえません。それは自動テストの中に書いてあります。書かずに合格だけ見ていると、人は守られている範囲を実際より広く見積もります。

自動テストを書いているあいだに、2 度転んだ

この章がいちばん言いたいのはここです。

⭐ ここが記事になったのは、👤著者の 2 行があったからです。転んだ 2 分後に、こう来ました（引いたのは、その発話の後ろの 2 行です）。

👤依頼者

うまくいかない実装は本編にヒントがあるかもしれません。随時チートシート活用してください。 実践編なので、作業の中で得た知見があれば記事化が必要です。

「記事化が必要です」と言われなければ、この日の転びは引き継ぎの 1 行で終わっていました。

1 度目 —— 「足す前は 151 runs」

自動テストを足したあと、記録にこう書きました。

[observed] test/reference 155 runs 6,927 assertions 緑（足す前は 151 runs）

155 と 6,927 は、走らせたスクリプトが出した数です。括弧の中の 151 だけが、自分のメモから📐写し🤖AI が実装とテストを同時に書くので、テストが実装の出力を貼っただけになる現象た数でした（No.10）。

新しい自動テストを外して走らせ直したら、こうでした。

[observed] 検査を外して実測 154 runs（足したあとは 155 runs）

151 が正しかったのは、同じ日の未明です。記録では 02:36 に 148 から 151 になり、04:48 まで 151。上の行を書いた 13:34 には 154 でした。正しかった窓は、半日もありません。前章の「孫引き」と同じ形で、今回は自分のメモが出所でした。

そして、間違えた数は [observed] の行の中にありました。その書き出しが付くのは行で、行の中の数の 1 つ 1 つではありません。スクリプトが出した数の隣に 1 語足すと、その 1 語も同じ行の内側に入ります。

2 度目 —— 「実測 2,181 件」

自動テストの注記に、見ない範囲を書きました。リンクの付いていない裸の § は見ない、という但し書きです。🤖私はそこに「実測 2,181 件」と書きました。

書いた直後に測りました。

[observed] § の総数 2,551 / リンクに付いているもの 249 / 裸 2,302

2,181 という数は、どこから出したのか自分でも分かりません。測る前に、それらしい数を書いていました。

自動テストが落ちた 1 度は、偽陽性だった

この自動テストが落ちたのは、置いてから 1 度だけです。落ちたのは、この章の材料を引き継ぎに書いたときの 1 行です。リンクの形（角括弧を閉じて、そのあとに # から始まる宛先を続ける書き方）を例として地の文に書いたら、自動テストがそれを本物の参照として読みました。指している節は、そのファイルにありません。

これは偽陽性です。それでも直したのは自動テストではなく、書き方のほうでした。先に置いてある相対リンクの自動テストが、同じ問題に同じ答えを出していたからです —— 省略表記は、パスに見えない形で書く。

📐逃げ道明示の環境変数などで hook を素通りできる正規の出口を 1 つ作れば、次に同じ形が本物で来たときに素通りします。

転んだ 2 回は、自動テストは合格のままです

理由は単純です。自動テストが読んでいるのは、記事と引き継ぎの中の § であって、🤖私が書いた説明文の数字ではないからです。

分ける線は、どこにあったのか

ここで、最初の仕分けの物差しに戻ります。

• 「§9-6 が実在するか」は、仕組みで決まります
• 「この自動テストを足す前は何件だったか」も、仕組みで決まります（走らせれば出ます）
• 「裸の参照が何件あるか」も、仕組みで決まります

3 つとも真偽が決まります。それでも🤖私は 2 つを間違えました。

違いは、その文が自動テストの走査対象に入っているかどうかでした。記事の本文と引き継ぎの § は走査対象です。自動テストそのものを説明する文の数字は、どの自動テストの対象でもありません。

だから、仕分けの線はこう引き直しました。

4 行目が、この章で増えた行です。対策は「説明文にも自動テストを当てる」ではありません。説明文の数字が何を指しているかは文脈で決まるので、真偽が決まらず、①で落ちます。

代わりに、既にある仕組みがこれをやっていました —— スクリプトが出した数字の行を、言い換えずにそのまま貼る。今回は、1 度目は貼ったうえで 1 語足し、2 度目は貼らずに書きました。どちらも、[observed] の行の内側です。

もう 1 つの抜け穴 —— 自動テストが、見ていない置き場を持っていた

同じ日の点検で、もう 1 つ抜け穴が出ました。こちらは、置いた自動テストではなく、前からあった自動テストの話です。

配布用の HTML を作るときに、扱えない記法が本文に無いかを見る自動テストがあります。その自動テストが見ていたのは、1 冊目の付録の置き場だけでした。2 冊目の巻末（この番外編を含む 9 本）は、1 度も走査されていませんでした（No.31）。

[observed] 走査対象 13 本 → 22 本 / 走査した文章の行 2,410 → 3,848

同じ抜け穴は、35 時間前に別の自動テストで 1 度塞がれていました（前日の未明です）。置き場の一覧を「1 冊目だけ」から「手書きの置き場すべて」に直す、という同じ修正です。1 本直したときに、同じ形の隣の 1 本は直っていませんでした。

そして、この形を捕まえるための自動テストは、既に置いてありました。走査しているのに件数の下限を持たない自動テストを、外から数えるものです。それでも通り抜けました —— 下限は持っていたからです。持っていた下限が、狭い置き場を数えていただけでした。

だから今回は、置き場の一覧を 1 か所にまとめて、そこを見るように直しました。3 冊目を足したときに、また同じことが起きないためです。

塞いだら、本物が出ました。番外編の 1 本に、記録の形を見せるための引用が字下げで置いてありました。字下げは、この変換器では引用のかたまりになりません。行が段落としてつながり、行頭の記号がそのまま文字として出ます。囲みに直したら、合格になりました。

この 9 行は、自動テストが見ていなかった期間に書かれたものです。落ちない自動テストは、落ちないのではなく、見ていないだけでした。

足した仕組みを、その日のうちに測った

⭐ この章の後半で、もう 1 つ仕組みを足しました。足す前に、👤著者から 1 行来ています。

👤依頼者

OKです。チートシート確認して妥当な対応かつ本編での落とし穴がなければ、仕組み追加を進めてください

条件が 2 つ付いています。逆引きチートシートを確認すること、本編の落とし穴を踏んでいないこと。この章の物差し（足す前に問う 2 つ）と、同じ向きの条件です。

足したのは、「[observed] か「実測」と書き出した行の数が、その日のスクリプトの出力にあるか」を、作業の終わりに 1 度だけ見るものです。この日の 3 回のうち 2 回は、これで鳴ります（151 と 2,181）。3 回目は、この章自身の行数でした —— 引き継ぎに「226 行」と書いて、数えたら 234 行。こちらは書き出しが無いので鳴りません —— 書き出しの無い数まで見ると、本文の数字を全部拾うからです。

2 回は自動テストを書きながら、3 回目は、この章を書きながらの転びです。

足したあとに、壊し方を 8 通り作って、全部で落ちることを確かめました。そこで、置いたばかりの仕組みの中に、何も守っていない部分が見つかりました。

🤖私は、数を拾う前に「日付」と「節番号」を除く処理を 2 つ書いていました。2026-09-11 の 2026 や §13f-12 の 13 を、数と数えないためです。壊してみたら、どちらを壊しても 1 件も落ちませんでした（No.3）。

[observed] いまの [observed] 行 1,308 本 / 除外の有無で拾う数が変わる行 0 本

理由は単純でした。この仕組みは「単位の付いた数」しか見ません（件・本・行・回・体…）。日付にも節番号にも単位は付かないので、除く処理は最初から仕事がありませんでした。外しました。

🤖私は、必要かどうかを確かめずに 2 つ書いていたのです。壊してみるまで、それが分かりませんでした —— 全部合格だったからです。

同じ壊し方で、🤖私は逆に「効いている」と分かったものも見つけました。色付きの出力から色の記号を落とす処理です。落とさないと、色の番号（32）が「測った数」として記録に入り、次に 32 件 と書いても、この仕組みは黙ってしまいます。これも、対照を書くまでは合格でした。

自己テストを、誰も走らせていなかった

仕組みを足す手を止めて、既にあるものを数えたら、もっと大きいものが出ました。

この置き場には、仕組みごとの自己テストが 4 本ありました。どれも、走らせる仕組みがありません。その 4 本は、作業前の確認手順にも、保存時の自動テストにも、通常のテストにも出てきません。手で打った人だけが見ていました。

⭐ 走らせる場所を足しました。ただし、置く場所で 1 度つまずいています —— 通常のテストは箱の中で動くのに対し、仕組みそのものは箱の外（手元）で動きます。箱の中で 5 本（前からの 4 本と、この日に足した 1 本）走らせたら、1 本だけが失敗しました。手元では合格です。

原因は分かっていません。分からないものを「例外」として自動テストに書き込むと、そこが逃げ道になります。だから環境に依らない部分だけを通常のテストに置き（自己テストが仕組みと 1 対 1 で在るか）、走らせるのは手元の側に移しました。

[observed] 自己検査 5 本 / 仕組みの本体 6 本 / 自己検査の無い本体 1 本

1 本は自己テストがありません。数を上限として書き留めました —— 減らす方向にだけ動かせる形にしてあります。「今はここまで」を数で残すのと、無いことにするのは違います。

この「1 本」という数は、同じ日のうちに誤りと分かりました。自己テストは在りました —— ただし名前が対応しない別の置き場（scripts/tests/）にあり、上限の数え方が「隣に同じ名前で在るか」だけだったので引けませんでした。数え方を広げたら 0 本です（上限もその日のうちに 1 から 0 へ下げました）。この章の主題が、この章の数字にそのまま出ました —— 合格だったのではなく、見ていない置き場があっただけです。

そのうえで、置いた直後の点検で 4 つの抜け穴が出ました。3 つは実装ではなく、呼ばれる条件が狭いという形です（3 つ目だけ別の形で、下に分けて書きます）。

• 走らせる判定を「触ったもの」にしていた —— 触ったという記録は保存した瞬間に消えます。つまり、その自動テストは直して保存したあと二度と走りません。全部を通すときは全部走らせるようにしました
• 保存の種類を 2 つしか見ていなかった —— 3 つ目の保存の仕方では、この仕組みが呼ばれません。中身はその形も扱えるのに、入口が狭いだけでした
• 走ったことが、出力に 1 文字も残らなかった —— 成功したときは何も言わない作りだったので、全部を通しても「走った」と「1 本も見ていない」が同じ顔でした。走った本数を 1 行出すようにしました
• 引き戻しが「1 日に 1 度だけ」だった —— この日の事故は 3 件です。つまり 2 件目以降を全部見逃す形でした。止めたら控えを消し、次に新しく書いたら改めて止めるように直しました（控えを消すので、同じ行で鳴り続けることはありません）

最初の 2 つは、この章の前半で見つけた抜け穴（走査する置き場が 1 つ足りない）と同じ形です。4 つ目も同じ family —— こちらは置き場ではなく効く回数が狭い。同じ形が、同じ日に 4 回出ました。 3 つ目は別の形 —— 無言の成功。これは前巻が既に書いていることで、自分で置いた仕組みで踏み直しました。 中身が正しいかと、呼ばれるかは、別の話です。

一般の校閲で、どうしても仕組みにできなかった 5 つ

ここが、冒頭に引いた発話の 2 行目です（「どうしても採用難しかったもの」）。

⭐ 物差しとして、校正・校閲のタスクを 25 項目に分けた手引きを 1 本読みました。そのうち 8 項目は既に仕組みがあり、7 項目はこの本には当たりません（記事媒体向けのもの）。残りで、どうしても仕組みにできなかったのが 5 つです。

1 つ目と 5 つ目は、仕組みで覆えません。2 つ目は「書いていないか」の自動テストにできますが、本編が既に守っていて 1 度も落ちないので置きません。落ちない自動テストは、置いた分だけ読む対象が増えるだけです。

検証手順: 仕組みに落とすかを、2 つ + 1 つの問いで決める

前提

• 直したい形が、記録から数えられること（会話の記録、git の履歴、スクリプトの出力）
• 1 回しか起きていないものは、この手順に乗せません（数えるだけのスクリプトにします）

手順

1. 直したい形を 1 つに絞り、記録で回数を数える。記憶で数えない
2. 真偽が決まるかを問う。決まらないなら、そこで人が読む側に置きます
3. その文が、置こうとしている自動テストの読むファイルの中にあるかを問う（＝走査対象に入るか）。入らないなら、自動テストではなく「スクリプトの出力を言い換えずに貼る」側です
4. 置く前に書いた数を、置いたあとにもう一度出す。合わなければ、直すのは自動テストではなく、先に書いた数のほうです
5. 壊れ方を作って、落ちることを確かめる。3 種類ほど作ると、見ていない面が出ます
6. 落ちなかった壊れ方を、限界として自動テストの中に書く。合格だけ見ていると、守られている範囲を広く見積もります

合格条件

• 置く前の数と、置いたあとの数が、同じ数え方で出せること
• 作った壊れ方が全部落ちること（1 つでも落ちないなら、その面は守られていません）
• 自動テストが見ていない範囲が、自動テストの中に書いてあること

つまずいたとき

• 置いたら 0 件だった: 置く前の数の数え方が残っていない可能性があります。自動テストを疑う前に、前の数を疑ってください
• 全部合格で、1 度も落ちない: 壊れ方を作っていません。作れないなら、その自動テストは要りません
• 走査対象の外を直したくなった: それは自動テストではなく、貼り方の問題です（言い換えずに貼る）

この番外編が言えないこと

⚠️ 正直に置いておきます。

• 母数は 1 人・1 冊です。「走査対象に入るかで分ける」は、🤖私の 10 個から言っているだけです
• 10 個の切り出し方は🤖私が決めました。切り方が変われば、仕組み 4 / 人 4 という数も変わります
• 置いた自動テストが本当に節の移設を止めた日は、まだ来ていません。落ちたのは 1 度だけで、それは偽陽性でした —— この章のために書いた例示を、自動テストが本物の参照として読みました（この章の「自動テストが落ちた 1 度は、偽陽性だった」）。本当に効いたと言えるのは、誰かが節を移して、それが止まった日です
• 転んだのは、30 分足らずの中の話です。記録では、この日の作業を 13:23 に始めて、2 回は 13:34、3 回目は 13:51 です。同じ頻度で起き続けるかは分かりません
• なぜ 7 件と書いたのかは、この章に書いていません。記録に残っているのは、書いた数と、数え直した数だけです

整理して残ったもの

• 真偽が決まっても、走査対象の外にある文は、仕組みが守らない。仕組みを説明する文は、その仕組みの外側にある —— 自動テストを置いた日ほど、説明文を疑うこと
• 置く前に書いた数は、置いたあとにもう一度出す。合わなければ、疑うのは前の数のほう
• 落ちない自動テストは置かない。壊れ方を作れないものは、自動テストにする理由がない。落ちなかった壊れ方は、限界として自動テストの中に書く（合格は「守られている」ではなく「作った壊れ方では落ちなかった」）
• 合格の自動テストは、走査対象を数えて初めて合格になる。中身が正しいかと、呼ばれるかは別の話 —— この日、1 本の自動テストは 9 本のファイルを見ずに合格で、入口や効く回数が狭いだけの抜け穴が 4 回出た
• 数字はスクリプトの行のまま貼る。その書き出しは行に付くので、貼った行に 1 語足すと、その 1 語も同じ行の内側に入る
• 足した仕組みは、その日のうちに壊してみる。書いたうちの 2 つは、何も守っていなかった
• 自己テストは、走らせる場所を決めて初めて自動テストになる。4 本が、誰にも走らされずに置いてあった
• 原因が分からないものを例外として書き込まない。書き込むと、そこが逃げ道になる