つまずいたとき、どの層で止まっているかを先に決める

15回かけて道筋を作りました。実際に歩くと、あちこちで詰まります。

この回で扱うのは、個別の対処法の一覧ではありません。どこで止まっているかを決める順番です。順番が決まっていれば、知らない症状でも調べる場所を絞れます。

症状ではなく、層で切り分ける

エラーの文面から原因を当てにいくと、当たるまで探し続けることになります。当たらないうちは、何も進みません。

代わりに、下から順に「ここまでは正しい」を確かめます。層は5つです。

1. 道具が動いているか
2. 依頼が届いて、実行できているか
3. 出てきたものが、頼んだものと合っているか
4. 他の環境でも通るか
5. 実際の画面で正しく動いているか

上の層の症状に見えても、原因が下の層にあることは珍しくありません。だから下から確かめます。

層1: 道具が動いているか

Codex そのものが動いていない場合です。ここには専用の道具があります。

codex doctor

第2回で載せた出力を、もう一度引きます。執筆環境で実行した実物です。

Notes
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key ...
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - ...
   ✗ reachability one or more required provider endpoints are unreachable over HTTP - ...

認証、通信、ディスク、Git の検出が並びます。ここに印が付いているなら、上の層を調べても無駄です。

この層で一番多いのは認証切れです。しばらく使っていなかったあとに動かないときは、まずここを見てください。

層2: 依頼が届いて、実行できているか

道具は動くが、作業が進まない場合です。

最初に疑うのはネットワークです。第5回で扱ったとおり、既定の workspace-write では外へ出られません。npm install も pip install も失敗します。「依頼したのにライブラリを入れてくれない」の原因は、ほぼこれです。

次に疑うのは範囲です。作業フォルダの外にあるファイルは、既定では書き換えられません。編集したいファイルがフォルダの外にあるなら、--add-dir で足すか、起動するフォルダを変えます。

どちらでもないときは、枠の中で実際にコマンドを打ってみます。

codex sandbox npm test

Codex と同じ枠の中で走るので、枠が原因かどうかがはっきりします。

層3: 出てきたものが、頼んだものと合っているか

動いてはいるが、返ってくるものが的外れな場合です。

原因が2つに分かれます。

依頼が足りていないなら、第6回の3つを見直します。文脈と制約と完了の条件。抜けているのはたいてい完了の条件です。

会話が長すぎるなら、/compact で畳みます。長い会話を持ち続けると、古いやり取りに引きずられて、もう関係ない前提で答えが返ります。答えが急に的外れになったら、まず畳む。作業を変えたのに会話を続けている状態が、この症状の一番多い原因です。

差分が大きすぎて読めないときは、直す先が依頼の側です。第7回で書いたとおり、1つの依頼で20ファイルが変わるなら依頼が大きすぎます。分けてください。

層4: 他の環境でも通るか

手元では通るのに、GitHub Actions で落ちる場合です。

原因は1つに絞れます。手元の環境に、記録されていない何かが残っている。手で入れた道具、生成されたまま追跡されていないファイル、設定した環境変数。このどれかです。

確かめ方は、使い捨ての環境で一から組み立てることです。第14回で触れたクラウドの環境設定も、第13回のワークフローも、これを書き出す作業でした。書き出せていないものが、この症状として出てきます。

BenriWorks でも何度か踏みました。書式の自動整形を手元で通していなかったために落ちたことがあり、そのときは整形を走らせて反映しただけで直りました。もう1つは、設計資料の内容から計算した指紋を検査していて、資料を書き換えたのに指紋を更新していなかった例です。検査そのものは正しく働いていました。

層5: 実際の画面で正しく動いているか

ビルドも検査も通っているのに、開くと動かない場合です。ここが一番やっかいで、実際に開いて確かめるしかありません。

実際に踏んだものを3つ挙げます。

ひとつは、開発用のサーバーで確認していて気づかなかった例です。開発用サーバーの通信がうまくつながらず、画面は出るのに操作が一切効かない状態になっていました。ビルドしたものを配信する形で起動し直したら、そのまま動きました。開発用の起動でおかしいときは、本番と同じ組み立て方で一度確かめる。

ふたつ目は、記述の中のエスケープが壊れていた例です。画面の部品の中に文字列として埋め込んだ処理に、そのままでは通らない書き方が混ざっていて、ブラウザで構文の誤りになっていました。サーバー側の検査は全部通っています。文字列として埋め込むものは、埋め込んだあとの形で確かめないと分かりません。この件のあと、埋め込んだ結果の構文を検査する項目をビルドの前に足しました。

みっつ目は、安全のための設定が原因だった例です。読み込む先を制限する設定があり、そこに計測用の送信先が入っていなかったために通信が全部止まっていました。コードは正しく、設定が足りていませんでした。

3つに共通するのは、ソースコードを読んでも分からないことです。この層の調査は、必ず動いているものを見てください。

調べ方そのものを間違えた例

もう1つ、層の話とは別の失敗を書きます。

16のサイトで計測が届いているかを確認する仕事で、渡した仕様書に「読み込む先を制限する設定は、どのリポジトリにも入っていない」と書いてありました。これが事実と違っていました。

なぜ間違えたかというと、リポジトリの中の文字列を検索して、見つからなかったから「ない」と結論していたからです。実際には、配信の設定として付いていました。本番の応答を見れば分かったことです。

探した場所にないことは、存在しないことを意味しません。設定は、コードの中だけでなく、配信の設定や管理画面にも置かれます。「ない」と書くときは、どこを探して「ない」と言っているのかを自分に確認してください。

この失敗の記録は「GPT-6 Astra の Codex に、16サイトの疎通確認を任せた記録」にまとめています。

直せないときに残すもの

全部が直るわけではありません。時間の制約で、分からないまま進めることもあります。

そのときに残すのは2つです。

何が起きているかの記述。再現する手順、出たエラー、試して駄目だったこと。将来の自分か、誰かが引き継ぎます。

そして、確かめていないと分かる形の印です。BenriWorks では、本文に TODO: 要確認 の形で残す約束にしています。第9回で引用した規約の3行がこれにあたります。分からないことを分からないと書く形式が先に決まっていると、埋めるために推測する動機がなくなります。

一番まずいのは、直っていないのに直ったことにすることです。次に困る人が、直っている前提で調べ始めます。

次の回

道具の話はここで終わりです。

最終回は、道具ではない話をします。ここまで作ってきた仕組みの上で、何を任せて何を自分で決めるか。この講座が結局のところ何のためのものだったかを書きます。

参照した情報

• codex doctor の出力は codex-cli 0.154.0 を執筆環境へ導入して取得
• 挙げた失敗は BenriWorks の各リポジトリで2026年に実際に起きたもの