連載公開分（クリックで開く）

# 【プロローグ】素人エンジニアが自分でアプリ開発できると甘く見てた全16弾無邪気な実装 vs 架空エンジニア2人の容赦なきツッコミ ※便利かなと思ってどんどん追加しちゃうんだよね
#1「在庫が見たいだけ」だったのに、引き算ひとつから在庫引当と多目的最適化まで始まった ※ 総在庫・予約在庫・有効在庫を分けた瞬間、ただの在庫表示が別物になった
#2「予約機能もこのアプリ1個にまとめれば便利じゃん」で、“時間”が一気に牙をむいた ※時間重複・境界条件・時間粒度・スマホ操作まで、空いてる時間を選ぶだけでは終わらなかった
#3 「機能増えたら毎回探すの面倒じゃん」で、お気に入りから共通UI設計まで広がった ※機能を増やした結果、「何を作るか」より「どう辿り着くか」が問題になった
#4「普通の組織図でいいじゃん」で一人を複数部署に入れたら、“多対多”が始まった ※兼務・複数所属・部署別役職・過去履歴が一気に絡み始めた
#5「どこの現場で使うかも持てばいいじゃん」で、物件マスタが在庫・予約・人を全部つないだ ※機能ごとにバラバラだった情報が、共通マスタを境に一つのシステムへ変わり始めた
#6「会社ごとにちょっと変えたい」で、設定駆動とバリデーションが殴り合いを始めた ※柔軟にしたら、「自由に設定させすぎない仕組み」の方が難しくなった
#7「ログインできたからって何でも触れたらまずいじゃん」で、認証より面倒な認可の沼に入った ※管理者か一般かでは足りず、「誰が・誰に・何をできるか」まで判定することになった
#8「二人とも空いてる画面を見てたら、どっちが勝つの？」でRace Conditionが牙をむいた ※在庫も予約も、画面に表示された「空き」を信用しただけでは守れなかった
#9「自分の在庫も持てた方が楽じゃん」で、“場所・所有・利用範囲”が全部別問題だった ※マイ在庫・現場在庫・共有在庫を分けたら、在庫数よりスコープ管理が難しくなった
#10「申請もこの中でできた方が楽じゃん」で、CRUDの裏に状態遷移が増殖した ※申請・承認・差し戻しを入れた瞬間、「保存できる」だけでは何も足りなくなった
#11「資格もQRで見られたら早いじゃん」で、“全部見せる”より“必要な答えだけ返す”方が難しかった ※資格・個人QR・権限をつないだら、識別より情報開示の方が本題になった
#12「一輪車を“ネコ”で探せないの不便じゃん」で、Canonical IDと人間の曖昧さを両立させることになった ※人間には優しく、内部は厳密に−−別名検索から正式IDへ収束させるまで
#13「機能増えすぎて説明する方が面倒」で、“どれが今の正解？”問題がコードの外まで広がった ※ヘルプ・仕様・会話・引き継ぎがズレ始め、Single Source of Truthが必要になった
#14「Codexなら全部見てくれるじゃん」で、AIの作業速度が人間のレビュー限界を超えた ※ AIがリポジトリ全体を調べられるほど変更範囲が怖くなる――Gitで差分・ステージ・既存変更・コミット境界を守る開発へ
#15「テストこんなに通るじゃん」で安心しかけたら、“全部緑なのに間違ってる”が普通に出てきた ※ テストがPASSでも正しいとは限らない――機能間の不具合・境界値・回帰・期待結果そのものまで疑う横断テストへ
#最終回【AIの尻拭い】JSONのまま押し通したら、AIたちが「最小トランザクションジャーナル」まで考え始めた ※「こうしたい」の一言から、AIとCodexが複数JSON更新の整合性リスクを発見し、Crash Recovery・回帰テスト・Git安全境界まで組み上げる開発へ
#エピローグ「作れた」で終わりじゃなかった。むしろ、そこからが本番だった ※ 単体テストはPASS、次は“全部つないで壊れないか”第2回横断テストへ

機能が増えてくると、作ることとは別の問題が出てきました。

私「これ、使う人に説明するの面倒じゃない？」

A「今さら気づいた？（笑）」

私「在庫だけならまだいいよ。」

在庫管理、予約、キャンセル待ち、組織、物件、設定、権限、文言変更モード、マイ在庫、申請、資格、QR、エイリアなど。

私「これ全部、使い方聞かれたら？」

A「お前が答える。」

私「漏れが出る（笑）」

そこで最初に、各ページへ、ヘルプボタンを付けることを考えました。

私「その画面で分からなくなったら、その場で見られた方がいいじゃん。」

