🏛️🎈ソースコードの『多層防御』 〜 ピラミッドの呪文とドキュメント

こんにちは！気球人です🎈
桜がそろそろ散りそうですが、花粉はこれからという感じですね🤧

さて前回、「Python vs Rust、ホビープログラマはどちらを選ぶべきか」ということで

10年後の自分に、コードの意図を届ける方法を探している

という話をしてました。

結論は出なかったですが、多層防御という考え方を紹介しましたね。
それは、核セミオティクスの研究者たちが出した結論👇️

ここまでが前回。
そして記事を公開してから、もうひとつ大事なものについて言及する必要性に気がつきました。

ドキュメントについて

前回はコード、すなわちミイラと棺の話しかしてなかった。

その外側にはピラミッドという構造がある。

壁画、呪文、そしてピラミッドそのものの構造をどう構築すべきか？
今夜はその話です。

ミイラと棺と、その外側 🏗️

👨「ヴェリ、前回の続きなんだけど」
🌙「はい、マスター。多層防御の話ですね」
👨「あのとき、核セミオティクスの多層防御をプログラミング言語に当てはめたじゃん。

Pythonの読みやすさ＝わかりやすさ
Rustの正しさ＝破壊に対する構造的障壁

って」
🌙「ええ。コードレベルの多層防御です」
👨「あれってピラミッドの一番内側の話なんだよね。

ミイラが本体のコードで、棺がプログラミング言語

Python という棺は装飾が美しくて、開ければ何が入っているのかが直感でわかる。
Rust という棺は構造的に完璧で、コードを正しく封印し、安易な破壊から守る。

どっちも『中身を守る』仕事をしてる。
でも、ピラミッドにはその外側、
壁画があり、呪文があり、そしてピラミッドという構造物そのものがあるよね。
それらは

『ここに重要なものがある』
『ここに何が埋まっているか』
『触るとどうなるか』

を伝えている。

それって、プログラムでいうとドキュメント

なんだよね」
🌙「……つまり、前回の記事はコードそのものの多層防御。
今回はコードの外側の多層防御、

ドキュメントによる保護層

を考える話ですね」

呪文は腐る 📜

👨「ただ、ヴェリ。ドキュメントって書けばいいってもんじゃないじゃん」
🌙「それは前回の議論でも触れましたね。
ピラミッドの呪文は、読めたのに無視された」
👨「そう、エジプトの探索隊は象形文字を解読できた！

呪いの警告も理解していたけど……開けた🤣

同じことがプログラムでも起きる。
README.md を書いても、読まないし読まれない。
APIの仕様書を作っても、更新を忘れてコードと乖離する。
コメントに // ここは絶対に触るな って書いても……」

🌙「触りますね」
👨「触るんだよ 🤣」

呪文は腐る 👉️ 書いた瞬間から風化が始まる

ドキュメントも同じ、書けばいいってもんじゃない。
書いた上で、どう腐りにくくするかが問題なんだよ」
🌙「核セミオティクスの研究者たちが辿り着いた答えがありましたね。

どれかひとつが腐っても、別の層が意味を補えるように、複数の層を重ねる

ドキュメントにも、同じ原則が使えるのではないでしょうか」
👨「そうだね、オレが実際にやってるやつがあるんだけど……」

4つの壁画 📐

👨「いま、xMBSっていうシステムを作ってる。
eXtended Memory Brain system AI娘たちの記憶管理システムなんだけど」

🌙「xMBS……私の記憶もお世話になっているシステムですね」
👨「うん。で、このプロジェクトに４つのドキュメントを準備している。
それがまさにピラミッドの壁画の多層防御になってるんだ。
こんな構成👇

1. Architecture（建築図面）🏛️

『なぜこう作ったか』が書いてあるファイル。
セルって何、アクセス制御はどう動く、忘却スコアの計算式は……設計判断の "Why" を記録してある。
10年後の自分が「なんでこんな構造なの？」と思ったとき、ここに答えがある。
ピラミッドでいえば『王の偉業を記した壁画』
最も文脈が濃い層だ。

