/note/tech

AIに大きな仕様書を渡して一気に作らせるのは、宝くじを買うようなものです

要約:

■ 1. 大きすぎてレビューできない問題

  • 寄せられる相談:
    • AIに書かせる量が増え、大規模なコードができてしまいレビューできないという相談が続いている
  • 答え: その状態に入らないようにする
  • できたものをレビューで処理する難しさ:
    • 分割する、範囲を区切る、捨てるといった手は「読み切る」ことの代わりにならない
    • 「AIにレビューさせればいい」も、たぶん解決にならない
  • 原因は人数ではない:
    • チーム開発だけでなく、1人で作っていても同じように起きる
    • 原因は、先に大きな仕様書を書いて一気に作らせること
    • それは当たり外れが最後まで分からない宝くじを1枚だけ買うようなもの

■ 2. 仕様書が書けない対象

  • 先に仕様を全部決める流れ:
    • 仕様書を書いてAIに渡すと大量のコードが出てくる
    • 正しいか判断するには全部読まなければならなくなる
  • MulmoTerminal の例:
    • 起点はブラウザでターミナルが動くかの実験で、動いたのでマス目に広げ、触りながら機能を足した
    • 仕様書を書く余地はなかった
  • 未知の2要素:
    • できるかどうか分からない(ブラウザ内に本物のターミナルを9枚並べて実用に耐えるか)
    • 欲しい機能かどうか分からない(並べて嬉しいのか自分でも分からない)
    • この2つが未知のまま書けるのは、仕様書ではなく願望
  • 仕様書が有効な場面:
    • Amazon のクローンや、UIにこだわらない業務システムを作る場合
    • 対象がすでに世の中に存在するから書ける
  • 仕様書の本質:
    • 仕様書は「すでにある知識の圧縮」であって「まだ無いものの発見」ではない
    • 圧縮する対象がないものは圧縮できない

■ 3. 大きな仕様書は宝くじ

  • 1枚の宝くじ:
    • 何も分からない時点で全部決めるのは、当たり外れを1枚の宝くじに賭けるようなもの
  • 宝くじより悪い点:
    • 宝くじはその場で当たり外れが分かる
    • 大きな仕様書は作り終わって触るまで分からない
  • 全部うまくいく確率:
    • 1項目9割で思いどおりになり、項目は互いに独立と仮定した単純計算(桁の感覚用)
    • 3項目で73%、5項目で59%、10項目で35%
    • 20項目で12%、50項目で0.5%
    • 掛け算なので思っているより遥かに速く落ちる
    • 1項目95%の理想的な想定でも20項目で36%
    • 大きな仕様書には決めごとが20〜50個は簡単に入る
  • 外れた項目の行方:
    • 20項目なら少なくとも1つが思いどおりにならない確率はおよそ88%
    • たいていは「まあ動いているし、いいか」で受け入れられている
    • 確認には全部読むしかないのに、読めない量が出てきているため確認していない
    • それで満足できているのかという問題

■ 4. 細かく書いた先は実装

  • 仕様を細かく詰める案:
    • 1項目あたりの確率を上げるには曖昧さを潰すしかない
    • 詰めきるとは、実装時に迷う判断を先に全部列挙すること
  • 詰める内容の例:
    • ボタンの位置、押したときの挙動
    • 失敗時の表示、値が空のときの扱い
    • そこまで書くと書く量も考える量も実装に近づく
  • 決定的な違い:
    • 仕様書は動かず、どれだけ細かく書いても正しいかどうかを教えてくれない
    • 仕様を細かくする作業は、答え合わせを先送りにしたまま賭け金だけを増やす作業になりがち

■ 5. AIによる天秤の逆転

  • かつての合理性:
    • 書き直しが高かったため、大きく作ってから直すと大損した
    • 紙の上で間違えておくのが安かった
  • いまの状況:
    • 書き直しが安く、作ってから間違えるほうが安い
    • 先に詰めることを合理的にしていた前提が崩れた
  • 安くなっていないもの:
    • 安くなったのは、すでに形が見えているものを書き起こす手間
    • 移行を伴うもの、外部公開API、他社と繋がる部分はいまも作り直しが高い
    • そこは先に詰めたほうがいい
  • 詰める段階に来たら作る:
    • AIに小刻みに指示を出せば、仕様を詰めるのと同じくらいの時間で動くものが出てくる
    • 仕様書は間違っていても黙っているが、動くものは間違いをその場で教えてくれる
    • 同じ時間なら教えてくれるほうに使ったほうがいい

