配布資料 30構築年表 第1章 — ドキュメント駆動の歩み

すべての日付・件数は題材プロジェクトの git 履歴（origin/master・2026-07-17 時点・総コミット 5,864）の実測値。

実装を始める前に、コミットが2.4ヶ月間まったく止まっている時期があります。 グラフで見ればただの空白で、外から見れば完全な停滞です。

その空白が、その後の速度を買っていました。

この章はその話をします。

この章で言いたいこと

1. 文書がどう育ったか。 実際のプロジェクトで文書がどう生まれ、どう育ち、どう再編されたか
2. なぜ文書の質が実装の質を決めるのか。 AI は文書を読んで実装します。文書の質が実装の質の上限になります
3. 腐らせないところまでが仕事だということ。 「あとで更新」は必ず腐ります。腐らせない仕組みまで作って初めて文書は資産になります

---

1. 文書はどう育ったか

コードより先に文書を書く姿勢は序章の初日から

扱うのは 2026年3月上旬の「仕切り直し」以降（本編・約4.5ヶ月）で、それ以前の約5ヶ月は序章として扱います。

序章では、AI を用いた開発を手探りしながら別サービス（予約系）を試作し、どんなサービスを作るかのブレインストーミングを繰り返していました。一度は全面作り直しもしています。

ただし序章にも既に萌芽があります。 初回コミット（2025-10-15）の時点で、事業計画書・要件仕様書・システム設計書など9本の計画文書が同梱されていました。

コードより先に文書という姿勢は、序章の初日から一貫しています。

2.4ヶ月の沈黙のあと、9分間で要件57本が入った

序章の試作の最終コミット（2025-12-23）から2026-03-04まで、約2.4ヶ月間コミットが完全に途絶えます。

この空白は序章の締めくくりでした。ブレインストーミングの収束——チケット販売への決定——と、リポジトリ外での要件定義の執筆に充てられています。

明けた2026-03-04、わずか9分間の3コミットで約100文書が一括インポートされました。

• 機能単位の要件定義 57本（抽選・返金・もぎり・座席・Bot対策・特商法 など）
• 設計 11本（システム構成・データモデル・状態遷移・API設計・バッチ設計）
• 画面設計 9本・実装フェーズ計画 9本
• そして起点には AI による deep-research レポート2本（業界調査・データモデル調査）

要件定義そのものが AI リサーチから始まっていた痕跡が、ここに残っています。

実装開始までの6日間

「要件57本 + 設計 + 計画 + ワイヤーフレーム129枚」が完成してから3日後に実装開始、6日後にイシュー駆動運用開始です。

この順序は git 上で実証できます。 以降の実装速度（4.5ヶ月で5,800コミット超）は、この事前文書群の上に成立しています。

文書は98本から274本へ増えた

カテゴリも計画的に生まれたわけではありません。必要になった瞬間に増えました。

テスト（03-11・実装開始直後）→ 環境構築（03-16・staging 構築期）→ 法務（05-09）→ ホワイトラベル（05-14）→ 返金（05-15）→ リファクタリング（05-30）→ …→ 営業資料（07-16）。

文書体系は、事業の歩みの写像になります。

---

2. なぜ文書が実装の質を決めるのか

文書は読み物ではなく実行環境

従来のドキュメントは、人間が読むための参考資料でした。

AI 駆動開発では違います。AI は文書を読んで実装します。

要件文書の曖昧さはそのまま実装の曖昧さになり、設計文書の欠落はそのまま AI の勝手な発明になります。 「文書の質が実装の質の上限」というのが実感です。

観測された効果は4つあります。