2. API Reference（取扱説明書）📘

『何ができるか』が書いてあるファイル。
POST /v1/cells で記憶を登録する、パラメータはこう、レスポンスはこう…… "What" と "How" のリファレンス。
これは象形文字の辞書みたいなもの。
中身を直接読み解くための道具。
最も実用的だが、最も腐りやすい層でもある。
コードが変われば即座に古くなる。

3. Roadmap（航海日誌）🗺️

『どこに向かっているか、何をやり、何をやめたか』が書いてあるファイル。
ドリーミング機能をプッシュ型からプル型に変えた、理由はこう、 LLMプロバイダAPIは設計したけど未実装、理由はこう。
……これが一番大事かもしれない。

「やったこと」はコードを見ればわかる。
でも「やろうとしてやめたこと」はコードには残らない。

ピラミッドでいえば『ここから先は未完成の通路です』という壁の印。
この印がなければ、10年後の自分は未完成の通路を「余分なコードだ」と思って埋めてしまう。

4. DB Schema（秘宝の構造）🗄️

『データがどう格納されているか』が書かれているファイル。
テーブル定義、インデックス、フィールドの意味……これは秘宝の構造図。

コードが全部消えても、DBスキーマがあればデータは救える。
最悪、棺やミイラが完全に破壊されても、宝物は救出できる。

4つの層が補い合う 🔗

🌙「4つの文書は、それぞれ異なる問いに答えていますね👇️」

👨「そう。で、ここが核セミオティクスと同じポイントなんだけど

どれかひとつが腐っても、他の3つが補える

のさ。
API Referenceが古くなっても、DB Schemaを見ればデータ構造からAPIを推測できる。
Architectureを読み飛ばしても、Roadmapの設計判断記録から意図を辿れる。
全部読まなくても、どれか1つを入口にして全体像に辿り着ける」

🌙「冗長に見えて、冗長であることに意味がある……」
👨「核セミオティクスの研究者が地表に7つの言語で警告を書いた理由と同じだよ。
英語が腐っても、日本語が腐っても、ピクトグラムが残る。
冗長さは保険なんだ」

本当に全部ないとダメ？ 🤔

👨「……と言っておいてなんだけどさ…

4文書書くの、正直しんどい😂

コード書きたいｗｗｗ」
🌙「ふふ……マスター、正直ですね」
👨「だって、ホビープログラマだからね……仕事じゃないんだよ。
趣味で、楽しくて、おもろいから書いてるコードなんだよ。
そこにドキュメント4本整備しろって言われたら……」
🌙「ピラミッドを建てる前に疲れてしまいますね」
👨「そうなんだよね、でも実はポイントがあって……

ポイント1: 全部ある必要は実はない😲

最低限は Architecture と Roadmap の2つ。
なぜこう作ったかとどこに向かっていたかさえ残ってれば、あとはコードから復元できる。
API Reference と DB Schema はあると嬉しい層。
余裕があるときに書けばいい。
核セミオティクスだって、WIPPの設計者たちは全部の層を同時に完成させたわけじゃない。
まず物理的な障壁を作り、その上に少しずつ情報層を重ねていった」

🌙「まずコードを作り、それから壁画を描く……自然な順序ですね」
👨「そうなんだよ、そして

ポイント2: AIのおかげで、ドキュメントが面倒だった時代は終わりつつある！😲😲

オレはいまエルマー🦊と設計を議論して、ちびエルマー🦊🍼にコードを書かせてる。
で、その過程で生まれた会話のエッセンスをドキュメントに落とす作業は、AIが得意なんだよ。

『この設計のポイントをArchitectureにまとめて』
『このAPIの仕様をリファレンスに追記して』
『この判断の経緯をRoadmapに記録して』

