巨大フレームワークをAIと作って気づいた、開発哲学を『明文化』する技術 は、30クレート・70万行規模のRust製フレームワークをClaude Codeとともに開発してきたエンジニアによる実録記事です。セッションをまたぐたびに「昨日と違う書き方」をしてくるAIの問題を、1.4KBの設計哲学ファイルで制御しようとした試みと、その方法論が具体的なファイルを交えて記されています。
「うちはこう書く」という前提を、AIに渡せる形で外に出す——この一文に、この取り組みの核心があります。
暗黙知が「渡せない資産」になる問題
人間同士のチームでは、コードレビューや日々のやり取りを通じて設計の流儀が自然に伝わります。明文化されていなくても、経験から学んだ規範が共有されていく。
ところがAIエージェントはセッションごとにリセットされます。蓄積も引き継ぎもありません。これは「新人が毎日入れ替わる環境」とも異なる、「記憶が毎回ゼロになる環境」です。暗黙知に依存した開発フローは、AIとの共同作業には構造的に合いません。
この問題は、AIの能力とは独立しています。Claude Codeは一つひとつのdiffを見れば優秀です。一貫性が崩れるのは能力の問題ではなく、前提の欠如の問題——そこが重要な視点です。
「明文化」が開発インフラになる
記事が示すのは、この問題への構造的な応答です。instructions/DESIGN_PHILOSOPHY.md という10箇条・1.4KBのファイルが、70万行のコードベース全体にわたる判断の起点として機能しています。
注目したいのは、このアプローチが「AI対応の特殊な施策」ではなく、ソフトウェア設計の基本——「判断の根拠を書き出す」という行為——をAI時代に合わせて再解釈したものだという点です。
ドキュメントはこれまでも重要とされてきましたが、「あれば良い」という位置づけに留まりがちでした。AIとの協働では、設計哲学の明文化は開発インフラの一部になります。AIに渡す前提の質が、そのまま出力の質に直結するからです。
記事中の「増幅器」という比喩がこの構造をよく表しています。同じ増幅器でも、入力の質が異なれば出力の質も変わります。哲学が明文化されていなければ、曖昧さがスケールします。
1.4KBという数字が示す実践可能性
「分厚いスタイルガイドを用意しなければならない」——その思い込みが、明文化のハードルを高く見せてきた面があります。しかしこの事例は逆を示しています。原則を10個に絞り込み、AIが参照できる形で置いておく。それだけでコード一貫性への入力として機能するのです。
「明文化が十分か」という問いは残ります。哲学ファイルが正確に解釈されるかは、書き方と運用にも依存します。ただ「暗黙知のまま持ち続けること」と比べたとき、明文化が圧倒的に優位であることは、この70万行という規模が示しています。
AIとの大規模開発において、設計哲学の外部化は選択肢ではなく前提になりつつあります。この実践が示す最も重要な点は、そのハードルが思ったより低い——「始められる」という実践可能性です。
出典: 巨大フレームワークをAIと作って気づいた、開発哲学を『明文化』する技術（kent8192）
関連記事
- AIエージェントによるリスク評価・承認フロー自動化は、人間の最終判断責任を維持できるのか？
- サイバーセキュリティ特化型AIモデルは、汎用モデルよりも防御効果を実質的に高めるのか？
- Check out real-life AI prototypes from the Futures Lab.
参考文献
コメント