renaissance-architecture

ルネサンス建築

本当に新しいものを作りましょう。「Y向けのX」ではなく。

---

基本理念

問題は最新のツールではありません。創作ではなく解説を作っていることです。

中世の学者たちは、新しい哲学を生み出す代わりにアリストテレスの注釈を書きました。私たちは新しいSFを生み出す代わりに、『スター・ウォーズ』のスピンオフを作っています。どのようなワークフローが可能になるかを考える代わりに、既存のワークフローにAIを追加しています。

ルネサンス建築とは、次のことを意味します。

• 何を作るべきかについての、第一原理に基づく思考
• どのように作るかについての、実用的な選択
• 古いパラダイムを拡張するのではなく、新しいパラダイムを創造すること
• 最新のツールを使って、本当に新しいものを可能にすること

---

アーキテクチャの原則

1. シンプルさを標準とし、複雑さは必要性が証明されてから

シンプルに始め、問題を測定できたときに複雑さを加えます。

最初に使うもの	移行先	移行するタイミング
SQLite	Postgres	同時書き込みが10件を超える、100GBを超える、PostGIS／全文検索が必要
単一ファイル	複数ファイル	ファイルが約500 LOCを超える、または複数の責務を持つ
モノリス	サービス	チームが同じコードベースで作業できない、または規模に応じた分離が本当に必要
静的ホスティング	サーバー	認証、リアルタイム処理、またはサーバー側の計算が必要
ローカル状態	クラウド同期	マルチデバイスが、想定上ではなく実際にユーザーから求められている

**これはドグマではなく、標準的な選択肢です。**変更する場合は、その理由を記録してください。

---

2. フレームワークの選択

本当に効果をもたらす場合にフレームワークを使いましょう。

フレームワーク	使用する場合	避ける場合
Next.js	フルスタックのReactアプリ、SSRが重要、チームが使い慣れている	シンプルな静的サイト、Reactを使わないチーム
Remix	データ中心のアプリ、プログレッシブエンハンスメントを優先	シンプルなSPA、チームに馴染みがない
Astro	コンテンツサイト、部分的なハイドレーションが有効	高度なインタラクティブ性が必要なアプリ
SvelteKit	バンドルの小ささが重要、チームが学ぶ意欲がある	大規模な既存のReactコードベース
Rails/Django	CRUDアプリをすばやく作る、管理画面、実績のあるパターン	リアルタイム処理が中心、チームがJSを好む
FastAPI	Python API、非同期処理が重要	シンプルなスクリプト、チームがほかの言語を好む
Hono/Elysia	エッジ関数、軽量なAPI	フル機能のフレームワークが必要な複雑なアプリ

問うべきなのは「フレームワークを使うかどうか」ではなく、「このフレームワークは作ろうとしているものに役立つのか、それともフレームワークに役立つものを作っているのか」です。

---

3. 人が理解できるシステム

設定

• YAML／JSONで問題ありません。問題はフォーマットではありません
• 問題なのは、条件分岐が入れ子になった500行の設定です
• 良い設定とは、新しいチームメンバーが10分で読み、変更できるものです
• 自明でない設定は、その場で説明してください

学びにつながるエラーメッセージ

• 何が起きたか
• なぜ起きたか
• どうすればよいか
• 内容が複雑な場合はドキュメントへのリンク

理解できるログ

• 機械向けには構造化ログ（JSON）
• 開発向けには人が読める形式
• タイムスタンプ、コンテキスト、重大度
• 専用ツールがなくても検索可能

ドキュメントはコードと一緒に管理する

• 重要な各ディレクトリにREADMEを置く
• APIドキュメントはコードから生成する
• アーキテクチャ上の決定を記録する（ADR）
• 外部Wikiはオンボーディングやプロセスの説明に限って使う

---

4. 重要なところではローカルファーストにする

「クラウドを一切使わない」ではなく、「不必要にクラウドを必須にしない」ということです。

