文書とは何なのか 理解負債とは何なのか

設計判断、意図（ADR）を残した文書があっても引き継ぎはうまくいかない
それはなぜなのか
これを古典的なソフトウェア工学論から分析してみる
NaurとRyle, Petronの論考を基にこの事象を言語化し、
さらにAI時代のNaurのいう「理論」は誰が持っているのか述べる。
そして、理解負債とはつまり何であるのかを捉えなおし、
結局はAIがあっても大枠は変わっていないのだという結論に至る。

Transcript

1. LT会 前回「What Is Software Design?」の続き 文書とは何なのか 理解負債とは何なのか Ref: Naur, Parnas, reeves N Naur 1985 P Parnas & Clements 1986 R Reeves 1992（前回） Stasshe ｜ 2026.10 1
2. 前回の結論：コードこそが設計、理由はADRに残す Reeves 1992 Reeves 残る問い ADR コードこそが設計 「なぜ」はどこに？ 理由を決定ごとに残す 2
3. 文書が揃っているのに、 引き継ぎが失敗するのはなぜか 3
4. 事例1：コンパイラの拡張、引き継ぎは手厚かった Naur 1985 注釈付きソース グループ A L のコンパイラを作った 詳細な設計文書 グループ B L + M へ拡張する A からの直接の助言 4
5. 結果：Bの拡張は、構造を壊すパッチになった グループ B グループ A 既存の仕組みを使わず、パッチを重ねる 一目で見抜き、構造の内側で解く Naur 1985 5
6. その仕組みは、 文書で詳しく論じられていた 6
7. 事例2：同じ文書、違う結果 Naur 1985 設計時からのチーム 別の運用チーム 知識と注釈付きソースだけで診断できる 文書と指導があっても行き詰まる 差は文書ではなく、人の側にある 7
8. I プログラムの本体はどこにあるか ADR は「なぜ」を残すための仕組みだった 背景 なぜ判断が必要だったか ADR が答える問い 決定 何を選んだか 「なぜ、こうなっているのか」 対象は、すでに下された決定。 結果 何を得て、何を失うか 却下案 検討して捨てた道 グループ B が受け取った「設計議論の文 書」も、この種類の情報だった。 8
9. ADRが残すのは過去の判断。次の判断ではない ADR-001 ADR-002 ADR-003 三者を統合 次の変更要求 ? 記録された過去 now まだ誰も判断していない 9
10. 01 プログラムの本体は理論である Peter Naur「Programming as Theory Building」 Microprocessing and Microprogramming 15, 1985 10
11. I プログラムの本体はどこにあるか Peter Naur と “Programming as Theory Building” Programming as Theory Building Peter Naur（1928–2016） Microprocessing and Microprogramming, 15(5), 1985 ALGOL 60 報告の編者 BNF（Backus–Naur Form）の N 2005 年 チューリング賞 プログラミングを「生産」ではなく「理論の構築」として捉 え直す論考。 Cockburn『Agile Software Development』の付録に再録。 11
12. プログラムとは、 人の頭の中にある「理論」である ソースコードは、その不完全な書き下しにすぎない 12
13. プログラミングは「生産」ではなく「理論構築」 生産モデル プログラマ 本体は成果物 Naur 1985 理論構築モデル コード・文書 理論 コード 本体は人の側 13
14. 「理論を持つ」とは：Ryleの意味で Naur 1985 Very briefly, a person who has or possesses a theory in this sense knows how to do certain things and in addition can support the actual doing with explanations, justifications, and answers to queries, about the activity of concern. 問いに答えら れる 正当化できる 理論を 持つ 説明できる 想定外の質問にも それが妥当である 理由 なぜそうするのか 行える 知的に振る舞う 14
15. 知ってる と 使える は違う．
16. I プログラムの本体はどこにあるか 知ってる と 使える は違う． F = ma 振り子 惑星 結論 規則は書ける。規則をどの状況に当てはめるかは書けない。理論とは後者を含む能力である。 16
17. I プログラムの本体はどこにあるか 理論は三つの領域で文書を超える 1 世界との対応 2 正当化 3 変更への応答 コードの各部分が現実のどこに対応 するか。現実のどこがコードに写さ れているか。何が関係するかの判断 は、世界全体を知る者にしかできな い。 各部分がなぜそうなっているか。ど の設計規則が今関係するかの判断は 、最終的にプログラマの直観に依る 。 新しい要求が既存のどの機能に似て いるかを知覚し、建設的に応える。 類似性は規則にできない。 一般的な文書 ADR が届く範囲：2 の一部 ADR の射程外 17
18. I プログラムの本体はどこにあるか 同じ挙動を実現する変更は、一つではない 理論を自然に延ばす変更 既存構造の内側で完結する 同じ外部挙動 現在のプログラム テストは両方通る 理論と矛盾するパッチ 外付けで挙動だけ合わせる 変更コストの本体はテキスト編集ではなく、理論との照合である。 18
19. では、理論はなぜ 書き下せないのか 21
20. I プログラムの本体はどこにあるか 規則として書き出せば済む、とはならない … 終わらない 規則 R″ R′ をいつ使うか 規則 R′ R をいつ使うか 規則 R こう書け 知的な振る舞いを「規則に従うこと」に還元すると、適用の規則が要り続ける（Ryle の無限後退）。 22
21. I プログラムの本体はどこにあるか 理論は類似性の知覚に依存する 人の顔 旋律 ワインの味 見分けられる。だが、見分ける基準は書き出せない。 プログラムでは 「この変更要求は、既存のどの機能に似ているか」── これも同じ種類の判断である。 23
22. 文書は、理論のコピーになりえない 書けるのは規則と事例。それをどう使うかは書けない 24
23. I プログラムの本体はどこにあるか 理論は関数、文書はその標本にすぎない 未知の要求 読み方 • 文書・ADR＝過去の（要求, 応答）の標 本 ━ 理論 f ┅ 標本をすべて通る、別の関数 未知の要求では、関数ごとに応答が分かれ る。 変更要求 x f(x_i) = y_i (i = 1, …, n) does not determine f(x_new) ※ 本発表の比喩 25
24. I プログラムの本体はどこにあるか コードは設計として完全、理論として不完全な射影 Naur 理論 頭の中。説明・正当化・変更への応答 射影（欠ける） Reeves コード まとめ Reeves：設計文書は要らな い。コードが設計だ。 製造に十分な、設計の完全な表現 ビルド（欠けない） Naur：そのコードからでは 足りないものがある。 成果物 ビルドの結果 26
25. 理論を失ったプログラムは「死ぬ」 Naur 1985 生 死 顕在化 理論を持つチームがいる チームが解散する 変更に応えられない 動いていることと、生きていることは別 27
26. 02 では、どうするべきか 理論が書けないなら、何で受け継ぐのか Naur 1985 → Parnas & Clements 1986 28
27. I プログラムの本体はどこにあるか Naurの答え：協働による継承 協働の中で得るもの 理論を 持つ者 新しい メンバー 密に協働する 1 現実の状況の中での、プログラムの位置 2 プログラムがどう動くか 3 異常な反応と変更を、理論の中でどう扱うか コードと文書だけでは不十分 29
28. だが、人は去る 30
29. 人が去ったときの、Naurの答え Naur 1985 蘇生 作り直し 文書から理論を再建する 新チームが一から解く → 厳密には不可能 → Naur はこちらを推す だが多くの現場では、作り直しは選べない 31
30. 現実的にどうするべきか
31. 文書
32. II 文書はどうあるべきか Parnas & Clements, “A Rational Design Process: How and Why to Fake It” (1986) 34
33. Parnas & Clements（1986） Parnas 1986 A Rational Design Process: How and Why to Fake It IEEE TSE 12(2), 1986 35
34. II ならば文書はどうあるべきか 文書の役割を問い直す：理論を運ぶのではなく、築かせる 誤った期待 現実的な役割 文書で理論を転送する 次の人が理論を築くのを助ける Naur の事例が示した通り、これは成り立たない 。 読み手の記憶を呼び起こし、思考の経路を作る 。 A. Cockburn, Agile Software Development (2001)、Naur 論考に付した解説より要約 問いが変わる：どういう文書なら、理論の再構築が速くなるか。 36
35. II ならば文書はどうあるべきか 文書が役立たない原因は、不足より編成にある 構成の悪さ 退屈な散文 思いついた順、実行順に書く。後の読者は必要な情報 を見つけられない。 一行のコードや図で済むことを長文で書き、同じ事実 を繰り返す。 用語の混乱 近視眼 一つの概念に複数の語。似て非なる概念に同じ語。 完成間際に、主要な判断を当然視した人が書く． 37
36. Naurで読み直す：理論を持つ者ほど、欠落が見えない 書き手が読むと 読み手が読むと 穴は理論が埋める 穴がそのまま残る 三者を統合 38
37. II ならば文書はどうあるべきか 設計は合理的な順序では進まない 1 発注者は何が欲しいか正確には知らない 2 必要な事実の多くは実装中に判明する 3 人間は細部の全体を理解しきれない 4 外部の変化が過去の判断を無効にする 5 人間は誤る 6 好きな設計アイデアを持ち込む 7 経済的理由で既存資産を流用させられる 理想 要求 → 設計 → 実装 定理を公理から証明するように、プログ ラムを要求から導出する。 そんな賢者の石は見つからない。 39
38. II ならば文書はどうあるべきか 読み手は、発見の追体験を望まない 発見の過程 理解しやすい過程 読み手が欲しいもの 定理が真であること ── つまり、プログラムを理解すること。 40
39. だから、偽装せよ 理想の過程を辿っていたら書いたはずの文書を、書く 41
40. II ならば文書はどうあるべきか 偽装せよ：合理的に設計したかのように書く 理想の過程が生む文書 書く文書 要求仕様（起こりやすい変更を含む） 理想の過程を辿っていたら書いたはずの文書 モジュールガイド（何を隠すか） モジュールインターフェース仕様 変更が起きたら その変更が最初からの設計だったかのように、文書 を書き直す。文書は常に現在の最終形。 uses 階層 モジュール内部設計 42
41. ただし、却下した道は残せ 数年後の保守者も、同じ疑問を抱くから 43
42. Parnasの文書とADRは、役割が違う 三者を統合 Parnas の文書 ADR 全体像を与える 境界を与える 常に最終形として書く なぜ他の道でないか 44
43. II ならば文書はどうあるべきか 全体像は内側の地図を、境界は輪郭を与える ✕ ADR ✕ 理論 ✕ ✕ 入力 解析 出力 Parnas 記号表 ✕ 最適化 ✕ ADR ✕ ADR 45
44. II ならば文書はどうあるべきか 前回の結論の更新：ADR は転送装置ではなく，足場に過ぎない 協働 理論そのものの継承 文書の目的 理論を運ぶことではない。 Parnas の文書 全体像（内側の地図） 次の人が理論を築く速度を 上げること。 ADR 境界（選ばなかった道） 前回：「ADR で理由を残す」 → 今回：「ADR は理論の境界を示す足場」 46
45. 03 AI時代、理論は誰が持つのか Naur の枠組みは、いまどこまで効くか ブラックボックス / 粒度 / 理解負債 47
46. よくある主張：AIのコードに、理論は一度もない これまで AI 生成コード 理論はあった 理論が一度もない 人が去って失われる（死） （死産）？ 2026 48
47. III AI 時代、理論は誰が持つのか 私たちはライブラリ内部の理論を持っていない 自分のアプリケーション（理論を持つ） それでも理論はある ライブラリ A ライブラリ B 内部は知らない 内部は知らない ライブラリ C 内部は知らない 境界の契約は知っている ・何をするか ・どう組み合わせるか ・境界で何が保証されるか 理論は全粒度で持つものではない。抽象化 こそが、理論を人の頭に収める。 49
48. 構造は変わらない 2026 ライブラリ AI生成コード 境界の理論 利用者 利用者 内部の理論 メンテナ そのセッションのAI 50
49. 変わったもの①：理論を持つ粒度 以前 2026 いま ドメイン・全体構造 ドメイン・全体構造 アプリのコード アプリのコード ライブラリの内部 AI モジュールの内部 OS・コンパイラ ライブラリ・OS 51
50. III AI 時代、理論は誰が持つのか 構造は変わらない。粒度とパラメータが変わった 変わったパラメータ 理論を持つ粒度 行・関数 ボックスの境界 保持者の寿命 年 セッション 作り直しのコスト 高い 低い 変わらない構造（Naur） ・理論は保持者とともにある ・保持者が去ればプログラムは死ぬ ・蘇生より、作り直しがよい 52
51. 理解負債 ＝ 理論の粒度と、変更の粒度のずれ 53
52. ずれがあると、どうなるか 2026 理論がある 境界への変更 内側への変更 一致 境界で応える・作り直す ずれ ＝ 負債 理論がない（ボックスの内側） 中を開けてパッチを当てる 54
53. III AI 時代、理論は誰が持つのか 返済は二方向：境界を合わせるか、理論を細かく持つか 境界を、変更の粒度に合わせる 理論の粒度を、細かくする ・「起こりやすい変更」に沿って切り直す ・契約とテストを書く ・内部は再生成で置き換える ・内部を読む ・実装した AI に説明させ、問いを重ねる ・理論を持つ人と協働する（Naur） どちらを選ぶかは、その部分がどれだけ変わるかで決める。 55
54. 今日の議論 問い 文書があっても引 き継げない Naur 理論は書けない 継承 Parnas AI 協働で。だが人は 去る 全体像と境界を 書く 粒度とパラメータ が変わる 56
55. 結論 文書は理論を運ばない。 次の人が理論を築く速度を上げる。 そして AI 時代には、理論をどの粒度で持つかを設計する。 57
56. 議論 持ち帰ってほしい三つの問い Q1 あなたのチームで、理論を持っているのは誰か。その人が去ったら、何が死ぬか。 Q2 ADR に「却下した代替案」を書いているか。それは境界を示しているか。 Q3 AI に書かせたコードの境界は、変わりうる設計判断を隠しているか。 58
57. 参考文献 Naur (1985) Programming as Theory Building. Microprocessing and Microprogramming 15(5). Parnas & Clements (1986) A Rational Design Process: How and Why to Fake It. IEEE TSE 12(2). Reeves (1992) What Is Software Design? C++ Journal. Ryle (1949) The Concept of Mind. Cockburn (2001) Agile Software Development. Naur の再録と解説。 Storey ほか (2025〜) 理解負債（cognitive debt）。 59
58. ありがとうございました あなたのチームで、理論はどこにありますか？ 60