ソフトウェア設計入門｜「動いた」と「作り終えた」の間にあるもの——後悔から逆算する設計論

Twelve-Factorという後悔リスト——12個のうち、まず3個でいい

12全部を覚える必要はない。個人開発の実害に直結する「設定・依存関係・ログ」の3ファクターから守る。

ソフトウェア設計の入口として最も費用対効果が高い文書が、Twelve-Factor Appです。自己紹介はこう始まります——“Software as a Service を作り上げるための方法論である”。クラウドで動くアプリを大量に運用したHerokuのエンジニアたちが、失敗の反省を12の原則に圧縮したものです。

個人開発に効く3ファクター

なぜ「設定の外出し」が最初なのか

コードと設定の分離は、12個の中で最も事故と直結します。APIキーの直書きはリポジトリを公開した瞬間に流出事故になり、実際にクラウドの認証情報がこの経路で盗まれる事件は後を絶ちません。環境変数への外出しは30分の作業で、流出事故と環境差異の両方を一度に予防します。セキュリティ面の続きはアプリケーションセキュリティの記事で扱っています。

「あとで効く設計」を今日入れる——3つの最小実装

設計の導入は書き直しではない。既存コードのまま、設定・依存・ログの3点だけ整えれば、運用の土台はできる。

ソフトウェア設計の導入というと大改修を想像しがちですが、最初の3手は既存コードをほぼ触りません。それぞれ30分〜1時間の作業です。

手順1: 設定を環境変数へ

// ❌ 流出予備軍
const stripeKey = "sk_live_abc123...";

// ✅ コードには「何が必要か」だけを書く
const stripeKey = process.env.STRIPE_SECRET_KEY;
if (!stripeKey) throw new Error("STRIPE_SECRET_KEY が未設定です");

手順2: 依存をロックする

package-lock.json や uv.lock のようなロックファイルをリポジトリに含め、インストールはロックに従うコマンド（npm ci 等）で行います。これだけで「他の環境で入れ直したらバージョン違いで壊れた」が構造的に消えます。

手順3: ログを1行のイベントとして標準出力へ

ファイルに独自形式で書き込むのではなく、1件のイベント＝1行のログを標準出力に流すだけにします。集約・保存・検索は実行環境（クラウドのログ機能）の仕事に任せる——これがTwelve-Factorの「XI. ログ」の考え方で、後から監視や通知を足すときの土台になります。エラー時の通知設計はn8nのError Workflowの思想と同じで、「静かに壊れる」を防ぐ第一歩です。

重い理論はいつ学ぶか——痛みが最高の教科書

クリーンアーキテクチャもDDDも、解決する痛みを経験してから読むと一気に腹落ちする。読む順番より、痛みの観察を優先する。

ソフトウェア設計の世界には、Twelve-Factorの先に有名な理論群が控えています。全部を先回りで学ぶ必要はありません。それぞれが特定の痛みへの処方箋なので、痛みが出たときに読むのが最短です。

痛みと処方箋の対応表

AI時代の設計の位置づけ