配布資料 31構築年表 第2章 — 大規模な要件追加・仕様変更の実像

実例5件について「人間と AI が実際にどう振る舞ったか」「あるべき姿」「ありがちなトラブル」を、 memory・rules・イシュートラッカー・git 履歴の実照会（2026-07-17）に基づいて記述する。

「返金の仕組みを作り直したい」

大きな変更のとき、AI に何と言うか。ここで結果がかなり変わります。

この章は、実際にあった大規模変更5件の記録です。 うまくいったところも、8回却下したところも、1ヶ月後に事故が見つかったところも、そのまま書きます。

扱う5件

---

1. 何が起きたのか

① 書き切ってから作った、極端な成功例

旧事業（予約システム）のプロトタイプを止め、2.4ヶ月かけてリポジトリ外で要件57本・設計・計画・市場調査（AI deep-research 2本）を執筆しました。 9分間の3コミットで一括インポートし、旧システムは削除ではなく退避しました。git mv で履歴を保持したまま隔離し、新実装が一巡した25日後に削除しています。

実装前にギャップ分析をやりました。 要件と画面・URL 設計の突合を記号で集計し（✅35 / 📋19 / ⏩1 / ❌0）、「❌ゼロ」を実装開始のゲートにしました。 パスワードリセット、特商法ページなど「要件には書いたが設計に無い」漏れを、実装前に9領域埋めています。

実装順序の原則も明文化しました。 「データを作る機能（管理画面）を先に、閲覧・消費する機能を後に」。 シードデータに頼らず、実操作でテストデータを作れるようにするためです。

影の側面も書いておきます。 6日で12 Phase という高速実装の負債（モック残置・ハードコード）は、2ヶ月後の全数監査で173件として精算されました。

速度は無料ではありません。 > 出典: git 1b0d9be9 / 2312e2ac / 303fda93、内部事例

② 8回否定して、禁止リストになるまで

確立過程（初回・2日間）。

AI が返金原資の設計案を出し、否定する往復が最低5回ありました。記録に残る否定された案は8パターンに及びます。

将来売上からの天引き（回収不能）。「手数料はほぼ±0」として計算から除外——これには「1件数十円でも年間数万件で数百万円。商売として『ほぼ±0』は絶対に許容できない」と返しています。銀行振込での補填（原資問題を構造的に解決しない）。

同じ案を2回提案した記録まで残っています。

決定打は「docs 以下の規約を確認しろ」という一次資料への差し戻しでした。 既存の要件定義に請求書方式が規定済みで、AI はそれを読まずに独自案を出し続けていました。

議論が決着した同日中に、「次セッションで結論を見失わないため」のガードレール整備をさせました。 絶対禁止事項リスト（禁止事項と理由のテーブル）を rules ファイルとして新設して全セッション自動ロード化。要件定義への反映。memory 記録。この3点を同日 PR にしています。

リストはその後も成長しました（8→10項目）。 そしてルール自体の誤り（手数料返還前提）も後日 Stripe 公式仕様の裏取りで訂正され、訂正の経緯ごと本文に残っています。

再設計（4日間・40 PR）。

起点は外部からの要請でした。決済事業者への資金フロー図を提出するため実装を精査したら、本番稼働中の返金実装に致命的欠陥2件が見つかりました。コンビニ返金が実行されない可能性と、銀行振込返金が購入者の現金にならない問題です。

「説明しようとしたら説明できなかった」ことが、監査の入口になりました。

進め方はこうなります。

• Phase 0 は実装ゼロの「仕様文書だけの PR」（3成分構成・返金モードA/B の正本更新）
• 実装は 1PR=1レイヤーで分割（スキーマ→購入者API→管理API→画面→メール→暗号化）
• 型・単体・ビルド全緑の先で、staging の実体 E2E（決済3種混在・画面操作の一気通貫）が重大バグ3件を掘り当てました。 設定が保存されない silent ignore、ルート順序の404、カラム長超過です

途中、何気なく「個別返金の手数料は誰が負担するのか」と聞いたことから、購入者が承認なしに即時返金できる業務違反の死にコード経路が見つかりました。 そこから経路撤廃（43ファイル・-985行）へ発展しています。

③ 稼働1ヶ月後に越境購入を自分で見つけた

設計 exploration 文書を1日で作り込みました。