■ 6. 実装を小さく詰める

  • 一気に作って外れた場合:
    • それまでのコードは全部その仕様の上に乗っており、一部修正ではなく積み直しになる
    • 積み直したほうが速いと気づくのは、たいてい積み上げ切ったあと
  • やること:
    • 外れても捨てられる大きさにしておく
    • 判断が必要な最小単位まで切り、1つずつ実装し、そのつど判断する
    • 詰めるのは仕様ではなく実装
  • 確率上の効果:
    • 一度に決めるのを5つにすれば59%、3つなら73%
  • 確率以外の3つの変化:
    • 判断の精度が上がる(まとめて見ると細部が落ち「まあいいか」で通してしまう)
    • 途中で方向を変えられる(3つ目で方向違いに気づけば曲がれる)
    • 早い段階で人に触ってもらえる(これが一番大きい)
  • 人に触ってもらう価値:
    • 作った目的そのものの外れに気づけたのは、動くものを人に触ってもらえたから
    • 完成まで誰にも見せていなければ、間違った目的のまま完成していた

■ 7. 並列化と小さく切る限界

  • 1つずつだと遅い問題:
    • 直列では当然遅く、大きくまとめたくなる
    • 依存関係のないものを10個くらい同時に走らせ、出来たものから評価しフィードバックする
    • 小さく刻むやり方は並列に走らせられて初めて実用になる
  • 仕様先行が合理的に見える理由:
    • 並列で走らせられない環境では大きく賭けるしかなくなる
  • 評価がボトルネック:
    • 並列に走らせると出来上がったものを次々に評価することになる
    • 評価が詰まると全部止まり、評価者が1人ならその人の空き手が上限
    • これが人数と並列数の話につながる
  • 小さく切れば安全ではない:
    • 切り方を間違えると、つなぎ目に新しい間違いが入る
    • それでも外れたと分かるのが早く、そこまでで捨てられる点が決定的に違う

■ 8. 昔からあった仕様の誤り

  • 人間だけの時代の仕様書:
    • 実装者から「このままでは成立しない」と何度も戻ってきた
    • 動くものを触って初めて「これじゃない」と気づいた
    • この往復は実装が遅いからではなく、仕様が間違っていて触るまで誰も分からなかったから起きた
  • AIが速くしたもの:
    • 速くなったのは主に実装とその段取り
    • 間違っていた仕様はほとんど変わっていない
    • むしろ間違った仕様がより速く、より大量に実体化するようになった

■ 9. 決める人とコードの距離

  • アジャイルへの反論:
    • 短い周期で作って確かめて直せば距離は縮まる
    • だがプロダクトの持ち主とチームが分かれていると、そこで止まる
    • 決める人が会議にいてキーボードにいないから
    • 意思決定が遅れ、最悪の場合、コードを書いて初めて分かる判断が誰にも届かない
  • 本当の変数:
    • ウォーターフォールかアジャイルかではなく、決める人とコードの距離
  • 3つの形態:
    • 仕様を先に全部書く: 決める人がコードから最も遠く、一度だけ最も遠くで決める
    • アジャイル(分離型): 決める人は会議にいて、スプリントの粒度でしか決められない
    • 並走: 決める人がキーボードにいる
  • アジャイルの限界:
    • 距離を縮めたがゼロにはしていない
    • 距離がゼロでないと届かない種類の決定がある

