罠を消すために書いた手順書が、自分で罠を仕込んでいた

転職用のポートフォリオとして、個人でWebアプリ「Hubpin」を作っています。
制作の経緯は「Hubpin 開発記録」に時系列でまとめています。
設計と判断は自分で行い、実装も原則自分で書いています。AIには手順書・レビュー・調査を任せています。

ポートフォリオとして制作中の自作アプリの開発で、実装の前に手順書を書く運用をしています。
その手順書自体に問題が出た話です。

手順書を先に書く運用にしていた

実装に入る前に、工程ごとの手順書を書いてから着手しています。
予見できる罠を先に潰しておくためです。

効果は数字で出ていました。直前の工程では見積8時間に対して実績4時間。
差の理由もはっきりしていて、手順書に書いてあった罠は全部回避できた。
唯一止まったのは、手順書に予見が無かった箇所だけでした。

つまり予見できた罠は消え、予見できなかった罠だけが時間を使った。

次の工程の手順書に、致命的な誤りが2件あった

「レビューを回したほうがいいのでは」と指摘されて読み直したら、出てきました。

誤り1: ファイルの置き場所

- middleware.ts（プロジェクト直下・src の外）
+ src/middleware.ts

src/ ディレクトリ構成のプロジェクトでは、middleware.ts はsrc/ の中に置きます。
外に置いてもエラーは出ません。ただ何も起きない。
認証の保護もセッション更新も無言で効かないので、
「なぜログインが弾かれないんだ」と実装側を疑い続けることになります。

誤り2: 同じ節の中で矛盾していた

・matcher に /dashboard を指定する
・⚠️ 公式のコードを削るとセッションが切れる（middleware はセッション更新も担当している）

この2つを同じ節に並べていました。 matcher を絞ることが、まさに「削る」に当たります。
保護は効きますが、それ以外のページでセッションが更新されず、使っているうちに勝手にログアウトされる。
しかも症状が出るのは数十分後なので、原因が matcher だと気づきにくい。

効果が実証されているぶん、間違いの害も大きくなっていた

ここが今回いちばん怖かった点です。

手順書を信頼して着手する運用になっているので、
書いてあることは疑わずに手を動かします。それが仕組みとして狙ったことでした。

だから誤った手順書は、ただの間違いではなく「信頼された間違い」になる。
自分で書いた罠に、自分で疑わずに突っ込むことになります。

見つかった誤りを「型」にした

同じ種類の間違いを繰り返さないよう、チェックリストにしました。

観点	実例
ファイルの置き場所を断定していないか	src/ の内か外か
同じ節の中で自己矛盾していないか	matcher の件
確認手順が整合しているか	「1と3は対で撮る」と書きながら3を除外していた
管理画面の UI パスを断定していないか	メニュー名はよく変わる
置き場所が未指定の関数がないか	「作る」とだけ書いてどこに置くか言っていない
公式の推奨と食い違っていないか	「動くが安全でない」選択肢

書いた直後に読み返しても効かない

自分で書いたものを直後に読むと、「書いたつもり」で読んでしまいます。
文字を追っているだけで、意味を検算していない。

なので運用としては、一度別の作業を挟んでから読むか、別のセッションに投げることにしました。

2件目 — 今度は「バージョン」が原因だった

修正した手順書で実際に着手したら、もう1件出ました。 しかも種類が違いました。

手順書には src/middleware.ts を作れと書いてあります。
Next.js 16.0 で proxy に改名されていました。

	旧（〜v15）	新（v16〜）
ファイル	src/middleware.ts	src/proxy.ts
関数名	middleware()	proxy()

ここが1件目と決定的に違う点です。

• 1件目（置き場所・matcher）は書いた側の不注意。読み直せば見つかる
• 2件目は書いた時点では正しかった可能性がある。レビューを何周回しても出てこない

手順書を書いたその日のうちに、その手順書が古くなっていました。
チェックリストで防げる種類ではないので、対策も別になります
（一次情報をバージョン一致の同梱ドキュメントで確認する運用にしました）。

3件目 — 「知っている罠」を、この場で成り立つか確かめずに書いた

さらに後の工程で、また別の種類が出ました。

テストの手順書に、こう書いていました。
「この取り方だと似た名前の別の要素にも当たるので、絞った取り方をすること。
ここは実際に踏んでから直したほうが身につく」。

実装した人が確かめたら、当たりませんでした。 そのライブラリは既定で完全一致だったんです。
一般論として知っている罠を、この道具でも成り立つかを確かめずに警告として書いていた。
しかも「踏んでから直せ」と、踏む時間まで積んでいました。

3件は種類が違った

	原因	見つけ方
1件目	書いた側の不注意	読み直せば見つかる
2件目	バージョン	一次情報を当てないと見つからない
3件目	一般論をこの場に当てはめずに書いた	実際にやってみないと見つからない

「レビューを回す」で消えるのは1件目だけでした。
2件目・3件目は、書いた側ではなく使った側にしか見えない。

落としどころ

効果が実証された仕組みほど、間違いが疑われずに通る。
手順書に限らず、テンプレート・スニペット・自動化スクリプト、全部同じだと思います。

だから手順書には、「こうなったら成功」を実際の出力まで具体的に書くようにしました。
そうしておくと、使った側が「書いてあるとおりにならなかった」と気づける。
3件目が見つかったのは、まさにその形でした。
手順書は本人の道しるべであると同時に、手順書自身の検算式になっています。