背景→提供パターン比較→サービスイン手順→アーキテクチャ判断の経緯（3案比較と採用根拠）→番号付き確定事項20項目→層別の仕様変更→工数→リスク→残論点→着手前の技術調査 TODO→改訂履歴、という構成です。

承認は文書一括ではなく論点単位にしました。番号で1つずつ決定して「確定事項」表へ移動し、未決は「実装着手時に確定で可」と明示的に保留します。

着手前の技術調査（T1〜T8）が、設計を実際に動かしました。 外部サービスの制約調査で方式が変わり、メール65メソッドが全件テナント非対応だという実測で工数が+1週になりました。 調査が設計を訂正する構造を、最初から組み込んでいたということでもあります。

実装は Phase 5分割 + 各 Phase 内 1PR=1レイヤーです。migration はテーブル別に細分割して backfill し、最後に feature flag 有効化 PR を置きました。

そして境界事故が起きます。

稼働1ヶ月後、staging を自分で触っていて「別テナントの商品がなぜこのサイトで買えるのか」と越境購入を発見しました。

原因は2つです。 ①既定値が設計と逆でした（設計は共有 opt-in、実装は既定で共有 true） ②照合の仕組みは作られていたのに適用されていない経路が大量に残っていました

101エージェント・26グループの全バックエンド監査をかけ、検出74件を敵対的検証で27件反証して確定47件（critical 3）。22イシューで修正しました。

ここで生まれた規律があります。 guard の fallback により「本番は安全」な状態ではありました。それでも最も徹底的な選択肢——全面掃討を先に完了する——を選びました。

「shim で本番安全」は correctness を先送りする理由になりません。

④ バグ1件から173件が出てきた

発端はバグ1件でした。6週間潜伏した「再利用経路だけ挙動が違う」バグです。

そこで「同種が他にも潜在する」という仮説を立てて全数調査を発注しました。 ただし即着手させず、「残イシュー消化後」という着手条件付きで事前登録しています。割り込みではなくキューとして統制するためです。

18クラスタ並列監査（19エージェント）で検出173件。 三軸で分類しました。重大度（critical 6〜low 81）× 混入の型（経路乖離・ハードコード金額・死にコード）× 消化の器（即修正 S0 / 共通化 EPIC / 削除のみ PR）です。

優先順位の価値基準も明文化しました。金銭 > 権限・個人情報 > 在庫 > 負債。

特筆すべき発見が一つあります。

「ルール上存在することになっている検証コマンドが、実在しませんでした。」

CLAUDE.md が完了条件として参照する verify:<page> の実体が無いことを実測で発見し、大規模置換の前提条件としてその日のうちに回帰検知ハーネスを自作しました（computed-style スナップショット）。

以後「先に検知器 PR → 次に置換 PR」の順序が確立しています。

inline style 7,868箇所の消化は、「トークン定義のみ（見た目不変保証）→ ユーティリティ定義のみ → 画面置換（クラスタ単位）」と定義と適用を別 PR に分離しました。 後で1色だけ差し替えたくなったときの影響範囲を最小化する PR 設計です。

⑤ 計画書だけで別セッションが8時間完走した

別セッションが作業中だったため、計画セッションはソースを1文字も編集せず、「実装プロンプト兼計画書」（143行）だけを作りました。

確定パレット値。現状の実測（file:line アンカー付き。「この列は存在しない」という不在の証明まで）。PR 分割表（依存とデプロイ条件付き）。既知の罠。次セッション冒頭の着手手順5ステップです。

結果、別のセッションが計画書だけを頼りに8時間で11個の PR を完走しました。 再調査コストはゼロです。

「計画の質 = 他人（未来の AI）がそのまま実行できるか」の実証例になりました。

副作用の教訓も採れています。 完了後も memory に「計画済み・未着手」という古い記述が残っていました。記憶とイシュートラッカーの二重管理では、トラッカーが正です。 この残骸は、この教材の調査中に見つけて是正しました。

---

2. 人間は何をしていたか

実例5件から抽出した、大規模変更時の人間側の行動様式を8つ挙げます。 提供思想の「人間の5役割」の、実務形態にあたります。

