■ 1. 問題提起
- リファクタリングにはドメイン知識が必須であり、顧客の文脈や要求まで遡る必要がある
- 「そのドメイン知識をどこに、どんな形式で保管するか」が語られる機会は少ない
- 知識の保管場所を誤ると、リファクタリングの前提となる情報そのものが腐敗する
- AIコーディングエージェントが普及した現在、この問題はさらに深刻化している
■ 2. 知識の4分類
- How（どう動くか）: 関数の振る舞い、データの変換手順
- What（何をすべきか）: 入力に対して返すもの、拒否するものの定義
- Why（なぜそう決めたか）: 技術選定の理由、設計判断の背景
- Why not（なぜそうしなかったか）: 検討して却下した代替案とその理由
■ 3. 各知識の適切な配置先
- How → コード:
- 「どう動くか」の正本はコード自体であり、読んだだけで意図が伝わるコードを指す
- DDDのユビキタス言語に対応し、Brand型やValue Objectでドメイン概念を型に埋め込む
- コードを変更すればHowの記述も自動更新されるため、腐敗への耐性が高い（Self-Documenting Code）
- What → テストコード:
- 「何をすべきか」の正本はテストコードであり、実行すれば嘘をつけない
- 仕様と実装がずれた瞬間にCIが赤くなり、同期の強制を機械に委ねる
- テストが仕様として機能するのは、テスト名が「何をすべきか」を表現している場合に限る
- テスト名を仕様書として書く習慣がない場合、テスト数だけ増えて何を守っているか不明になる
- Why → ADR（Architecture Decision Records）:
- 技術選定・アーキテクチャの分岐・仕様の取捨選択といった大きな判断を記録する
- 内容を書き換えず、状況が変わった場合は新しいADRでsupersede（置換）する
- タイムスタンプとステータスが明示されているため、AIも有効性を構造的に判断できる
- Why not → ADRのWhy notセクション:
- 「何を選ばなかったか、なぜか」はコードに現れないため最も失われやすい知識
- この情報が失われると、同じ議論を半年後に繰り返すことになる
- ADRはイミュータブルであるため判断が消えず、JSDocのようにコードと共に消えない
■ 4. 自然言語ドキュメントが正本として機能しない理由
- 仕様書はコードが変わっても自動更新されない
- 古い仕様書と新しい仕様書が混在すると、AIがどちらを信じるかの判断に揺れが生じる
- 「事実だけ保存する。導出可能なものは保存しない」という原則（そーだい原則）が適用される
- コードから導出できる情報を別の文書にも書くと二重管理となり、乖離が必ず発生する
- 乖離した文書をAIが参照すると、古い仕様で実装する事故が起きる
■ 5. 型とテストの守備範囲の分離
- 型（コンパイル時）で守れるもの: IDの取り違えやエラー処理の漏れなど、構造的に判定できるもの
- テストで守るべきもの:
- 「退職済みメンバーの操作を拒否する」のような実行時ロジック
- 「48時間で期限切れにする」のような時間依存の振る舞い
- 型で守っている範囲をテストで二重に検証すると無駄が生まれるため、守備範囲を混同しない
■ 6. 抽出可能性と設計品質の関係
- コードからドメイン用語集やアーキテクチャ図を自動抽出しようとする試みは、設計品質のバロメーターになる
- 抽出スクリプトを書くことが異常に難しい場合、スクリプトではなくコードの設計が問題
- 適切な命名規則（例:
src/domain/member/MemberId.ts）であればファイル名だけで用語集が作れる- 汎用的な命名（例:
src/utils/helpers.ts）ではスクリプトによる判別が不可能■ 7. まとめ
- ドメイン知識を「人の頭」や「手書きの仕様書」だけに置くと、人の異動や仕様書の腐敗によりリファクタリングの前提が失われる
- 配置原則:
- How→コード
- What→テスト
- Why・Why not→ADR、コードから導出可能な説明文書は置かない
- AIコーディングエージェントと協働する時代において、この配置原則の価値はさらに高まる
- テストは「通るか通らないか」の二値で答え、型は「コンパイルできるかできないか」の二値で答える
- ADRはイミュータブルな記録としてAIにも人にも同じ情報を伝える