well-architected

Well-Architected — 出荷前に確認する 6 つの柱

nano 以外の作業に関する ARCH ドキュメントでは、以下の 6 つの柱に関する質問にすべて答える必要があります。 柱を省略できるのは、明示的に理由を示した場合のみです（例： 「サステナビリティ：該当なし — バックエンドのみで、共有インフラ上で実行されるため。」）。

これは AWS Well-Architected（レンズ：小規模チーム向け SaaS／LLM アプリケーション）を参考に、エンジニアが 10 人未満の規模で重要な質問に絞ったものです。

柱 1 — 運用上の優秀性

質問

1. 可観測性： どのようなメトリクス、ログ、トレースを出力しますか？本番環境で動作しているか、ダッシュボードからどのように判断しますか？
2. デプロイ可能性： 変更をどのようにリリースしますか？CI のゲートはありますか？ロールバック手順はありますか？
3. ランブック： 午前 3 時に障害が発生した場合、オンコール担当者は何を読めばよいですか？

合格基準

• ✅ ビジネス上の成果ごとに 1 つのメトリクスがある（例：webhook-deliveries-acked）
• ✅ リクエストごとに 1 行のログがあり、request-id をサービス間で相互に追跡できる
• ✅ デプロイ手順が文書化され、テスト済みである（ロールバックのドライランを実施済み）
• ✅ 事前検討で洗い出した上位 3 つの障害モードをランブックでカバーしている

よくある不合格例

❌ 「監視は後で追加します。」監視も機能の一部です。

柱 2 — セキュリティ

質問

1. 信頼境界： 信頼できないデータはどこから入りますか？どのように検証／サニタイズしますか？
2. 認証／認可： 誰がこれを呼び出せますか？誰がデータを読み書きできますか？
3. シークレット： API キー、DB パスワード、JWT 署名キーはどこに保存されていますか？
4. データ分類： PII ですか？PHI ですか？PCI カード会員データですか？保持ポリシーはどうなっていますか？

合格基準

• ✅ すべての外部入力が、境界で明示的に検証される
• ✅ 認可が UI だけでなく、データ層で強制されている
• ✅ シークレットは環境変数またはシークレットマネージャーに保存され、ソース内には存在しない
• ✅ 機密データが分類され、保持ポリシーが定義されている

よくある不合格例

❌ 「JWT がユーザーを検証するので、これが認可です。」JWT は認証です。認可は別の仕組みです（このユーザーはこの行を読み取れる、という判定）。

柱 3 — 信頼性

質問

1. 障害モード： 下流の依存先が遅い／停止している／破損している場合、どうなりますか？
2. 冪等性： 再試行されたリクエストを安全に再実行できますか？
3. バックアップと復旧： RPO（許容データ損失）はどの程度ですか？RTO（許容ダウンタイム）はどの程度ですか？それぞれのテスト計画はありますか？
4. キャパシティ： このシステムが処理できる最大 QPS はいくつですか？その 1.5 倍になるとどうなりますか？

合格基準

• ✅ 外部呼び出しにサーキットブレーカー／タイムアウトがある
• ✅ 状態を変更するエンドポイントが冪等性キーを受け付ける
• ✅ バックアップが文書化され、直近 90 日以内に復元テストを実施済みである
• ✅ 負荷テストがあり、結果が docs/perf/ に保存されている

よくある不合格例

❌ 「Postgres にバックアップがあります。」テスト済みの復元ができないバックアップは、バックアップとは言えません。

柱 4 — パフォーマンス効率

質問

1. SLO： p50／p95／p99 のレイテンシ目標はいくつですか？エラー率は？可用性は？
2. ボトルネック： クリティカルパスをプロファイリングしてください。最も遅いステップは何ですか？
3. キャッシュ： 何をキャッシュできますか？キャッシュの無効化戦略はどうなっていますか？
4. スケーリング： 垂直スケーリングですか、水平スケーリングですか？自動スケーリングのルールはありますか？

合格基準

• ✅ SLO の数値が ARCH ドキュメントに記載されている（「十分に速い」ではなく）
• ✅ 複雑なリクエストにはプロファイルが添付されている
• ✅ キャッシュ戦略が文書化され、無効化方法が明示されている
• ✅ スケーリングの判断が「適切だと感じる」ではなく、データで裏付けられている

よくある不合格例

❌ 「データベースなら処理できます。」数値で示してください。クエリ数／秒、行数、インデックスヒット率です。

柱 5 — コスト最適化

質問

1. ホットパス： リクエストごとに最もコストのかかる処理は何ですか？その理由は何ですか？
2. 適正なサイジング： 選択したインスタンスタイプ／モデル／DB ティアは、SLO を満たす最小のものですか？
3. クリーンアップ： 古いデータはどうなりますか？古いログは？古いブランチ環境は？

合格基準

• ✅ スキル cost-model を使って、具体的な金額（$）を文書化する
• ✅ 品質 SLO を満たす最小の LLM モデルを選ぶ（sonnet より先に haiku、opus より先に sonnet）
• ✅ ログ、メトリクス、古いデータに対する保持ポリシーがある

よくある不合格例

❌ Haiku で十分なのに、デフォルトで Opus／GPT-4 を選ぶこと。まず Haiku でテストしてください。

柱 6 — サステナビリティ（環境／エネルギー）

質問

1. ワークロード効率： O(n)で済む処理が、O(n log n)になっていませんか？
2. アイドル状態のリソース： 開発環境を夜間にゼロまでスケールできますか？
3. データ最小化： 一度もクエリしないデータを収集・保存していませんか？

合格基準

• ✅ ホットループの計算量が文書化されている
• ✅ 本番以外のリソースにシャットダウンスケジュールが設定されている
• ✅ データのライフサイクルで、取り込み、保持、削除がカバーされている

よくある不合格例

❌ 本番環境でログがデバッグレベルのまま放置され、確認されていません。ストレージと炭素を無駄に消費します。

出力形式 — ARCH に追加

## Well-Architected review

### 1. Operational excellence
- Metrics: <list>
- Deploy path: <link to runbook>
- Verdict: PASS | RISKS LISTED

### 2. Security
- Trust boundaries: <list>
- Data classification: <PII / PHI / PCI / none>
- Verdict: PASS | RISKS LISTED

### 3. Reliability
- Failure modes: <link to pre-mortem>
- Idempotency: <yes/no per endpoint>
- Verdict: PASS | RISKS LISTED

### 4. Performance
- SLOs: p99=<ms>, error_rate=<%>, availability=<%>
- Verdict: PASS | RISKS LISTED

### 5. Cost
- Per-request cost: $<amount>
- Verdict: PASS | RISKS LISTED

### 6. Sustainability
- Hot-path complexity: O(<n>)
- Verdict: PASS | N/A | RISKS LISTED

## Open risks (rolled up)

<bullet list of all RISKS LISTED items + mitigation in plan>

リスクを明記したうえで PASS が許容される場合

すべてのアーキテクチャが万全とは限りません。次の条件を満たすなら、リスク付きの PASS でも問題ありません。

• 各リスクが明示されている（曖昧にごまかされていない）
• 各リスクについて、計画に緩和策が盛り込まれている、またはユーザーが明示的に受容している
• 事前検証のセクションで、リスクスコア上位 3 項目に対応している

ゲート：plan ではリスク付きの PASS を承認できます。ゲート：ship では、緩和策をリリースする必要があります。