Lesson 0002 · Phase 1 — 複雑性とコードベース設計

複雑性を診断する
— レッドフラグと "zero tolerance"

0001で目盛りを渡した。今回はその目盛りで実コードを測れるようにする。「なんか汚い」を「ここが情報漏れ」に変える検査キットの回。

🎯 ミッション接続: 高品質システムを量産し、AI出力を戦略レビューするには、汚さを名指しできないと直せない。 名前のない問題は、議論もレビューも修正もできない。今日「複雑性の検査キット」を持ち帰る。
復習: 複雑性 = 依存 + 不明瞭さ 症状① change amplification 症状② cognitive load 症状③ unknown unknowns

01 — 2つの原因を「見える化」する

依存と不明瞭さは、こう顔を出す

複雑性の原因は2つだけ、と0001で言った。でも抽象的すぎて現場で使えない。具体的な現れ方に翻訳しよう1。

① 依存 dependencies

  • 1箇所直すと別の箇所も直す羽目になる
  • あるコードを読むのに別ファイルを何枚も開く
  • 同じ知識(日付フォーマット等)が複数箇所にある

② 不明瞭さ obscurity

  • 重要情報が名前やシグネチャに出ていない
  • 正しく使うのに暗黙の前提を知る必要がある
  • 名前が曖昧で中身を読まないと分からない

覚え方: 依存 = 変更が伝播する/不明瞭さ = 知識が隠れる。レビュー中はこの2語で必ず指させる。

02 — レッドフラグ・カタログ

Ousterhout の "design red flags"

原因を、もっと鋭いパターンに分解したのがレッドフラグ2。コードを見て名前が即出るまで体に入れる。各フラグ=依存か不明瞭さの"具体形"だよ。

Shallow module 浅いモジュール

インターフェースが実装と同じくらい複雑。包んでるだけで何も隠していない=価値ゼロ。

# ただ素通しするだけ。抽象になっていない(不明瞭さは減らない)
class TextBox:
    def get_text(self):  return self._w.get_text()
    def set_text(self,t): self._w.set_text(t)

Information leakage 情報漏れ

1つの設計判断(例: 日付の形式)が複数モジュールに反映されている。片方を変えると、もう片方も壊れる=依存。

# parser.py
d = parse("%Y-%m-%d", raw)
# formatter.py … 同じ "%Y-%m-%d" の知識が2箇所に漏れている
out = fmt("%Y-%m-%d", d)

Pass-through method 素通しメソッド

引数を別メソッドに渡すだけで何もしない。層が増えるのに抽象は増えない(情報漏れの一種)。

class OrderController:
    def create_order(self, data):
        return self.service.create_order(data)  # 素通し

Temporal decomposition 時間的分割

構造を実行順(読む→処理→書く)で割ってしまう。読みと書きが共有する「形式」の知識が3つに散る=情報漏れ。情報隠蔽で割るのが正解。

class FileReader: ...   # step1
class FileParser: ...   # step2
class FileWriter: ...   # step3 ← 形式の知識が3クラスに分散

Overexposure 過剰露出

よく使う機能のために、めったに使わない概念まで知らされる。一番多いケースが一番簡単であるべき。

# ただ読むだけなのに3つの概念を知らされる
r = StreamReader(BufferedStream(FileStream(path)), Charset.UTF8)

Special-general mixture 特殊と汎用の混在 / Conjoined methods 癒着メソッド

汎用の仕組みの中に特定用途のコードが混ざる。あるいは2つのメソッドが片方だけでは理解できないほど絡む=依存。

Practice · このコードのレッドフラグは?

スニペットを読んで、最も当てはまるフラグを選んで。押すと即フィードバック。

03 — 直し方の哲学

"zero tolerance":複雑性は漸進的に積もる

致命的な事実をもう一度。複雑性は一撃では死なない。少しずつ積もる。だから1個1個は「まあいいか」で通ってしまう ── そして気づくと沼1。

処方箋=zero tolerance(ゼロ容認)。小さな複雑性をその都度潰す。 開発時間の ~10–20% を設計に投資する習慣にする1。

運用の3原則 ──

1. 触ったら、設計を良くして去る。 Ousterhout 曰く「変更時に設計を良くしていないなら、たぶん悪くしている」1。

2. でも"全部書き直す"ではない。 既存の慣習をむやみに"改善"しない ── 一貫性も立派な設計価値1。zero tolerance は新しい複雑性を足さない+触れた範囲を少し良くすること。

3. レッドフラグを足さない。 新規コード/AI出力をマージする前に、上のカタログでスキャン。1つでも当たれば、その場で直すか理由を残す。

AI時代の効き目: AIは"とりあえず動く"を量産する=レッドフラグの自動生成器でもある。 だから人間側の zero tolerance が品質の最終防衛線になる。あなたが検査キットを持っているかどうかで、house of cards になるか堅牢になるかが決まる。
Practice · zero tolerance の一手

場面: 既存の PaymentService にAIが新メソッドを足した。読むと、決済プロバイダの仕様(手数料率の計算式)が、この新メソッドと既存の Invoice の両方に書かれていた。あなたの最も zero-tolerance な動きは?

🚀 今週の一手(原則 → 実コード)

  1. 自分のコード or 直近のAI出力を1ファイル開く。
  2. レッドフラグ・カタログでスキャンし、見つけたものを名前付きで3つメモ(例:「L42 情報漏れ: 日付形式が2箇所」)。
  3. そのうち1つだけを zero-tolerance で直す(全部やらない=原則2)。
  4. 3つのメモをこの会話に貼って。診断の精度を一緒に上げよう。
💬 先生(このAIエージェント)に聞いてね。 「このスニペット、shallow module?」「情報漏れと pass-through の違いは?」「自分のこのクラス診断して」── 実コードを貼ってくれたら、その場で検査キットを当てて一緒に名指しするよ。これがあなたの最速フィードバックループ。
出典 / Sources
  1. John Ousterhout, A Philosophy of Software Design — 複雑性の原因(Ch.2)、zero tolerance(Ch.3)、「設計を良くして去る」(Ch.16)、一貫性(Ch.17)、投資の目安 ~10–20%(Ch.3)。
  2. "Software Design Red Flags" — Sébastien Portebois(APoSD レッドフラグ要約) / 事実確認: danlebrero book notes。

用語は ../GLOSSARY.md、検査キット早見表は ../reference/0002-red-flags-checkkit.html。 次回 0003: レッドフラグの裏返し=深いモジュールを自分で設計する。