4-1. 技術スタックの選定と理由

使用する言語・フレームワーク・DBと、それを選んだ理由を定義する。「なぜこの技術を使うか」まで記録することが重要だ。技術選定の決定理由を残さないと、数ヶ月後・数年後に「なぜこれを使っているのか」がわからなくなり、不必要な技術リプレース議論やリファクタリングが発生する。

層選択肢例選定の論点
フロントエンドNext.js / Nuxt / SvelteKitSSRが必要か、学習コスト、チームの習熟度
バックエンドBFF一体型 / API分離型規模感・チーム構成・将来のスケール
データベースPostgreSQL / Supabase / Firebase運用コスト・スケール・リレーショナルが必要か
認証NextAuth / Supabase Auth / 独自実装セキュリティ・実装コスト・MFAが必要か
ホスティングVercel / Cloudflare Pages / AWSコスト・可用性・チームのクラウド経験

⚠️ 定義しないと…

メンバーが増えたときに「なぜこの技術を使っているか」が伝わらない。理由がわからないまま他の技術に乗り換えようとし、不必要なリプレース議論が起きる。

ℹ️ 選定理由の書き方

「〇〇を選んだ理由：チームの習熟度が高く学習コストを抑えられるため」など、理由を一文で添えるだけでも将来の意思決定の参考になる。

技術選定の記録は「ドキュメント」よりも軽量な形でよい。Confluence・Notion・GitHubのREADMEに次のような形式で残すだけで十分だ。

## 技術選定メモ

### フロントエンド: Next.js 14（App Router）
- 選定理由: チーム全員がReact経験あり。SSRが必要な一部ページがあるためNext.jsを選択。
- 懸念: App RouterはチームがPage Router経験しかないため学習コスト発生。
- 検討した代替: Remix（App Router移行コストと同程度のため不採用）

### データベース: PostgreSQL（Supabase経由）
- 選定理由: RDBが必要。Supabaseを使うことで認証・リアルタイム機能も統合できる。
- 懸念: 無料枠を超えた際の課金が月$25〜（要プロジェクト予算確認）
- 検討した代替: PlanetScale（MySQL系のため一部SQL構文の差異あり。Postgres寄りのため不採用）

4-2. 外部サービス依存の明示

使用するSaaS・外部APIのリストと、それが使えなくなった場合の代替方針を定義する。外部サービスへの依存は「使えて当然」と思われがちだが、料金改定・サービス終了・APIの仕様変更はビジネスの外部要因であり、事前に代替方針を持っておくことがリスク管理の基本だ。

⚠️ 定義しないと…

外部サービスが料金改定・サービス終了した際に影響範囲が把握できない。依存関係を誰も把握していないため、障害時の対応が遅れる。

記載項目内容記載例
サービス名利用するSaaS・API名SendGrid
用途何に使うかトランザクションメール送信（会員登録・パスワードリセット等）
代替方針使えなくなった場合どうするかAWS SES に切り替え（移行コスト: 1週間程度）
コスト無料枠の上限・有料化のトリガー月100通まで無料。超過時は$19.95/月〜

外部サービスへの依存は多くなりがちだ。メール送信・決済・地図・翻訳・認証・ファイルストレージなど、一つひとつは小さくてもまとめるとかなりの数になる。依存リストを一覧化するだけで「このサービスが止まったらどこまで影響するか」が一目でわかるようになる。

4-3. 開発・本番環境の分離方針

ローカル・ステージング・本番環境の構成と、環境変数の管理方法を定義する。環境分離が不十分なプロジェクトでは、開発者が誤って本番データを操作してしまう事故や、APIキーのGitHub流出が頻繁に発生する。これらは技術的なミスというよりも、ルールの不在が原因であることが多い。

⚠️ 定義しないと…

開発中のコードが誤って本番DBに接続し、実データを書き換えてしまう事故が起きる。APIキーや秘密鍵がコードにハードコードされ、GitHubに流出するリスクが生まれる。

✅ 最低限の分離方針

① 環境変数は .env ファイルで管理し .gitignore に追加する。② ローカル・ステージング・本番で別々のDBを使う。③ 本番DBへの直接接続は管理者のみに限定する。

環境ごとの設定管理に使えるツールとパターンを整理しておく。

手法概要向いているシーン
.env ファイル環境ごとに .env.local / .env.staging / .env.production を分けて管理小規模プロジェクト
AWS Secrets Manager / Parameter StoreシークレットをAWSで一元管理。コードへの書き込みをゼロにできるAWSを使うプロジェクト
HashiCorp Vaultオープンソースのシークレット管理ツール。クラウド非依存マルチクラウド・オンプレミス
GitHub Actions SecretsCI/CDパイプライン内でのみ使うシークレットをGitHub側で管理GitHub Actionsを使うプロジェクト

本番環境へのアクセス制限も忘れずに定義したい。「本番DBに直接アクセスできるのは誰か」「本番サーバにSSHできるのは誰か」を明文化しておかないと、本番障害時に「誰がアクセスできるか」を確認する時間が発生し、対応が遅れる。最低限、本番アクセス可能なIAMユーザー・SSH鍵の一覧と、アクセス権付与・剥奪のプロセスを定義しておくとよい。

アーキテクチャ方針でよくある失敗パターン

技術選択の決定そのものより、「決定の記録と共有」の失敗が後工程で大きなコストになる。

失敗パターン何が起きるか防止策
環境間で秘密情報をコードにハードコードする本番DBのパスワードがGitHubに混入し、セキュリティインシデントが発生する.envファイルを.gitignoreに追加し、シークレット管理ツール（Secrets Manager等）を使う
環境構成をドキュメント化しないローカル・ステージング・本番で設定が乖離し、「ローカルは動くのに本番で動かない」問題が頻発する各環境の設定差分を表形式でドキュメントに記録し、onboarding時に共有する
技術選定理由を残さないメンバーが変わるたびに「なぜこの構成なのか」が不明になり、不要な再検討が発生するADRで選択・却下した代替案・理由を記録し、Confluenceやリポジトリに保管する