vitest run <file> は触っていないテストを回さない——CLAUDE.md の決まりを、コミットされたファイルそのものを裁く 82 本のテストにして、コミット前の 8 秒に置く
- 割引あり
push まで行ってから気づく
2026年9月27日の朝、週に1回回している「道具の見直し」のルーティンが、直近7日の push 前の関門(`scripts/local-ci.sh`。lint・型検査・テスト一式を回す、このリポジトリで唯一の品質ゲート)の失敗 18 件を原因ごとに分けて、こう報告してきました。
主因は「リポジトリ全体を裁くテスト」の群で、`CLAUDE.md` のコミット前の決まり「触ったファイルの `vitest run <file>`」では原理的に当たらない。
このリポジトリの `CLAUDE.md` には「Rules that prevent mistakes」という節があり、決まりが 9 項目並んでいます。新しいコードで `process.env` を直に読まない。`console.` でなく構造化ログを使う。画面の文言は1文ごとに改行する。使い捨てのプレビュー画面は `preview..tsx` という名前に置く(別の名前だと認証なしの公開ページになる)。こういうものです。
このうち「コミットされたファイルを読めば機械で判定できる」決まりは、文章として書くだけでなくテストにしてあります。生の色コードを増やしていないか、画面を持つルート全部にエラーの受け皿が付いているか、ブラウザ保存のキーの一覧が実装と一致しているか。こういうテストは `app/` を `readdirSync` で歩いたり、`process.cwd()` から `doc/` の文書を読んだりして、自分の import ではなく、コミットされたファイルそのものを入力にします。
ここに穴がありました。コミット前に回すのが「触ったファイルのテスト」だけだと、触ったのがコンポーネントや CSS や文書のとき、その変更で落ちるはずの「全体を裁くテスト」は1本も走りません。`vitest run app/components/Foo.test.tsx` は `app/lib/rawColorHex.test.ts` を回さないからです。違反はコミットされ、push 前の関門(30秒から数分)で初めて落ち、直してコミットし直すところから始まります。
この記事で言う「決まりのテスト」は、この「コミットされたファイルを入力にして、リポジトリの決まりを裁くテスト」のことです。property-based testing で言う invariant とは別のものです。
決まりのテストは何本あるか
2026年10月31日の実測で、テストファイル 1,071 本のうち 82 本(7.7%)がこの性質を持ちます。9月27日の時点では 861 本中 63 本でした。月ごとに足した数は、2026年7月に 2 本、8月に 18 本、9月に 50 本、10月に 12 本です。9月に急に増えたのは、画面の文言や見た目の決まりを `CLAUDE.md` に書くだけでは守られないと分かり、書いた決まりを片端からテストにした月だからです。
82 本の中身を手口で数えると(重複あり)、こうなります。
ディレクトリを歩いてファイルを集めるもの: 31 本
`doc/` の文書を読むもの: 22 本
基準値や上限を焼き付けて「増やさない」を見るもの: 23 本
TypeScript の構文木から文字列だけを拾うもの: 2 本(1文1行と、消えた画面名)
例外の印(直前のコメントに決まった言葉と理由を書く)を持つもの: 9 本
`.claude/` や `scripts/` のような、アプリの外のファイルを読むもの: 5 本
入力がアプリのコードに限らないのが特徴です。`.dockerignore` とシェルスクリプトを突き合わせるテスト、シェルスクリプトと文書の中の bash のコード囲みを読むテスト、`doc/` の台帳の形を見るテストがあります。
代表例で見る 6 つの型
以下の例は、このリポジトリの決まりです。「1文1行」や「生の色コードを書かない」を読者に勧めているのではなく、型の説明に使っています。
(a) ルートを import せず、テキストとして読む
`routeErrorBoundaries.test.ts`(8月8日)。画面を持つルート全部が `ErrorBoundary` を export しているかを見ます。無い画面で loader が落ちると、親のルートが受けて、Shopify の素っ気ないエラー表示がアプリ全体を置き換えます。新しい画面を足したときに付け忘れるのが唯一の壊れ方なので、ファイルを歩いて中身を見るのが合っています。
要点は import しないことです。ルートのモジュールを import すると、読み込みの時点で `shopifyApp()` が走り、本物の環境変数が要ります。`readFileSync` で読んで正規表現で `export function ErrorBoundary` か `as ErrorBoundary` を探すだけにしてあります。
もうひとつ、「対象のルートが 8 本以上ある」という下限のテストが先頭にあります。フィルタが壊れて対象が 0 本になると、後ろの `it.each` が1本も走らず緑になるからです。全体を裁くテストには、この「見る対象がある」の裏取りを必ず1本付けます。
(b) 基準値を焼き付けて、増やさない
`rawColorHex.test.ts`(8月19日)。意味のある色を生の hex で書かず、デザイントークンを使う決まりです。書いた時点で既存の生 hex は何十件もあり、今日全部直すのは無理でした。そこでファイルごとの件数を `BASELINE` という表に焼き付け、件数の一致を要求しています。増えれば落ちます。減らしたときも落ちます。数字を下げるところまでが片付けで、下げ忘れた数字はその分だけ緩みとして残るからです。
同じ理由で「`BASELINE` に実在しないパスが残っていない」も見ます。消えたファイルや改名したファイルの行が残ると、その数字が誰にも使われない緩みになります。
基準値には2つの方針があります。`polarisReactImportCeiling.test.ts`(10月5日)は、廃止予定の UI ライブラリを import するファイル数の上限(app 側 223・テスト側 13)を見ますが、こちらは減っても PR では上限を下げません。下げるのは毎晩の自動整形です。理由は並行する PR です。ファイル別の件数の表は、別の PR が別の行を触るので衝突しにくい。単一の上限は、画面を1本ずつ移している複数の PR が同じ1行を下げようとして衝突します。「ファイルごとの表なら減ったら下げる、単一の上限なら夜にまとめて下げる」で分けています。
(c) 一覧の完全性は、最後の1本で grep して閉じる
`localStorageKeys.test.ts`(8月29日)。ブラウザ保存のキーは `localStorageKeys.ts` に全部並べ、「全部 `myapp.` で始まる」「重複しない」「動的なキーは前半が共通」を見ます。ただ、名前の決まりを縛るだけでは、新しいキーがこの一覧を通らずに増えるのを止められません。
そこで最後の1本で `app/` の実装ファイルを全部読み、文字列リテラルの中に `myapp.` で始まるものが一覧のファイル以外に無いことを見ます。これで「一覧に足さずに使う」が落ちます。grep が「たまたま何も見つからない」形で通っていないかの裏取りに、既知の1件を拾えることも見ています。
(d) 2つのファイルの整合は、両方読んで集合で比べる
`dockerIgnoreParity.test.ts`(9月7日)。デプロイ前に「未コミットの変更が無いか」を見るスクリプトは、`Evidence/` と `.claude/` の汚れを見逃します。根拠は「`.dockerignore` に入っているのでイメージに出荷されない」の一点だけです。つまり `.dockerignore` からどちらかが落ちた瞬間、「未コミットの変更がデプロイされる」を止めるはずの関門に穴が開きます。しかも静かに開きます。デプロイは今までどおり成功します。
それまでは、両方のファイルに同じ2つの名前がリテラルで書いてあり、揃えることはコメントで頼んであるだけでした。テストは `.dockerignore` の目印に挟まれた行と、スクリプトの `:(exclude)名前` を両方読んで、同じ集合であることを見ます。「スクリプト側が1件以上ある」という下限を先に置くのは (a) と同じ理由で、空と空の比較で通さないためです。
(e) 例外は、コメントの印に理由を付けて1か所だけ
`oneSentencePerLine.test.ts`(9月11日)。画面の文言は1文ごとに改行する、という決まりです。`app/` の文字列リテラル・テンプレート・JSX の直書きを TypeScript の構文木から拾い、1行に2文以上が並んでいたら名指しで落とします。
翌日に継ぎ目を足しました。`"…。" + "…"` のように `+` でつないだ文字列は、リテラルを1つずつ見ていると継ぎ目で2文が並んでも見えません。左の最後の行と右の最初の行をつないで判定するようにしました。
例外は3通りです。画面に出ない文字列だけのファイルを丸ごと外す、トーストや読み上げ名のようなキー名で外す、そして直前8行以内のコメントに「1文1行の例外」と理由を書いてその1か所だけ外す。3つ目が本命で、ファイルごとの除外は増えやすく、理由付きの印は増えにくい。82 本中 9 本がこの型の印を持っています。
同じ型に `retiredScreenNames.test.ts` があります。改名で消えた画面名が、利用者に見える文言に戻ってきていないかを見ます。改名の直後は文言の置き場だけ直してあり、よくある質問・吹き出し・メールの本文に旧名が残っていました。旧名の配列は消さずに足し続けます。
(f) 実物に違反が無いと素通りするテストは、偽物を作る
`previewRoutes.test.ts`(8月30日)。使い捨てのプレビュー画面が本番のビルドに出ないことを見ます。きっかけは、プレビュー3本が staging で認証なしの HTTP 200 を返していたことです。
ただ、プレビューは足したり消したりするので、実物の `app/` だけを見るテストは、プレビューが1本も無い日に穴が開いていても素通りします。そこで一時ディレクトリに偽の `preview.*.tsx` を作り、本物のルーター設定(`flatRoutes` と `ignoredRouteFiles`)をそのまま走らせて、本番の設定では拾われず開発の設定では拾われることを見ます。
入力はアプリのコードに限らない
`shellMultibyteVar.test.ts`(9月13日)。シェルスクリプトで `$変数` の直後に全角文字を置かない、という決まりです。macOS 標準の bash 3.2 は、ロケールが UTF-8 のとき `"$BRANCH)"` の `)` の1バイト目を変数名の続きとして読み、`set -u` の下で即死します。たちが悪いのはロケールで結果が割れることで、Claude Code のセッションや launchd は C ロケールで通り、オーナーが Terminal から流したときだけ落ちます。つまり関門では捕まらない種類の壊れ方です。見る範囲は `scripts/` の `.sh` と shebang 付きのファイル、文書の中の bash のコード囲み、`package.json` の scripts、GitHub Actions の workflow です。
`singleInstanceSchedulers.test.ts` は、`setInterval` を持つサーバー側の処理が「単一起動の台帳」に登録されているかを見ます。登録の無い定期処理は、サーバーの台数を増やした日に二重に走ります。
ESLint のルールで済まないのか
最初に思う反論です。1ファイルで判定できる決まり(`process.env` の直読み、`console.*`)は ESLint か、書いた直後のフックで十分で、このリポジトリでもそうしています。テストにするのは、(c) 一覧の完全性や (d) 2ファイルの整合のように集合が要るもの、入力が JS でないもの(文書・`.dockerignore`・シェル)、(b) のように基準値の増減を持つものです。
コミット前に回す分を、パスの一覧でなく性質で選ぶ
直しは `npm run test:invariants` を足すことでした。82 本だけをまとめて、コミット前に回します。設計で決めたことを順に書きます。
パスを並べない
最初に捨てた案が「全体を裁くテストのパスを配列に並べる」です。テストが増えたときに腐ります。足した人が配列の存在に気づけないので、新しいテストは配列に入らず、コミット前に回らず、また push 前で落ちます。
代わりに性質で拾います。テスト本体か、テストが辿れるリポジトリ内のモジュールのどれかが、ディスクからリポジトリのファイルを読んでいるか。判定は2条件です。
ディレクトリを歩く: `readdirSync`・`readdir(`・glob 系・`git ls-files` が書いてある。推移で見る
リポジトリのルートから決まったファイルを読む: `process.cwd()`・`import.meta.url`・`import.meta.dirname` が書いてある。または `readFileSync` / `existsSync` のような fs の読みと、トップレベルのディレクトリ名で始まる文字列(`"public/…"`)の両方がある。テスト本体だけで見る
推移で見る理由と、循環の扱い
歩く処理はヘルパーに寄せてあることがあります。`checklistTags.test.ts` 自身は `readdirSync` を呼ばず、import 先の `checklistLedgerFiles.ts` が台帳のディレクトリを歩きます。テスト本体だけ見ると取りこぼすので、import を辿ります。
辿り方に1つ罠があります。import の向きに素直に再帰して「この先に歩く処理があるか」を返す書き方だと、モジュールが循環しているところで「まだ見ている最中だから false」と答えてしまい、落とす側に間違えます。なので先に import の graph を組み、「歩く」の印を import の逆向きに伝播させ、変化が無くなるまで回します。循環があっても同じ答えになります。
process.cwd() を推移で見ない理由
ルートから1本読むのはアプリの実行時の振る舞いとして普通にあります。テンプレートや資料の読み込みです。それを import しただけの画面のテストまで巻き込むと、段が倍以上に膨らみます。9月27日の実測では 45 本が 94 本になり、増えた分は「触ったファイルの vitest run」で当たる普通のテストでした。テストのファイルが自分でルートからの読みを書いているときは、それが入力なので対象にします。
入れすぎる側に倒す
取りこぼしても関門は狭まりません。push 前の `local-ci.sh` の Test 段は従来どおり全部を回します。ここは「push まで行ってから気づく」のをやめるための追加であって、検査を減らす変更ではありません。なので判定は入れすぎる側に倒してあります。`process.cwd()` を読み書き以外で使うテストが数本混じっても、秒単位では変わりません。
実際、選別器自身のテスト(`repoWideTests.test.mjs`)も選ばれます。import 先の選別器のソースに `readdirSync` という正規表現が文字列で書いてあるので「歩いている」と読まれるからです。害が無いので放ってあります。
まだ add していないテストも見る・DB を触るものは外す
ファイルの一覧は `git ls-files --cached --others --exclude-standard` で取ります。コミット前の段なので、いま書いたばかりの「全体を裁くテスト」が `git ls-files` だけでは見えないと困ります。`.gitignore` のものと `node_modules` は入りません。
本物の Postgres を触るテストは外し、vitest の unit プロジェクトに固定して回します。こちらは関門の側で走ります。
翌日に直した取りこぼし 4 本
9月28日、夜間の変更確認が `--list` から漏れている 4 本を見つけました。起点が `import.meta.dirname` のものが 3 本、`existsSync("public/…")` のように起点を書かず素の相対パスで読むものが 1 本です。判定の正規表現を広げ、4 本が選ばれることを選別器のテストで実ファイルに当てて固定しました。性質で拾う判定は、こうやって育てるものです。初日で完成するとは考えないほうがよいです。
実測
9月27日に入れた時点で、63 本・963 件を 8 秒で回しました。静かな M1 Pro(10コア・32GB)で 7.8 秒と 7.9 秒。同じ機械で push 前の関門を2本流している最中(load 16)でも 7.7 秒から 9.1 秒で、いちばん重かった1回が 13.7 秒でした。初回は `prisma migrate deploy` が乗って 2 秒ほど増えます。テスト一式 `npm run test` は 30 秒弱なので、その4分の1です。
10月31日は 82 本・1,302 件で、vitest の表示が 7.4 秒、起動込みで 8.7 秒でした。本数が 3 割増えても秒数が変わらないのは、増えた分が軽いからです。
runner の冒頭には「30 秒を超えるようになったらコミット前に置くには重いので、段の置き場を考え直す」と書いてあります。コミット前の段が守られるのは、8 秒で終わるからです。
運用して見えたこと
9月27日以降の 1,293 コミットのうち、この 82 本のテストを触ったコミットが 115(8.9%)ありました。決まりが増えるか、例外が増えるか、基準値が減るたびにテストの側も動きます。決まりをテストにすると、決まりの変更がコミットの履歴に残ります。
落とし穴も1つありました。10月18日の道具の見直しで、`releaseNotes.test.ts` が `git tag --list` でリポジトリ全体の最新タグを読んでいるため、遅れているだけの作業ツリーが落ちることが分かりました。本体の main が 15 コミット遅れていて Test 段が赤、origin/main は緑。全体を裁くテストは「コミットされたファイル」を入力にする分には作業ツリーごとに同じ答えを出しますが、タグやブランチのような「リポジトリの状態」まで裁くと、作業ツリーの鮮度で結果が割れます。翌日、全タグの最新ではなく、HEAD から辿れるタグの最新(`git tag --merged HEAD`)と比べる形に直しました。git の状態を見るテストは、コミット前に置かないか、見る先を作業ツリーの HEAD から辿れる範囲に絞ります。
決まりをテストにするか、フックにするか、関門にするか
このリポジトリでは、決まりを止める場所が3つあります。実行前フック(記事 07)、毎回読むファイルの大きさの関門(記事 12)、そしてこの記事の決まりのテストです。決まりを1行書く前に、上から順に当てます。
実行の前に止めないと取り返しがつかない(`git push --force`・`rm -rf`・本番へのデプロイ)→ 実行前フック。コマンドの文字列を見て止める。テストでは遅い
書いた直後に、そのファイル1本だけで判定できる(`process.env` の直読み・`console.*`・テストをルートのディレクトリに置く)→ 書き込み後のフックか ESLint。今回増えた行だけを見て、その場で差し戻す
コミットされたファイルを読めば判定できる(全ルートがエラーの受け皿を持つ・生 hex を増やさない・一覧の完全性・2ファイルの整合・消えた名前)→ 決まりのテスト。既存の違反があるなら基準値を焼き付けて「増やさない」から始める。例外は直前のコメントに印と理由
コミットの履歴や複数コミットの関係で決まる(新機能のコミットに動作確認の項目が付いているか)→ push 前の関門のスクリプト。コミット前では効かない
機械で判定できない(文言の分かりやすさ・見た目・設計の良し悪し)→ `CLAUDE.md` の1行として残す。ただし「守られない前提」で、守られなかったときに気づける数え方(週次の集計)を別に持つ
コミット前は 8 秒、push 前は全部、という二段です。コミット前の段は速さで守られ、push 前の段は網羅で守られます。
決まりのテストを書くときの型は、上の 6 つです。(a) 全部が X を持つ、は歩いてテキストで見る。(b) 増やさない、は基準値の一致。(c) 一覧の完全性は最後の1本の grep。(d) 2ファイルの整合は集合の比較。(e) 消えた名前は配列を足し続ける。(f) 違反が無いと素通りするものは偽物を作る。どの型でも「見る対象がある」の下限を1本先頭に置きます。
検証環境
macOS、Node 24、vitest 5、Apple M1 Pro(10コア・32GB)
計測日: 2026年9月27日(63 本・963 件・8 秒、861 本中)と 2026年10月31日(82 本・1,302 件・7.4 秒、1,071 本中)
有料部分の素材は、git init した空のプロジェクトに置いて 2026年10月31日に動かしました。選別で 7 本中 6 本が選ばれ 46 件が通ること、5 本の雛形がそれぞれの違反で落ちること、例外の印で通ること、まだ `git add` していないテストが `--list` に出ることを確かめてあります
有料部分に入っているもの
置き方(最初の 5 分): 3 ファイルを置く → `package.json` に 2 行 → `--list` で選ばれたテストを見る → 1本も選ばれないときに見る場所。書き換える箇所の一覧
選別器 `scripts/lib/repoWideTests.mjs` の全文(約 180 行。推移・不動点・取りこぼしの直し込み)。書き換えるのはトップレベルのディレクトリ名の1行
runner `scripts/run-invariant-tests.mjs` の全文(`--list` 付き。DB の分岐を外した汎用版)。書き換えるのは除外の前方一致と vitest の引数の2行
選別器のテスト `scripts/lib/repoWideTests.test.mjs` の全文(偽のリポジトリで判定を固定。判定の条件を足したときの安全網)
決まりのテストの雛形 5 本(上の (a)〜(e) と1対1。各ファイルの冒頭に「書き換える場所」)。(a) 全ルートが X を export/(b) 生 hex の基準値(判定の小さなモジュール付き)/(c) 一覧の完全性を grep で閉じる(一覧のファイルの雛形付き)/(d) 2ファイルの整合/(e) 消えた名前が文言に戻らない(例外の印付き)
`package.json` の scripts と `CLAUDE.md` の節