機能	ローカルファーストのアプローチ	クラウドを使う場合
中核機能	オフラインで動作する	中核機能で必須になることはありません
データストレージ	SQLite／ローカルストレージ	同期、バックアップ、マルチデバイス
計算処理	可能な限りクライアント側で実行	大規模な処理、共有リソース
認証	ローカルセッションで動作する	サードパーティ向けOAuth、エンタープライズSSO

状態は調査可能にする

• デバッグ用に状態をファイルへシリアライズする
• 状態マシンは暗黙的ではなく明示的にする
• スナップショットから再現できるようにする

同期は拡張機能として扱う

• 可能な限りローカルを信頼できる唯一の情報源にする
• 同期に失敗してもアプリが壊れないようにする
• 競合解決は明示的にし、ユーザーが制御できるようにする

5. コンポジションの考え方

次の場合はフレームワークよりライブラリを選びます。

• エコシステムではなく、単一の機能が必要な場合
• アーキテクチャを自分で制御したい場合
• 速度よりも離脱コストが重要な場合

次の場合はライブラリよりフレームワークを選びます。

• チームに専門知識がある場合
• 市場投入までの時間が重要な場合
• 設定より規約を重視することに価値がある場合
• フレームワークの設計方針がニーズに合致する場合

API はプリミティブを公開します

• 利便性の高いメソッドを用意しても問題ありません
• ただし、パワーユーザーが低レベルにアクセスできるようにします
• 内部の仕組みを隠さないでください

離脱コストを最小限に抑えます

• データを標準形式でエクスポートできるようにします
• 実用上可能であれば、独自仕様へのロックインを避けます
• 実際には使わないとしても、離脱手順を文書化します

---

クラウドとインフラストラクチャ

クラウドが適している場合

ユースケース	クラウドが適している場合	ローカル／エッジが適している場合
認証	エンタープライズ SSO、OAuth プロバイダー	シンプルなユーザー名／パスワード
ストレージ	複数デバイス間の同期、コラボレーション	単一ユーザー、オフライン対応
コンピューティング	大規模な ML 推論、動画処理	テキスト処理、単純な変換
データベース	複数ライター、グローバル分散	単一ユーザー、ローカルファースト
リアルタイム	複数ユーザーのコラボレーション	単一ユーザーの状態

クラウドを現実的に活用する

• 負荷の変動が激しく予測しにくい場合は サーバーレス
• レイテンシーに敏感な処理には エッジ関数
• 運用のオーバーヘッドがコストを上回る場合は マネージドデータベース
• 制御、コスト、コンプライアンスの要件がある場合は セルフホスト

問い：クラウドはユーザーの役に立っていますか。それとも、実際には存在しない規模についての思い込みを満たしているだけですか？

---

UI／UX の理念

1. 即時のフィードバック

ユーザー操作には 100 ミリ秒未満で応答し、時間のかかる処理では正直に進捗を示します

• 安全にロールバックできる場合は楽観的更新を行います
• 実際の処理を反映した進捗インジケーターを表示します
• スピナーでも問題ありません。処理中であることを正直に示します
• 読み込みパターンが予測できる場合はスケルトンスクリーンを使います

読み込み状態では、次の点を満たす必要があります。

• 何が起きているかを示します
• 可能な場合は所要時間を見積もります
• 時間のかかる処理をキャンセルできるようにします
• 進捗を偽装しません

---

2. 状態の可視化

ユーザーがシステムの動作を常に把握できるようにします

• 詳細を探さなくても状態を確認できるようにします
• バックグラウンドプロセスを見えるようにします
• エラーを隠さず、目立つようにします
• 動作が明らかでない場合、システムが判断の理由を説明します

ブラックボックスを作りません

• ユーザーが何かの発生理由を理解できるようにします
• 重要な操作の監査証跡を残します
• 開発者ツールで状態を確認できるようにします

---

3. 空間的一貫性

配置したものがその場所に留まります

• 読み込み後にレイアウトをずらしません
• 「ユーザーのために」要素を並べ替えません
• 筋肉の記憶が機能します
• コンポーネントの配置に一貫性を持たせます

予測可能なナビゲーション

