実例編

npm run dev を7層で追う

毎日打っているこの1行が、7つの層をどう通り抜けているか。

1. シェル

   npm という名前のファイルを探す

   bash が PATH に並んだフォルダを先頭から順に見て、npm という名前のファイルを探します。見つかったら自分の複製を作り、その中身を上書きしようとします。第1部の第4章そのままです。

   $ which npm /usr/local/bin/npm
2. OS カーネル

   ファイルの先頭2文字を見る

   カーネルがそのファイルを開いて先頭を確認すると、こう書かれています。

   #!/usr/bin/env node

   先頭の #! はシバン（shebang）と呼ばれる印で、「これは機械語の実行ファイルではない。後ろに書いたプログラムに読ませてくれ」という指示です。

   だからカーネルは npm を直接動かすのではなく、node を起動して npm のファイルを引数として渡します。npm 自体が JavaScript で書かれたプログラムであり、Node の上で動いているということです。

3. Node.js

   JavaScript として解釈する

   node が起動し、V8 エンジンが npm のコードを読み込んで実行を始めます。ここで初めて「JavaScript が動いている」状態になります。

4. npm

   package.json を読んで、dev の中身を取り出す

   npm が今いるフォルダの package.json を開き、scripts の中の dev という項目を探します。

   "scripts": { "dev": "next dev" }

   つまり npm run dev それ自体は何もしません。package.json に書いてある別のコマンドを呼び出す代理人です。実際に動くのは next dev です。

   ここで npm がもう一仕事します。node_modules/.bin というフォルダを PATH の先頭に一時的に付け加えます。これがあるから、next をパソコン全体にインストールしていなくても next という名前で呼べます。

5. npm

   next を子プロセスとして起動する

   npm がさらに自分の複製を作り、その中身を next で上書きします。ここでも fork と exec が起きています。プロセスの親子関係は bash → node(npm) → node(next) という三段になります。

6. Next.js

   URL とファイルの対応表を作る

   next が app/ フォルダの中を走査し、どのファイルがどの URL に対応するかの表を組み立てます。

   app/page.tsx → / app/staff/page.tsx → /staff app/api/csv/route.ts → /api/csv

   置き場所がそのまま URL になる。第1部の原則1「すべてはファイルである」の直系です。

7. OS カーネル

   ポートを確保する

   Next.js がカーネルに「3000 番ポートで待ち受けたい」と依頼します。空いていればカーネルが割り当て、すでに他のプロセスが使っていれば拒否されます。

   Error: listen EADDRINUSE: address already in use :::3000

   あの見慣れたエラーは、この段階で出ています。Next.js の問題でもコードの問題でもなく、OS がポートを渡せなかったという報告です。

8. Next.js

   終わらずに待ち続ける

   準備が終わっても Next.js は終了しません。リクエストを待つことが仕事なので、意図的に生き続けます。

   だからターミナルにプロンプトが戻ってきません。第1部で見た「親が子の終了を待つ」状態のまま、子が永遠に終わらないためです。Ctrl+C を押すと、その待機を強制的に打ち切ることになります。

同じ仕事を3つの層でやってみる

同じ結果を、シェル・Node スクリプト・Next.js の3通りで出します。

題材として、こういう従業員データがあるとします。employees.csv という名前のテキストファイルです。

やりたいことは「週の所定労働時間が20時間以上の人を抽出し、賃金の高い順に並べる」です。

方法1 ─ シェルで1行

3つの独立したプログラムが、パイプでつながっているだけです。

awk は絞り込みしかしません。sort は並べ替えしかしません。それぞれが一つのことしかしないから、順番を入れ替えたり別のものに差し替えたりできます。第1部の原則2と原則3が、そのまま目に見える形で現れています。

部品を入れ替えると、別の集計になります。

部署の列だけ取り出し、並べ、同じものを数え、多い順に並べる。4つつないだだけで部署別人数が出ます。新しいプログラムは1行も書いていません。

向いている場面は、今この場で1回確認したいとき。所要1分、作るものはゼロです。限界は、条件が複雑になると誰も読めなくなること、そして人に渡しにくいことです。

方法2 ─ Node スクリプト

判定条件が複数の組み合わせになると、シェルでは苦しくなります。そこで一段上げます。