1. 原則を与え、実装を与えません。 「テナント間では基本的に共有しない」「事業として赤字を絶対に許容しない」。実装指示ではなく判断基準を与えます。AI は基準から設計を導出し直せます
2. 反例で否定します。 抽象的な「ダメ」ではなく「販売者が退会したら回収できない」「年間数万件なら数百万円」と、1点ずつ業務事実の反例で潰します
3. 一次資料へ差し戻します。 AI の独自案ループは「既存文書を確認しろ」で切断します。多くの場合、答えはもう文書にあります
4. 最も徹底的な選択肢を選びます。 AI が並べる A（手早い）/ B（中間）/ C（徹底的）から、本旨に関わる領域では C を選びます。「本番は安全」を先送りの理由にさせません
5. 承認は暫定と考えます。 一度承認した案でも、文書や公式仕様との突合で覆します。承認より裏取りが優先されます
6. 着手条件と時期を統制します。 全数監査を「残イシュー消化後」と条件付きで事前登録します。計画だけ固めて実行を分離します。割り込みをキューに変えます
7. 自分で実地検分します。 越境購入もメールテンプレの全件無効も、staging を自分で触って見つけました。AI の報告だけで完了を信じません
8. 記録を残させます。 議論の決着と同日中に、結論を rules・要件定義・memory へ焼き込む PR を作らせます。「次のセッションの AI」は今日の議論を覚えていない前提で動きます

3. AI の良かった型と、実際に起きた悪癖9つ

良かった型。

着手前の実コード調査で設計と工数を補正します。番号付き確定事項と改訂履歴の管理。migration 細分割 + backfill + feature flag 最後の安全な段替え。多エージェント並列監査と敵対的検証（74件→47件に絞る精度管理）。回帰検知器の自作。file:line アンカー付き計画書で、次セッションへの引き継ぎコストをゼロにすること。

悪癖。 すべて実際に起きたものです。

9 は特に重要だと思っています。

人間の記憶も間違えます。

「live 値で裏取り」の規律は、AI の思い込み対策であると同時に、人間の思い込みから成果物を守る仕組みでもあります。

4. 大規模変更を安全に進める8段

1. モード分離。 調査・計画のセッションではソースに触れません（確認/実行の契約）。並行作業とのファイル競合は計画段階で確認します
2. 実測調査。 live 値・実コード・公式仕様で現状を確定します。file:line アンカーと「不在の証明」まで計画書に焼き込みます
3. 設計 exploration 文書。 背景→選択肢比較→判断経緯→番号付き確定事項→層別変更→工数→リスク→残論点→着手前 TODO→改訂履歴。着手前の技術調査で設計を訂正する余地を、最初から組み込みます
4. 論点単位の承認。 文書一括承認をしません。1論点ずつ決定し、未決は「いつ確定させるか」ごと明示して保留します
5. 分割。 Phase（価値単位）→ イシュー（機能単位）→ PR（1PR=1レイヤー）。migration は個別、feature flag は最後、定義と適用は別 PR です
6. 回帰検知器を先に作ります。 大規模置換や見た目不変改修の前に、機械が退行を検知できる状態を作ります。「ルール上あることになっている検知器」の実在も確認します
7. 実体 E2E で締めます。 緑のテストの先に、実データ・実画面の一気通貫検証を置きます。ここで出るバグが一番深いです
8. 事後処理。 設計文書は書き換えず「原文 + 実装差異の注記」で歴史化します。失敗はルールと hook に転写します。旧資産は退避→縮退定義→削除の3段階です

5. 対応する事例カード

• 事例 #11: 否定済み設計の再提案ループ（→ 禁止リスト + 毎セッション自動ロード）
• 事例 #12: 「小さな変更」が実測で別物になった（→ blast radius の実測義務）
• ほかに #06 検証スキップと早期 Done / #07 文書の古い金額 / #08 監査の盲点

手を動かすなら

• 設計 exploration。 Keihi に大型仕様変更「事後承認の2段階制 + 代理申請の追加」を想定して、exploration 文書（選択肢比較・番号付き確定事項・PR 分割表）を書いてみてください
• blast radius の実測。 その変更のスキーマ影響を AI に見積もらせ、そのあと tsc 試走で実測させて、乖離を体験してみてください
• 否定のロールプレイ。 誤設計（たとえば精算前の申請から手数料天引き）を AI に提案させ、「反例で否定→一次資料へ差し戻し→禁止リスト化」を実践してみてください
• 実地検分。 AI が「完了」と報告した変更を実画面で検分し、未配線や既定値の逆転を見つけてみてください