• 戻るボタンが機能します
• URL をブックマークして共有できます
• 更新後も状態が維持されます
• ディープリンクが機能します

---

4. 元に戻す・復旧する

UI だけでなく、データ層で実装します

• デフォルトで論理削除を使います
• 価値がある場合は状態をバージョン管理します
• 復旧手順を文書化します
• 「本当によろしいですか？」は、元に戻す機能の代わりにはなりません

破壊的な操作

• 元に戻せない操作には確認を求めます
• 完全削除までの猶予期間を設けます
• 結果を明確に伝えます

---

5. 注意を尊重する

通知

• ユーザーが明示的にオプトインします
• エンゲージメント重視ではなく、有意義な通知にします
• 適切な場合はまとめて送ります
• 簡単に調整または無効化できるようにします

モーダルと割り込み

• システム側ではなく、ユーザーが起点となるようにします
• 閉じられるようにします
• 不必要にフォーカスを閉じ込めません
• キーボードで操作できるようにします

自動再生

• 音声では決して自動再生しません
• 動画はユーザーが明示的に再生した場合に限ります
• モーションは prefers-reduced-motion を尊重します

カスタマイズより適切なデフォルト

• 適切なデフォルトで設定項目をなくします
• パワーユーザー向けのオプションを用意しますが、必須にはしません
• 複雑さは段階的に提示します

---

これは何を否定するのか

模倣的な思考

• Y に X が必要かを問わず、「Y 向けの X」を作ること
• 競合が搭載しているという理由で機能を追加すること
• チュートリアルで使われているという理由でパターンを採用すること
• FAANG が採用しているという理由でアーキテクチャを選ぶこと

カーゴ・カルト・エンジニアリング

• 規模の異なる企業の「ベストプラクティス」
• 3 人のチームにマイクロサービスを導入すること
• 単一サーバーの負荷に Kubernetes を使うこと
• 社内ツールに OAuth を使うこと

早すぎる複雑化

• 「将来の柔軟性」のための抽象化レイヤー
• スケール上の問題が起きる前にアーキテクチャをスケールさせる
• 基盤が整う前に機能を追加する
• シングルユーザーで動く前にリアルタイム対応する

思考よりプロセスを優先

• 実際に考えることの代わりになるスクラムのセレモニー
• 明確さのためではなく、コンプライアンスのためのドキュメント
• 会議についての会議
• 予測できるかのように装うロードマップ

---

適用

デザインをレビューするとき

第一原理によるチェック

• これはどんな新しいものを生み出しますか？（「既存の何を拡張するか」ではありません）
• なぜこれが必要なのですか？
• これによって、以前はできなかったどんなことが可能になりますか？

シンプルさのチェック

• 複雑さには根拠がありますか、それとも当然のものとされていますか？
• 新しい開発者が1時間で理解できますか？
• 核心的な問題を解決する、最もシンプルな形は何ですか？

ツール適合性のチェック

• ツールの選択は創造を支えていますか、それとも創造がツールに合わせられていますか？
• チームの専門知識と問題への適合性を踏まえて、フレームワークを選ぶ妥当性がありますか？
• クラウドへの依存は本当に必要ですか、それとも当然のものとされていますか？

人間が読み解けるかのチェック

• 設定を読めば、その内容を理解できますか？
• エラーメッセージは学びにつながりますか？
• ドキュメントは開発者が見つける場所にありますか？

UI/UX のチェック

• フィードバックは即時ですか、それとも段階的な進行であることが正直に伝わりますか？
• システムが何をしているか、ユーザーに見えますか？
• すべて復旧または取り消しができますか？
• 中断はユーザーが開始するものですか？

---

ソリューションを生成するとき

まず、次のことを問いかけます。

1. 私たちは、本当に新しいどんなものを作ろうとしていますか？
2. それを実現する最もシンプルなアーキテクチャは何ですか？
3. 実際の制約によって正当化される複雑さは何ですか？

基本方針：

• 動作する範囲で最もシンプルなツールを選ぶ
• チームが使い慣れていて、適合するならフレームワークを使う
• 可能な限りローカルファーストにする
• 本当に必要な場合にクラウドを使う

