開発秘話①: 指示厨ゲーム

Linuxを「怖いもの」から「触りたいもの」へ。UNIX哲学を“体験”にするための開発戦記。

czzは、Linux/UNIXの考え方（小さく作って、つないで強くする）を“体験”として学べるように作った学習ゲーム。LPIC-1学習にも役立つのが狙い。
当初は2人で始めたが、途中で1人になり、納期まで約2か月という制約の中で生成AIを最大限活用して走った。
ただし「モダン全部盛り＋凝ったアーキテクチャ」で複雑さが爆発し、何度も壊して直してを繰り返した。最後は issue単位で作業を分割 し、迷子と巻き戻しを減らす運用へ切り替えて持ち直した。

!NOTE 「最初から完璧に」じゃなくて、「壊れても戻れる」方向に舵を切ったのが転機だった。

目的：なぜ czzアプリを作ろうと思ったか

Linuxをもっと身近に感じてほしい
UNIX哲学の素晴らしさを“体験”として味わってほしい
LPIC-1の学習が、苦行じゃなくて少しでも楽しくなる形にしたい

czzアプリは「学習の補助輪」であり、「遊べる実験場」でもある。
失敗しても怖くない形で、コマンドの組み合わせや考え方を身体で覚えられるのが理想だった。

!NOTE 読んで理解するより、触って理解したい。これ、Linux学習あるあるだと思う。

プロローグ：パーティが解散した

元は2人態勢で、ペアで作業する予定だった。
相方は「あまり会話が得意じゃなさそう」だけど、個人開発経験は少しあると聞いていた。

まずはイメージが大事だと思って、ゲームの環境構築して「動く状態」を作って共有した。
「いい感じ」と返事が来たので、「cloneしておいてね」と伝えた。

……返事が来ない。

1か月ほど経ってから今後の方針を確認すると、「辞退したい」とのこと。
結果、開発は一人旅になった。なんということ…

!NOTE この時点で、地味にダメージ。だけど、ここで折れたら終わる。

第一章：散歩中に“草案”が降ってきた

納期まであと2か月ちょい。
散歩していた時に、ふっと czzアプリの草案が浮かんできた。

「これだ」と思った。
ただ、せっかく作るならモダンな技術を盛って、アーキテクチャもがっつり凝りたい。
でも一人で全部は難しい。そこで 生成AIを最大限使う 方針に寄せた。

!NOTE この時の私は、燃えてた。燃えると盛りたくなる。盛ると燃える（地獄の循環）。

第二章：召喚獣・生成AI（壁打ち2〜3週間）

最初の2〜3週間は、ほぼ壁打ちに費やした。

目的（Linux/UNIX/LPIC-1）
技術スタック
設計思想（境界、責務、依存方向）
“認識のズレ”を減らすための言語化

この期間は「実装が進んでない」ように見えるけど、後から効いてくる。
やりたいことが曖昧なまま走ると、後半で確実に詰むから。

第三章：実装開始 → 構造が育つ → そして複雑さが爆発する

いい感じに全体像ができてきたところで、Clean Architectureも盛り込んだ。
すると、構造は強くなる代わりにディレクトリが増え、把握コストが跳ね上がった。

さらに悪手が重なる。

OCP（拡張しやすく変更しにくい方針） が甘い状態でE2E(画面の自動テスト)を追加した
明確な画面UIを固めないまま実装を進めた
変更の波及が増え、直して壊してを繰り返す

結果、「前に進んでるのに、進捗が積み上がらない」状態になった。

!NOTE ここで気づいた。「正しさ」より先に「進め方」を整えないと死ぬ。

第四章：電車内デプロイ事件（Vercelで全滅）

そろそろ期日、実際に今のゲーム画面が見たいという話になった。
帰りの電車内でVercelにデプロイしようとしたら、過去の不具合が再燃。直したらフロントがエラーで落ちた。

せっかく出来ていた画面が全て止まり、ローカル環境も完全に壊れる。
修正は間に合わず、見せられる画面がないことを告げて、とても気まずい時間だけが流れた。

!NOTE 「移動中デプロイ」のように焦れは、だいたい事故る。分かってたのにやった。オワタ。

第五章：速度を取り戻したいのに、生成AIが遅くなる

そこからは、E2Eを一旦無視してUIをどんどん作った。
しかし今度は、過去の差分や型定義があやふやな箇所が積み重なっていて、生成AIの出力が遅い。

精度最大(GPT5.2 Thinking)で平均20分かかることもあった。
チャットを分けても、シンプルにしても、エラーは増え、出力は遅く、げんなりする。

ここでようやく分かった。
AIが遅いのは、AIが悪いというより「文脈が重すぎる」サイン だ。
構造が複雑すぎて、人間もAIも迷子になっている。

!NOTE 速く作るために複雑にしたのに、複雑だから遅くなる。皮肉が鋭い。

第六章：転機は「issue単位でチャットを減らす」だった

ふと発想を変えた。
「作る」より先に、「進め方」を整える。

チャットを issue単位 に切る（目的を1つに閉じる）
改修箇所が迷子にならないよう、影響範囲を明確にする
不具合の発生個所を局所化し、巻き戻しコストを減らす

これでようやく、1つ1つの責務を解決することで前に進めるようになった。

!NOTE “全部を一気に理解して解く”を諦めた瞬間、前に進み始めた。

学び：この経験を「みんなの学び」に変えるなら

ここからは、読者が真似できる形に落とす。

1) 複雑さが爆発しているサイン

変更のたびに関係ない場所が壊れる
UIが固まってないのに実装だけが進む
ディレクトリが増えても責務が見えない
生成AIの出力が遅くなる（文脈が肥大化している）

!NOTE 「遅くなった」時点で、設計か運用を見直す合図だった。

2) issue単位運用が効いた理由

変更理由が1つになる → 判断がブレにくい
影響範囲が狭い → デバッグが速い
完了条件が明確 → “終わった感”が積み上がる
チャット（AI文脈）も小さくなる → 出力が安定する

3) E2Eは強いけど、入れる順番がある

E2Eは「守り」になるけど、設計が固まっていない段階で厚く入れると、変更の自由度が落ちる。
まずはスモーク（最小のE2E）で“生存確認”だけして、UIと境界が落ち着いてから増やす方が、個人開発では安全。

!NOTE 最初から重装備にすると、動けなくなる。ゲームでも現実でも同じ。

4) 次に入れたい：観測可能性（ログ）

ログはまだ未実施。だからこそ、次の改善として価値がある。

どこで失敗したかを即座に分かるようにする
巻き戻しと調査時間を減らす
“再現できる不具合”に変換する

!NOTE バグは怖くない。怖いのは「再現できないこと」と「原因が追えないこと」。

おわりに：czzは、Linuxの入口を作る試み

czzの狙いは、Linux/UNIXを“正しく怖がらず”触れる場所を作ること。
そして学びを「楽しい」に寄せること。

派手な成功談というより、複雑さに殴られながらも進め方を修正して前に進んだ記録。
同じように一人で作ってる人、AIを使ってる人に、どこか一行でも刺さったら嬉しい。

!NOTE 次は、祈らなくて済む開発にする。ログと運用の攻略本を育てる。