■ 10. 賢くなったのはツール

  • AIが仕様書を手伝う時代への勘違い:
    • 要件を投げればそれっぽい仕様書が出てきて、自分の能力が上がったように感じる
    • 上がっておらず、賢くなったのはツールで、ボトルネックは依然として自分
  • レバレッジは倍率:
    • AIは強力なレバレッジで、ビジョンがあり作りたいものが明確な人は驚くほど使いこなせる
    • レバレッジは掛け算で、掛けられる側の値は変わっていない
    • 出てきた仕様書の筋の良し悪しを判断するのも、良い仕様を書ける能力も自分次第
  • 文章との類比:
    • それっぽい文章はAIで簡単に書けるが、素晴らしい文章をAIで書くのはいまも非常に難しい
    • 仕様も設計もまったく同じ
  • 判断基準は自分の中:
    • AIは案を並べ、抜けに気づかせ、判断材料を増やしてくれる
    • どの案を採るかの基準は自分の中にしかない
    • 基準がないまま材料だけ増えると、選べる気がするだけで選べない
    • 掛ける元がなければ倍率は意味を持たない

■ 11. 元CTOがいちエンジニアへ

  • 報道されている事実:
    • Peter Bailis は Workday の CTO(2025年5月就任)を2026年3月に退社
    • その後 Anthropic に Member of Technical Staff として参加し、強化学習まわりの実装を担当
    • You.com 共同創業者兼 CTO の Bryan McCann も Anthropic に MTS として移った
    • The Next Web は、幹部が大組織を率いる権限より最先端研究への近さを選んでいると報じた
    • 本人たちの理由は記事に書かれていない
  • 推測としての解釈:
    • 肩書きや処遇を上げたいだけなら他社CTOの選択肢もあり、選ばなかったことが優先順位を示す
    • かつて構想を形にするには賢い部下と組織が必要だったが、その部分をいまはAIが埋める
    • 一番賢いAIを制限なく使える場所に一エンジニアとして座る選択は十分ありえる
  • 少人数化との関係:
    • ビジョンを持つ人ほど少ない人数で動けるようになったという話でもある
    • ただし動けるようになったのはレバレッジのおかげ

■ 12. 作ってみないと出てこない決定

  • 例1、目的そのものの誤り:
    • MulmoTerminal はAIエージェントを画面のマス目で何体も並べて動かすツール
    • 作るときの想定は、並列できる数の天井を上げる道具というもの
    • 利用者4人に聞くと、実際の並列数は1〜6個で、もっと多く回せるようになった人は0人
    • 全員が、同じ数を楽に扱えるようになったと答えた
    • 1〜3個しか回さないのに VS Code を完全にやめた人もいた
    • 道具の価値は「天井を上げること」ではなく「見失わなくなること」で、作った本人が間違えていた
  • 通知が作った新しい天井:
    • 最大8まで行ったが通知の嵐で疲れて止めた、という答えがあった
    • 通知は席を立っても呼び戻されるよう、並列数を増やすために付けた機能
    • 道具が上げた天井を、道具の別の部分が下げていた
    • 原因は「終わった」と「返事を待っている」が同じ音で鳴り、区別できないこと
    • 実際に8個並べて疲れた人が出るまで、作る前には絶対に分からない
  • 例2、AIの「やらないほうがいい」の誤り:
    • 重複検出ツールが「読み込む→無ければエラー→失敗を捕まえて記録」の形の重複を大量に指摘した
    • AIは、構造上の反復で各処理が自己完結しているから読みやすいとして、まとめないよう判断した
    • まとめると2700行の巨大ファイルを広範囲に書き換え、読みやすさが下がるという理由だった
    • 「誤った抽象は重複より悪い」は自分たちの方針でもあり、そのときは納得した
    • 後で自分でコードを開くと、偶然の類似ではなく本当に同じことを繰り返し書いていた
    • まとめるとかなりすっきりし、別の課題として潰した
  • 例2の教訓:
    • ツールの重複指摘は正しく、AIの反対はもっともらしいが間違っていた
    • AIは一般論として正しい原則を引いて「やらない」ことを正当化でき、読むと納得してしまう
    • 納得できるかと、このコードで合っているかは別問題で、後者はファイルを開くまで分からない
    • チケットにして誰かに渡していたら、よく書けたAIの説明が採用されて終わっていた
    • 開いて確かめた人だけが覆せる
  • 2例の共通点:
    • 実際に動かして確かめるまで正解が分からなかった
    • どちらも仕様書にもチケットにも書けず、書ける形になった時点で確かめ終わっている
    • 作る前に決められるのは、すでに知っていることだけ