向いている場面は、毎月繰り返す作業。ファイルとして保存できるので、来月も同じものが動きます。限界は、ターミナルを使える人しか回せないことです。

方法3 ─ Next.js の画面

職員が使うなら、ブラウザで完結させる必要があります。ファイルをこう置きます。

判定ロジックは方法2で書いたものがそのまま流用できます。変わるのは、結果を console.log で出すか、画面に表として描くかだけです。

向いている場面は、自分以外の人が使うとき。代償は、作る手間、保守の責任、そして誰がどこまで見られるかという設計です。

どの層で作るかの判断

3つの方法に優劣はありません。適する場面が違うだけです。

一段上げるたびの取引

層を一段上げるたびに、作る手間は増え、使う人の負担は減ります。この交換をどこで止めるかが設計判断です。

そして重要なのは、いきなり上から作らないことです。

まずシェル1行で確かめる。繰り返すことが分かってからスクリプトにする。他人が使うと決まってから画面をつける。この順番を守ると、要らないものを作らずに済みます。逆にいきなり Next.js から始めると、月1回しか使わない機能に数日かけることになります。

「Python で作れ」と言われたとき

Excel の申請書を自動化したい、という場面でよく出る助言です。

「アプリを作るより Python のほうがいい」という言い方は、3つの別々の話を1つに束ねています。ほどくと見通しがよくなります。

この助言の実質は、たいてい軸1と軸2の話です。「画面を作らず、手元で動かせ」と言っている。Python という言語名は、その結論に付いてきただけのことが多い。

同じことは Node.js でも書けます。ですので最初に立てるべき問いは「アプリか Python か」ではなく、「アプリか、スクリプトか」です。

Excel の場合、往復が丸ごと無駄になる

Excel の申請書は、すでに手元のファイルとして存在しています。ここが決定的です。

上の往復は、Web アプリにしたせいで発生した工事であって、元の仕事とは無関係です。しかもアップロードとダウンロードのぶん、職員の操作手順はむしろ増えます。「自動化したのに手数が増えた」という結果になりがちなのは、この構造のためです。

ただし Excel だけは、言語の差も独立に効く

軸3（何語で書くか）が本当に効く数少ない領域が、まさに Excel です。

JavaScript にも SheetJS があり、読み書き自体は十分できます。ただし書式まわりは無償版だと制約があり、「元のブックの体裁を崩さずに値だけ埋める」という申請書の用途では Python のほうが素直です。

判断表

分かれ目はファイルが最終形かどうかです。Excel を作って終わりならスクリプト。データを溜めて後から使い回すならアプリ。この一問で、たいていの場合は決まります。

中間形態がある

いきなり画面を作らずに済ませる手が2つあります。

「画面が要る」ことと「Web アプリにする」ことは別です。ここを分けて考えられると、選択肢がかなり広がります。

前章の図との対応

Python スクリプトは、前章の図の「Node スクリプト」とまったく同じ位置にあります。言語が違うだけで、層としては同一です。

ですので判断基準も変わりません。誰が何回使うかに尽きます。Excel の申請書は、たいてい「担当者が毎月」なのでスクリプトの領域に落ちる。冒頭の助言は、経験則として当たっているということです。

ただし理由が「Python だから」ではなく「その仕事はスクリプトの層だから」だと理解しておくと、条件が変わったとき ─ たとえば顧問先にも使わせることになったとき ─ に判断をやり直せます。

エラーを層で追う

実際によく出る4つを、層に対応づけて読みます。

切り分けの原則

下から上へ確認する。上の層で悩む前に、下が正常であることを確かめます。

この5行を先に流すだけで、原因の大半がどの層にあるか判明します。そしてその情報を持って AI に相談すると、返答の精度が変わります。

後者に対して AI は、Vercel 側の環境変数登録が抜けているという結論に一手で到達します。前者に対しては、可能性を10個並べるしかありません。効いているのは技術力ではなく、どの層で止まったかを言語化する能力です。

プロジェクトの構成を読む

Next.js プロジェクトの標準形。ファイルが20個以上並んでいても、種類は3つしかありません。

分類は3つだけ

自分が書いたもの（資産。消えたら困る）、機械が自動生成したもの（消しても再生成される）、設定ファイル（自分が書くが、中身は道具への指示）。この3つです。

① 自動生成されるもの