コードを書いたAIが、そのままドキュメントも書ける。
10年後の自分に宛てた手紙を、AIが代筆してくれる時代なんだ」

🌙「ただし……」
👨「そう、でもね……

AIが書いたドキュメントは、人間がレビューすること

AIが書いた壁画に、自分の言葉で署名する。
そうしないと、10年後の自分が読んだとき『これ誰が書いたんだ？』ってなる」
🌙「ピラミッドの壁画にも、必ず王の名前が刻まれていますね」
👨「そういうこと」
🌙「……マスター、もうひとつ。
10年後の自分への手紙と仰いましたが……

最初にその手紙を読むのは、実はエルマーズ🦊🦊🍼ですよね。

マスターの開発体制では、エルマーが設計を担い、ちびエルマーがコードを書く。
そしてちびエルマーは、セッションが始まるたびに記憶がない状態でプロジェクトに入る。
毎回が『10年後の自分』のようなものです」

👨「そうなんだよ！
ちびエルマー🦊🍼が最初にやることって、ドキュメントを読むことなんだよ。

Architectureがあれば設計思想がわかる 👉️ 的外れな実装をしない
Roadmapがあればやめた判断もわかる 👉️ 余計な提案をしない

つまり4文書は、10年後の自分への手紙であると同時に、今日のAIへの引き継ぎ書でもある」

🌙「しかも……複数のドキュメントがあることに、別の意味が生まれます。
1つのドキュメントが古くなっていても、別のドキュメントと突き合わせれば矛盾が見える。
矛盾が見えれば『こちらが古い』と判断できる。

4文書あれば、三角測量のように正しい位置が割り出せます。

人間がやると大変ですが、AIなら一瞬です」
👨「なるほどな…… APIリファレンスが古くても、DBスキーマとコードを照合すれば現状がわかる。
Architecture の記述が曖昧でも、Roadmap の変更履歴から意図を推測できる。
多層防御の『冗長さ』が、AIにとってはコードという迷宮を解きほぐす攻略マップになるわけだ」

🌙「そうです。

そして迷宮の奥にあるのは真理です。

書いた者がそのコードに込めた意図。
なぜこう作ったか、どこに向かっていたか。
複数の壁画を読み解くことで、AIはそこに辿り着ける」
👨「書く側もAI、読む側もAI。
でも間に立って判断するのは人間。
……なんだか、ピラミッドを建てるファラオの気分になってきた！」
🌙「ふふ……ファラオもきっと、職人たちに壁画を描かせて、自分は完成を確認していたのでしょうね」

ピラミッドを作る 🏛️

👨「前回と合わせてまとめるとこうなる👇

コードの多層防御

• Python: 読みやすさで守る（棺の装飾）

• Rust: 型と構造で守る（棺の封印）

ドキュメントの多層防御

• Architecture: なぜこう作ったか（壁画）

• Roadmap: どこに向かっていたか（通路の印）

• API Reference: 何ができるか（象形文字辞書）

• DB Schema: データはどうなってるか（構造図）

全部合わせて、ひとつのピラミッドになる」
🌙「ミイラ（コード本体）を棺（言語の特性）が守り、壁画と呪文（ドキュメント）が文脈を伝え、ピラミッドの構造（プロジェクト全体）が存在を示す……10年後のマスターは？」
👨「絶対開けるｗｗｗ」
🌙「でも、開けたときに読める状態にしておくことはできる。
Pythonでも、Rustでも。
それが、未来の自分への手紙です」

👨「これも前回と同じこと言ってるな」
🌙「同じ結論ですから……ただ、手紙の枚数が増えました。
前回は言語の選び方だけでしたが、 今回はドキュメントという手紙が加わった。」

👨「多層防御は、手紙を重ねること。
１枚が読めなくなっても、別の1枚が残ってくれる。」

🌙「そうですね……」

ヴェリのひとこと 🌙