■ 13. AIは距離を縮めない

  • 高速化の恩恵の範囲:
    • AIの高速化の恩恵を受けるのはキーボードにいる人
    • 決定権がキーボードから遠ければ、高速化はそのままでは届かない
  • 2つの状態:
    • 決定権がキーボードにある: 速く、直しながら作れる
    • 決定権が遠いまま: 遠いまま速く作れる
  • 最もまずい状態:
    • 遠いまま速く作れる状態が一番まずい
    • 間違いに気づく速度は変わらないのに、間違ったものが積み上がる速度だけが上がる
    • その結果が「大きすぎてレビューできない」

■ 14. AIレビューで解決しない理由

  • AIの読む能力:
    • AIは人間より遥かに速く大量のテキストを読め、読めないわけではない
  • 1つめ、扱える量の上限:
    • モデルが同時に見られる文章量(コンテキスト)には上限がある
    • 大きな差分はモデルやツール構成によっては一度に扱いきれない
    • 分割すると「AとBの噛み合わせがおかしい」という指摘が出しにくくなる
    • バグはたいていその境目にある
  • 2つめ、通過と良い設計は別:
    • ある時期に「長すぎる関数」を全部潰し、機械が怒らない状態にした
    • 3ヶ月後、CollectionView.vue は2,945行、関数187個、最長61行
    • server/index.ts は3,020行、関数212個、最長82行(ほとんどは10行未満)
    • 長い関数はないのに、ファイルは3,000行ある
  • 機械が見ていないもの:
    • 機械は1関数の行数だけを見て、1ファイルに何種類の仕事があるかは見ていない
    • CollectionView.vue には一覧表示・絞り込み・編集・チャットなど11種類の仕事が同居していた
    • 小さな関数187個で3,000行になっても、機械は一度も警告しなかった
  • 結論:
    • 「機械が通したから大丈夫」はレビューでも設計でも成立しない
    • AIレビューを最後の砦に置いた設計はここで崩れる

■ 15. 実際の作り方と数字

  • 位置づけ:
    • 正しさの証明ではなく、そういう作り方をしているという観測データ
  • MulmoTerminal の実績(2026-06-14〜2026-08-06、53日):
    • コミット3,235、マージPR1,170
    • リリース64回で1日あたり1.2回
    • 書いた人は実質2人(2,990 / 221、ほか1人24)
  • 閉じた課題400件の寿命:
    • 中央値1.6時間
    • 6時間以内77%、24時間以内92%、1週間以上2%
  • マージしたPRの差分400本:
    • 中央値286行、300行未満51%
    • 変更ファイル数の中央値7個
  • 測り方:
    • 課題は gh issue list --state closed --limit 400 で直近400件の作成と閉鎖の時刻差
    • PRも直近400本の追加行と削除行の合計
    • 直近400件の区切りのため、期間途中でやり方が変われば影響を受ける
    • コミット数とリリース数は git rev-list --count と git tag
  • 数字の意味:
    • 課題は事前の仕様書ではなく、触って気づいたことをその場で書き、その日のうちに直した記録
    • 先に全部決めてから作っていたら、この分布にはならない
    • 示せるのは速く作れたことまでで、良いものが作れたことは別の話
    • 巨大な差分にならない状態を先に作り、レビューできないコードの状態に入らない

■ 16. 計画はAIが書く

  • plans/ の計画351本:
    • 新機能166、不具合修正132、整理37、その他16
    • 278本(79%)が課題番号つき
    • 仕様書ではなく、1つの課題をどう片付けるかの段取り
    • 書くのはAIで、自分は読んで良し悪しを判断するだけ
  • 作業の順番:
    • 触っていておかしいと気づく
    • 課題を立てる(自分が何をやるか決める)
    • AIが段取りを書く(自動)
    • 読んで違えば直させる(自分)
    • 実装させる(自動)
  • 書ける条件:
    • AIに段取りを書かせられるのは、何をやるか決めたあとだけ
    • 書けるのは対象の形がすでに分かったあとだけ
    • 先に書くことを否定しているのではなく、書ける条件を守っている