A「取扱説明書を最初から探すんじゃなくて？」

私「そう。」

例えば、予約画面なら、このページでできること。在庫画面なら、数量の見方。設定画面なら、何を変更すると、どこへ反映されるのか。

私「画面ごとに専用の説明を出す。」

B「Contextual Help、コンテキストヘルプですね。利用者が今いる場所に応じた説明を出す考え方です。」

ただ、ヘルプボタンを置いたら、スマホで別の問題も出ました。

私「ここにあると邪魔な場合あるじゃん。」

A「ヘルプするためのボタンが操作の邪魔をする（笑）」

私「だから動かせればいい。」

A「また簡単に（笑）」

私「長押しして、邪魔じゃないところへ。」

A「やったの？」

私「やった。」

そして、ヘルプが増えると、当然、検索したくなります。

私「何十ページもあるなら、ヘルプから探すのも面倒じゃん。」

A「検索。」

私「キーワードで。」

A「ページ内だけ？」

私「アプリ全体も。」

A「結局、取扱説明書みたいになってきた（笑）」

私「そうなんだよ。」

ここで、以前作った機能ともつながってきました、文言変更モードです。第6弾では、会社によって呼び方が違うものを、コードそのものを書き換えずに変更できるようにしました。

例えば、「物件」を「現場」にする。「案件番号」を「工事番号」にする。そんな、会社ごとの表示文言の違いです。

私「これも結局、変更できる文言が増えてきたじゃん。」

A「第6弾で『毎回コード直すの面倒』って作ったやつね。」

私「そう。」

A「まさか、また一個ずつ管理してないよね？」

私「だから辞書化して、AIにも既存画面を調べてもらった。」

どの文言があるのか。どこで使われているのか。どこまで変更対象にしていいのか。既存画面を調べて、辞書化の作業もAIに手伝わせる。

ただし、何を変更可能にするかまで、全部AIへ丸投げするわけではありません。

私「意味変わったら危ないところまで、勝手に対象にされたら困るでしょ。」

A「AIは調査と作業。」

私「どこまで許すかは人間。」

B「機械的な抽出と、人間によるポリシー判断を分離したわけですね。」

そして、同じようなことが、ヘルプでも起きました。ページが増える、説明が増える、同じ機能について、別の場所でも説明する。

私「これ、同じ説明を何か所にも直接書くの嫌だな。」

A「また始まった（笑）」

私「だって、一個変えたら全部直すんでしょ？」

A「まあ。」

私「絶対どっか忘れるじゃん。」

そこで、ヘルプの内容も、バラバラに各ページへ直接書くのではなく、まとめて管理する方向へ進みました。一つの説明を、ページのヘルプで使う、検索でも使う、取扱説明書でも使う。

私「同じ説明なら、同じ元から出せばいいじゃん。」

B「コンテンツの一元管理と再利用ですね。」

ここまでは、まだ、利用者へどう説明するかの問題でした。でも、もっと面倒なことに気づきます。

私「ヘルプ直した。」

A「うん。」

私「仕様書は？」

A「……。」

私「取扱説明書は？」

A「……。」

私「前に残した説明は？」

A「……。」

私「全部同じ内容なのに、一個ずつ直すの？ってなる。」

A「そうだな（笑）」

例えば、予約の仕様を変える。実装は新しくなった。でも、ヘルプは昔のまま。仕様書には、さらに前の内容が残っている。引き継ぎメモには、別の説明が書いてある。会話の中には、途中で検討してやめた案まで残っている。

私「どれが今の正解なの？ってなるじゃん。」

A「なる。」

B「Document Drift、ドキュメントドリフトですね。実装と複数の説明資料が、時間とともにズレていく問題です。」

A「じゃあ全部毎回直す？」

私「それやってたら、いつか絶対漏れる。」

A「どうする？」

私「元になる情報、一個にできない？」

A「……。」

私「何？」

A「また共通化する気だろ（笑）」

私「同じ説明何回も直すの嫌じゃん。」

B「考え方としては、文書やヘルプにもSingle Source of Truth、SSOTを持たせる形ですね。」

A「データだけじゃなく、説明まで正本化していくのか。」

そこで、ヘルプだけではなく、仕様そのものを確認する場所も欲しくなりました。そして、仕様書ハブまで作るようになりました。

A「ヘルプだけじゃ足りなかった？」

私「ヘルプは使う人向けでしょ。」

A「仕様は？」

私「今このアプリが、どういう状態なのか確認する場所が欲しい。」

ここで、かなり重要になったのが、全部を同じ扱いにしないこと。実装済み検討中、将来構想、旧仕様。