次の場合に複雑さを加えます。

• 痛みが理論上のものではなく、測定可能である
• チームがトレードオフに合意している
• シンプルな状態に戻す方法が文書化されている

---

移行のしきい値

デフォルトからアップグレードするタイミング：

移行元	移行先	判断のきっかけ
SQLite	Postgres	同時書き込みが10件超、またはデータ量が100GB超、またはPostGIS／全文検索が必要
モノリス	サービス	チームが同じコードベースで作業できない、またはスケールを実際に分離する必要がある
静的	サーバー	認証、リアルタイム処理、またはサーバーサイド計算が必要
ローカルストレージ	クラウド同期	マルチデバイスが仮定ではなく、ユーザーニーズとして検証されている
ライブラリ	フレームワーク	チームに専門知識があり、かつ市場投入までの時間が重要で、フレームワークの設計思想が合致している
シンプル	複雑	痛みが理論上のものではなく、測定可能である

---

正当化できる例外

次の場合、複雑さは許容されます。

• フレームワーク：チームに専門知識があり、問題がフレームワークの設計思想に合致し、市場投入までの時間が重要である
• クラウドへの依存：複数ユーザーでのコラボレーション、高負荷の計算、またはコンプライアンス上の要件がある
• マイクロサービス：チームがモノリスで連携できない、またはスケールを実際に分離する必要がある
• 重量級のツール：ビルド時間への投資が開発速度の向上につながる

判断の根拠を記録してください。 未来のあなたは、今のあなたに感謝するでしょう。

---

実践的なデフォルト

まずシンプルに始め、痛みが測定可能になったら複雑さを加えます。

1. 動作する可能性のある、最もシンプルなアーキテクチャから始める
2. 想像上の問題ではなく、実際の問題が発生するまで待つ
3. 最適化する前に測定する
4. 複雑さを加える理由を文書化する
5. シンプルな状態に戻す方法を確保する

早すぎる複雑化は、利息が増え続ける技術的負債です。

---

ドグマ化を避ける条項

これらはデフォルトであり、法律ではありません。根拠を記録したうえで、逸脱してください。

ここにある原則はすべて、正当な例外があります。目標は純粋さではなく、意図を持つことです。

逸脱する正当な理由：

• チームの専門知識が、別のアプローチを強く支持している
• ビジネス上のスケジュールにより、より速い道筋が必要
• 規制／コンプライアンス上の要件
• 測定されたパフォーマンス上のニーズ
• ユーザー調査が仮定と矛盾している

逸脱する正当な理由にならないもの：

• 「みんながこのやり方でやっている」
• 「いつか必要になるかもしれない」
• 「チュートリアルでこうしていた」
• 「ベストプラクティスだから」（理由を理解していない場合）

逸脱するときは、その理由を書き留めてください。 コメント、ADR、またはREADMEに一文で記します。

---

クイックリファレンス

項目	デフォルト	切り替えを検討するタイミング
ストレージ	SQLite	同時書き込み、規模の拡大、機能の必要性
フレームワーク	チームが使い慣れているなら採用	よりシンプルならゼロから構築
クラウド	本当に必要な場合に利用	前提にせず、妥当性を検証
設定	YAML/JSONで、十分に文書化	-
エラー	学びにつながるメッセージ	-
読み込み	進捗を正直に示すスピナー	-
状態	見える状態で、確認可能	-
元に戻す	データレイヤーでのバージョン管理	-
複雑さ	前提とせず、必要性を示す	判断理由を文書化

---

核心となる問い

何かを設計するときは、次のように問いかけてください。

「私は何か新しいものを作っているのか、それとも既存のものに論評を加えているのか？」

ルネサンス建築とは、現代のツールを拒絶することではありません。確立されたパターンの単なる別の変形ではなく、本当に新しいものを作るためにツールを使うことです。

中世の学者たちが注釈しか書けなかったのは、真理は過去に明かされたものだと信じていたからです。私たちには、そのような制約はありません。私たちは創造できます。