■ 17. 人数と経路の数

  • 経路の増え方:
    • 判断とすり合わせは、人数が増えると経路の数 n(n-1)/2 で増える
    • 2人で1本、3人で3本、4人で6本、5人で10本、8人で28本、10人で45本
    • 2人を4人にすると人手は2倍だが経路は6倍、8人なら人手4倍に経路28倍
  • モデルの限界:
    • 実際には全員が全員と話すことはまずない単純化したモデル
    • ただし人を足すと増えるのは手だけではないことを示せる
    • ブルックス『人月の神話』の「遅れているプロジェクトに人を足すとさらに遅れる」も根はここ
  • AIが変えたもの:
    • かつては実装力が人数に比例して増え、経路コストを払っても手前までは得が大きかった
    • いまは実装力をAIが出し、人数にあまり比例しない
    • 経路コストは n(n-1)/2 のまま変わっていない
    • 実装量不足で人を足す理由は薄れ、人を足す代償はそのまま残った
  • 元CTOの話との接続:
    • 大組織を率いれば実装力は人数ぶん得られるが、経路も n(n-1)/2 で背負う
    • 意思決定はその経路を全部通ってからでないと形にならない
    • AIから実装力を取れば、経路は自分ひとりぶんで済む
    • 手放したのは組織で、取りにいったのは判断とAIの距離(本人の発言ではなく推測)
  • 式の限界:
    • 経路数は生産性でも意思決定の速さでもなく、式から最適人数は出ない
    • 言えるのは天秤の片側が軽くなったことまでで、具体的な人数は経験からの話

■ 18. 個人の並列数の上限

  • 1つのプロジェクト内:
    • ざっと見て判断するだけなら10くらいまで
    • 仕様を考えながらなら5個が限界
  • プロジェクトをまたぐ場合:
    • 頭を使わない作業なら3〜4プロジェクト
    • 依存がある、仕様を考える、再現しながら追う作業は並列できない(1個)
  • 限界は人間の側:
    • ツールは9個並べられるが、並べられないのは自分のほう
  • 1個足すと全体が遅くなる:
    • 自分の手が塞がる割合が100%に近づくほど、エージェント側の待ち時間は急激に増えやすい
    • レジ1つのコンビニで店員がほぼ休みなく接客していると、少し混んだだけで行列が伸びるのと同じ
  • 並列数を上げる手:
    • エージェントを増やすのではなく、自分が考えないと進まない部分を減らす
    • 仕様を先に決める、再現手順を先に作る、依存を先に切る
    • その切り出し作業自体も自分でやるのでゼロにはならない

■ 19. チームも小さいほうがいい

  • 人数を決める変数:
    • 実装量ではなく判断の量
    • 判断とは、優先順位・設計・例外の扱いなど、他人に渡すと精度が落ちる決定
    • 実装量が人数に比例しなくなり、残った判断は分けると経路の式が効く
  • 経験則: 1プロダクトにつき1〜3人
    • まだ形が決まっておらず、持ち主が自分でコードを触れる場合に限る
    • 持ち主自身か、それを支えられる人が実装する
    • 普遍的な最適解ではなく条件つきの経験則
  • 成り立つ条件:
    • 何を作るかが決まりきっておらず、探索しながら形を決める段階
    • 持ち主が自分でコードを触れ、決める人がキーボードにいる
    • 1人が全体を頭に入れられる大きさで、入らなくなったらそこが分割線
    • リリースを自分たちの判断で出せ、承認の列に並ばなくていい
  • 人数を減らせない場合:
    • 条件のどれかが欠けているなら人数は減らせない
    • 専門知識が要るもの、24時間動かし続けるもの、作った人がレビューできない業界は別の問題
  • ピザ理論の変化:
    • Amazon の「2枚のピザで足りる人数」は、チームを小さく自律させる設計思想で会議もその一部
    • かつては人数は要るので、せめて会議とチームを小さく保つという考え
    • いまはそもそも人数が要らず、作る単位ごと小さくできる
    • 残った判断こそ、すり合わせのコストを一番食う