1. 並列性。 要件57本が独立した文書として存在したから、AI に「この要件を実装して」と1本ずつ、並列に投げられました。文書の分割単位がそのままタスクの分割単位になります
2. ブレの抑制。 ワイヤーフレーム129枚を「デザインの正本」と規定したことで、AI が画面ごとに配色・余白を発明する事故が構造的に減りました。正本を先に置くことは、AI への最大の制約条件になります
3. 判断の再現性。 「なぜこの設計か」が文書に残っているため、数ヶ月後の変更時に AI 自身が経緯を読んで整合的な判断ができます。文書は AI の長期記憶の一部として機能します
4. 人間の役割との接続。 「発注者」役割の実体は要件文書を書くことであり、「監督者」の検収基準は設計文書に書かれた完了条件です。ドキュメント駆動は「AIに仕事をさせるという仕事」の実務形態そのものでした

文書を書く時間は実装の遅れではない

2.4ヶ月の要件定義期間は、コミットグラフ上は完全な空白、つまり停滞に見えます。

しかしその直後の4.5ヶ月で、5,800コミット・実サービス運用まで到達しました。

沈黙の2.4ヶ月が、その後の速度を買いました。

経営の立場の方に伝えるべきは、この投資構造だと思っています。

---

3. 腐らせないところまでが仕事

4ヶ月で3種類の劣化が起きた

急成長の代償として、4ヶ月で文書体系は3種類の劣化を起こしました。2026-06-30 の棚卸しで実測された問題です。

• 散乱。 返金・法務・ホワイトラベル等の文書が、正規の体系外に7ディレクトリ分散していました
• 重複・衝突。 ディレクトリ採番の衝突。同一トピックの文書が複数箇所に併存し、どれが正本か分からない状態になっていました
• 陳腐化文書と現役文書の同居。 災害復旧（DR）情報が11ファイルに分散し、古い手順が現役のように見える危険な状態でした

AI 駆動開発では、劣化の被害が人間の場合より深刻になります。

AI は古い文書も「正」として読んで実装するからです。 腐った文書は、腐った実装を自動生産する装置になります。

吸収して、再編して、仕組みにする

再編で特筆すべきは、移動前に「計画書だけのコミット」を作り、承認を得てから1ファイルも動かしたことです。承認ゲートです。

そして確定した設計原則は、そのまま移植できる普遍則になりました。

1. 1トピック = 1正本（重複を作らない）
2. 各ディレクトリに索引ファイル必置・同番号禁止
3. 削除せずアーカイブへ退避 + 墓標（tombstone）を残す
4. 文書に status ヘッダ（現役 / 参考 / 置換済み）
5. 運用手順書は AI が読んでそのまま実行できる自己完結性
6. 「索引 → 概要 → 詳細」の3層構成

コード変更と文書更新を同じコミットに縛る

再編しただけでは半年後にまた腐ります。

出した答えはコード変更と文書更新を同一コミットに強制することでした。

• doc-ownership.tsv。 どのコードがどの文書のオーナーかを AI が読める対応表にします（現在40行）
• hook 三段構え。 編集直後の軽いナッジ → コミット時の動的な関連文書提示 → コミット時の静的検査。金銭・DR・スキーマ・法務は、文書未更新だとコミット自体をブロックします
• 詳細は catalog/01_hooks.md・catalog/05_settings_misc.md にあります

そして正直に書いておくと、この仕組みの適用範囲外だった領域は、実際に腐りました。

rules の後発更新が skills 2件に反映されず、旧仕様のまま残っていた事例があります（この教材の解析中に発見）。 「対応表に載っていない文書は守られない」ことの、生きた証拠になってしまいました。

仕組みの網羅性そのものを定期監査する必要があります。ここまで含めて陳腐化防止です。

---

手を動かすなら

• Keihi の機能1つについて「AI がそのまま実装に使える要件文書」を書き、実際に AI に実装させて、文書の曖昧さが実装にどう現れるかを観察してみてください
• 自分のプロジェクトの docs 棚卸しミニ版です。正本不明・重複・陳腐化の3観点で15分だけ監査してみてください
• 自分のプロジェクト向けの doc-ownership 対応表を5行書いてみてください。どのコードが変わったらどの文書を直すか、です