私「これ混ざると本当に危ない。」

A「実装済みの席に、検討中と将来構想が勝手に座ってる（笑）」

私「逆に昔の仕様を、今も正しいと思ったり。」

A「旧仕様さん！あなたはもう退職してるから！出社しないで（笑）」

B「仕様のライフサイクル・ステータス管理ですね。」

ただし、ここも、「全部完全自動で同期できています」という話ではありません。

A「仕様変えたら、コードもヘルプも取説も全部自動で直る？」

私「そこまで完成してない。」

A「ちゃんと止めた（笑）」

私「自動化したい部分と、人が確認しないと危ない部分があるから。」

ただ、最近は少し変わってきました。

私「実装が終わるとさ。」

A「うん。」

私「俺が何も言ってないのに、AIの方から『この変更、正本にも反映しましょう』って言ってくるようになった。」

A「……勝手に？」

私「勝手にというか（笑）。実装した内容を見て、正本も変えた方がいいところがあると、向こうから言ってくる。」

A「お前が忘れる前に？」

私「たぶん（笑）」

B「実装後の変更内容と正本の整合を確認し、必要なら更新を提案する流れですね。」

A「正本作ったら、今度はAIが正本の面倒まで見始めた（笑）」

私「最近そんな感じ。」

A「で、そのままAIが勝手に正本を書き換えるの？」

私「いや、そこは違う。」

A「違う？」

私「『ここ変わったから、正本も更新した方がいい』って提案してくる。内容を確認して、それでいいなら進める。」

B「つまり、完全な自動同期ではなく、
変更を認識する
↓
正本更新を提案する
↓
人間が確認する
↓
正本へ反映するという形ですね。」

私「そう。」

A「お前、正本作ったのに、その正本の更新までAIに見張られてんの？（笑）」

私「優秀な刑事みたいだよ。俺が忘れた証拠まで拾ってくれる。」

A「容疑者もお前なんだけどな（笑）」

でも、これは自分の中では結構大きな変化でした。以前なら、実装する、動いた。終わり。そのあとで、「あ、ヘルプ直してない。」「仕様書が古い。」「引き継ぎメモと違う。」となる。

最近は、実装が終わった段階で、「この変更を正本側にも反映する必要がある」という話まで、AI側から出てくるようになりました。

私「最初は、俺が全部覚えてないとダメだったんだよ。」

A「無理だろ（笑）」

私「無理だった（笑）」

B「機能数と関連資料が増えれば、人間の記憶だけで整合を維持するのは難しくなります。」

私「だから、正本を決める。」

A「で、AIもそこを見る。」

私「そう。」

A「でも最後に正しいか決めるのは？」

私「俺。」

A「そこは残ってるんだ。」

私「そこまでAIに勝手に決められたら、それはそれで怖いだろ（笑）」

ここで一回整理すると、

私「その画面で分からなくなったら、その場で説明を見る。」
B「Contextual Help。」
私「同じ説明を何か所にも直接持たない。」
B「コンテンツ一元管理。」
私「実装と説明がズレる。」
B「Document Drift。」
私「今の正解を確認する場所を決める。」
B「Single Source of Truth。」
私「実装済み、検討中、将来構想、旧仕様を混ぜない。」
B「仕様のライフサイクル管理。」
私「実装が変わったら、最近はAI側から正本更新まで提案してくる。」
B「実装変更と正本の整合確認。」

A「最初は『説明するの面倒』だったんだよね？」

私「そう。」

A「説明が面倒だから、説明を管理するシステムまで作って、その管理までAIに手伝わせ始めた（笑）」

私「機能増やした結果、そうなった（笑）」

そして、ここまで機能がつながってくると、もう一つ、やり方そのものに限界が来ました。

私「一個変えるたびに、影響するところ増えてきたじゃん。」

A「在庫変えたら予約。」

私「権限。」

A「ヘルプ。」

私「仕様。」

A「テスト。」

私「全部見る。」

A「人間だけで？」

私「……きつい。」

そこで、コードベース全体を、まとめて調べてもらうことが増えていきました。

私「だったらCodexに、関連してるところ全部調べてもらえばいいじゃん。」

A「便利そうだね。」

B「便利です。」

A「……B、その言い方は何かあるな（笑）」

B「全部見られることと、全部変更させてよいことは別です。」

私「そこなんだよ。」

次回

「Codexなら全部見てくれるじゃん」で、AIの作業速度が人間のレビュー限界を超えた

AIがリポジトリ全体を調べられるほど変更範囲が怖くなる――Gitで差分・ステージ・既存変更・コミット境界を守る開発へ

連載公開分（クリックで開く）