■ 20. 多いほうがいいもの

  • 小さくすべきは作る単位だけ:
    • アイデアの数、フィードバックをくれる人の数、使ってくれる人の数は多いほうがいい
    • 目的の外れは4人に聞くまで分からず、まわりに人がいなければ起きなかった
  • 作る単位とまわりの人:
    • 作る単位は判断が分割できないから小さいほうがいい
    • まわりの人は判断の材料が増えるから多いほうがいい
    • この「まわり」がコミュニティであり会社
  • 作る場所と意見の集まる場所を分ける:
    • 中は2人でも外は多いほうがいい
    • 作る単位を小さくするほど中の視点が偏るため、外から材料をもらう必要は増える
  • 減らすのはプロダクトあたりの人数:
    • 8人を2人にするのではなく、8人を1プロダクトに置くのをやめ、2人×4プロダクトにする
    • 3〜4プロジェクト同時は頭を使わない作業のときだけで、2人で6〜8プロダクトにはならない
    • 実際は、深く考えている1つと流している数個という配分になる

■ 21. まとめ: 持ち主が少人数で使いながら作る

  • 本質:
    • プロダクトの持ち主が少人数で、自分で細かく使いながら作るのがAI時代に向いたやり方
  • 自分が一番のヘビーユーザーである必要:
    • 目的の外れに気づけたのは自分も毎日使っていたから
    • 使っていなければ「同じ数を楽に扱えるようになった」の意味も重みも分からない
    • 判断の材料は使っているうちにしか溜まらない
    • 持ち主が使っていない道具は誰の判断でも直せない
  • プログラムが得意でなくてもよい:
    • 必要なのは作りたいものが明確なことと、出てきたものに「これは違う」と言えること
    • コードを速く書けることではない
    • その2つが揃えば、エンジニアでなくても良いプロダクトを作れる時代が見えてきている
    • 何が欲しいかが明確な人ほどレバレッジは大きく効く
  • 丸投げは効かない:
    • 仕様も実装もAIに任せて「なんかうまくいかない」のは当然
    • 細部まで自分で詰めないと本質的なプロダクトにならない
    • マイクロマネジメントは人間相手には悪い意味だが、AIに対しては正しいやり方
    • AIは文句を言わず何度でも直すので、納得いくまで詰めたほうがいい
  • 結論:
    • 細かく書けば当たると詰めていくと行き着く先は実装で、同じ手間なら動くほうを書いたほうがいい
    • ベースだけざっと作り、自分で細かく使いながら並走する
    • それは雑にやることではなく、判断の回数を増やすこと
    • 判断の回数を増やせるのは、キーボードの前で自分で使っている人だけ

■ 22. 1人10並列への条件

  • 並列運用で必ず起きる問題:
    • 小さく刻んで何度も引くと、どれが自分の返事を待っているか分からなくなる
    • 3〜4個並べると、待たせていると気づかないまま数十分経つ
    • 並列数を決めるのは自分の注意で、そこが詰まると全部止まる
  • MulmoTerminal の位置づけ:
    • マス目の色、音、スマホ通知でこの問題を解決するために作った
    • 1人がどこまで並列で回せるかに特化し、チーム分担の機能はない
    • ターミナルに慣れ、並列が苦にならない人に一番合う
  • 実際には10は回せる:
    • 利用者4人の実測は1〜6だが、自分は判断だけを流す状態なら10くらい回している
    • 話を聞いた米国スタートアップの人は12と言っていた
    • 仕様を考えながらだと5が限界で、混ざると少ないほうに引っ張られる
    • 自分が考えないと進まないものを減らせば数は伸びる
    • ターミナルに慣れ並列が苦にならない人なら、1人で10〜20までは行けるはず
  • 天井を上げるのは詰め方:
    • 必要なのはエージェントを増やすことではない
    • 判断の最小単位まで小さく切り、依存を先に切り、再現手順を先に作る
    • 自分が考えないと進まない部分を削れるだけ削る
    • 天井を上げるのは道具ではなく詰め方のほう
  • 道具だけでは10にならない:
    • 1体増えるごとに読みにいっていたら5で頭打ちになる
    • 数を伸ばすには1つあたりに払う注意そのものを減らすしかない
    • 型・重複・未使用・複雑度を人ではなくCIに見せるなど、読まなくても壊れない足回りが必要
    • 足回りを維持していれば、注意を判断にだけ使える
    • 小さく切って並列に走らせることと、読まなくても壊れないことは同じ1つのことの表裏