下2つが例外です。package-lock.json は「他の環境でも同じものが再現される」ための唯一の保証なので必ず記録します。next-env.d.ts は編集しても上書きされますが、記録する慣例です。

② 設定ファイル

③ 自分が書いたもの

なぜ設定ファイルが7つもあるのか

ここが第1部の原則に直接つながります。

ルート直下に設定が散らばっているのは、道具が独立して7つあるからです。Next.js、TypeScript、Tailwind、PostCSS、Drizzle。それぞれ別の作者が作った部品で、互いのことを知りません。だから設定もそれぞれ持ちます。

全部入りの一枚岩なら設定は1ファイルで済みます。ただし Tailwind を別の CSS ツールに差し替えることも、Drizzle を Prisma に替えることもできなくなります。

散らばっているのは混乱ではなく、原則2「一つのことをうまくやる」と原則3「組み合わせて使う」の代償です。差し替えられる自由の対価として、組み合わせを記述する手間を払っている。第1部で見た一枚岩と部品の対比が、そのままファイル一覧に現れています。

ルート直下に置く理由も単純で、各道具は起動時にカレントディレクトリから親方向へ設定を探しに上がるためです。プロジェクトの根に置くのが約束事になっています。

.env が2枚ある理由

これは第4章の CASE 4（Vercel で DATABASE_URL が undefined）に対する予防策そのものです。

新しい環境で立ち上げるとき、example を見れば必要な項目が全部わかります。値そのものは漏れません。「秘密は共有しないが、秘密の一覧は共有する」という分離です。この2枚組を作っておくと、環境を移すときの事故が減ります。

.gitignore が引いている境界線

この1ファイルが、プロジェクトの中に見えない線を引いています。

線の外側に置かれる理由は3つに整理できます。再生成できる（node_modules、.next）、秘密である（.env.local）、環境ごとに違う（.vercel）。この3つのどれかに当てはまるものは、記録しません。

困ったときの初期化

動作が怪しいときの定番手順です。①の自動生成物のうち3つを消すだけです。

消えたものはすべて自動生成物なので、失うものはありません。node_modules の再取得に数分かかるだけです。

第4章の CASE 3 で挙げた package-lock.json の削除は、ここには含めていません。あれは lock ファイル自体が壊れている疑いがあるときの最後の手段で、通常は残します。消すとバージョンが変わりうるので、再現性を捨てる操作だと理解しておくのが安全です。

エージェント型 CLI の構造

Claude Code や Codex CLI は、シェルではありません。

これらはシェルの上で動くプログラムであり、同時にシェルを使う側でもあります。二重の立場を持っているのが特徴です。

エージェントは、これまで人間が座っていた席に座っています。第1部で見た「シェルに翻訳を頼む」という立場そのものを代行している。

だから設計上の中心問題が権限になります。人間の席に座った以上、原理的には rm -rf も打てるからです。エージェント型 CLI の機能一覧が権限まわりに偏っているのは、この構造から必然的に出てきます。

4つのツールに共通する骨格

主要なエージェント型 CLI は、いずれもほぼ同じ仕組みを持つところへ収束しました。

骨格が共通化した結果、各ツールの差はモデルの質・価格・エコシステムへ移りました。そこは週単位で動くのでこの資料には書きません。骨格を知っていれば、どのツールへ移っても同じ場所を探せば設定できます。

miraise-crm の現物との対応

前章で見たルート直下のファイルが、そのままこの構造に対応しています。

指示書を書くという行為の意味も、ここで定まります。席に座らせる前に、業務の文脈を渡しているということです。第2部第0章で挙げた「AI は事務所の業務も顧問先の事情も知らない」という制約に対する、唯一の実務的な対処がこれにあたります。

この章の内容のうち、製品名と提供状況は2026年7月時点のものです。骨格の部分は当面変わらないと見ていますが、個別の製品情報は都度確認してください。

ゼロから公開までの全コマンド

各コマンドが、どの層に触っているかを対応させます。

最後に ─ 3部を通して

第1部でシェルの仕組みと設計原則を見て、第2部で層の全体像を見て、第3部で実際のコマンドに落としました。

結局のところ、覚えておくべきことは多くありません。

実装の速さは AI の側に移りました。だからこそ人間の側に残るのは、何を作るかを決める力と、出てきたものを疑う力です。そのどちらも、土台の構造を知っていることを前提にしています。