ChatGPT と 5 ラウンドの設計レビュー — 設計書を v1 から v4 まで磨いた話
構築を始める前に、まず 設計書を作ってからコードを書く 方針を取りました。AWS サーバレスは最初の構成判断が運用コストにそのまま跳ね返るので、雑に始めると後悔します。
ただし設計書を 1 人で書くと自己満で終わりがちです。そこで ChatGPT (gpt-4o) を相互レビュアーに使い、5 ラウンドの設計レビュー を回しました。本記事はその記録です。
レビューに使ったツール
ChatGPT との往復は、自前の CLI ツール consult_chatgpt.py を使いました。会話履歴を JSON で保存できて、複数ラウンドの設計議論を引き継げます。
# 単発相談
chatgpt --prompt "AWS サーバレスポートフォリオの設計書をレビューして"
# ファイル渡し + 履歴引き継ぎ
chatgpt --file design-v1.md --conversation iigtn_design --save-to round1.md
chatgpt --prompt "1 番目の指摘を具体化して" --conversation iigtn_design --save-to round2.md
これで「設計書 v1 を渡す → R1 レビュー → 反映 → v2 → R2 レビュー → …」のループが回ります。
5 ラウンドの全体像
結論から言うと、設計書はこのレビューを通じて次のように磨き込まれました:
| ラウンド | バージョン | テーマ |
|---|---|---|
| R1 | v1 → v2 | 運用視点の追加 |
| R2 | v2 → v3 | 文書役割の分離と事実訂正 |
| R3 | v3 → v4 | 実運用データの計測と過剰主張の訂正 |
| R4 | v4 で合意 | ポートフォリオとして十分と判定 |
| R5 | 実装後の確認 | 実装を踏まえた最終チェック |
R1 (v1 → v2) — 運用視点の追加
v1 は「9 つの章で AWS サービスごとの採用理由を書いた仕様書」でした。技術的には正確ですが、ChatGPT の最初の指摘はこうでした:
これを受けて v2 で追加したのは:
- 運用証拠の確認方法章: CloudFront 配信確認 / CloudWatch ログ / DynamoDB / GitHub Actions ログ をどう確認するかの手順
- Runbook: よくあるトラブル 12 件の対応手順 + 障害発生時の調査順序
- コスト設計: 月額試算 + トラフィック増加時のコスト変動 + 最適化策
- 採用しなかった選択肢: Amplify / Vercel / ECS / EC2 をなぜ採用しなかったか
- ビジネス応用: クライアント案件への展開構想
R2 (v2 → v3) — 文書役割の分離と事実訂正
v2 は内容が分厚くなりすぎて、1 つのファイルで「技術ドキュメント / 営業資料 / 面接対策 / キャリア戦略」が混在する状態に。R2 で次の指摘:
- README として読むとノイズ過多
CloudFront Invalidation は requests 単位という記述が誤り（正しくは paths 単位）- Lambda / API Gateway を「0 円」と書いているが、CloudWatch Logs の取込課金で実際は月数十円〜
- SES コストを固定額表記しているが、送信数で変動
- WAF 動的 ON/OFF やマルチリージョンの構想が「盛りすぎ」感を醸す
v3 では 1 つの大きなファイルを 7 ファイルに分割 しました:
| ファイル | 役割 |
|---|---|
README.md | 技術概要・構成・採用理由 |
motivation.md | 動機・思想・ストーリー |
cost.md | コスト試算（事実訂正版） |
runbook.md | 障害対応 + 実障害ログ |
lessons.md | 失敗・反省・悩み |
business.md | クライアント展開構想 |
interview.md | 面接 Q&A |
R3 (v3 → v4) — 実運用データの計測と過剰主張の訂正
v3 はファイル分離で読みやすくなりましたが、もう一段、レビューで突っ込まれました:
- 実運用データ（p95 / Hit 率 / Lambda Duration / アラート発火履歴）の計測項目が定義されていない
- コスト・可用性の数値に、前提条件や計測方法の裏付けが弱い箇所がある
- 「OS / プラグイン脆弱性が原理的に存在しない」は断定が強すぎる（Lambda ランタイム・Node・npm 依存・OSS の脆弱性は当然存在する）
v4 では:
- 新規 metrics.md: 実運用メトリクスの計測項目と取得元、月次レポート Template
- 各数値に前提を明記: コスト試算・可用性の根拠（トラフィック前提・計測方法）を各章に追記
- 「セキュリティ」断定の撤回: 脆弱性は存在する旨と、依存パッケージ・ランタイムのパッチ管理方針を明記
R4 (v4 で合意)
R4 のレビューで、ChatGPT は 「合意」 と判定しました:
4 ラウンドのレビューで、設計書は 「優秀なテンプレ」から「この人だから作れた設計書」 へと変わったと言えるレベルになりました。
R5 (実装後の確認)
実装が一段落した時点で、もう 1 ラウンド、ChatGPT に「これで本当に十分か」を確認しました。これも合意。設計フェーズはここで終了し、実装フェーズに入りました。
レビューで一番効いた指摘
5 ラウンドを通じて、一番効いたフィードバックは:
つまり、「全部問題なく動く」と書くより、数値の前提・採用しなかった選択肢・残課題を明示するほうが、技術ドキュメントとしての説得力が増す。これは技術ブログの書き方にも共通する気づきでした。
このレビューを 1 人でやろうとしていたら
もし ChatGPT を使わずに 1 人で書いていたら、おそらく v2 か v3 で止まっていたと思います。「もう完成」と思った瞬間に外部から客観的に突っ込まれることで、初めて気付ける欠落がある。これは 技術ブログ・ポートフォリオを作るすべての人にお勧めできる方法 です。
次の記事
設計書ができたところで、いよいよ実装に入ります。次の記事では AWS のマルチアカウント運用 (dev / prod) と、Terraform を回す前提となる IAM の初期設定について書きます。
📚 用語集
- 設計書 (Design Doc)
- システム構築前に「何を・どう作るか」を文書化したもの。AWS 構築の場合は採用サービス・配置・通信経路・コスト・運用までカバーする。
- Runbook
- 障害時にどう対処するかを事前に文書化した手順書。「症状 → 原因の典型 → 対応」のテーブル形式が多い。
- Postmortem (ポストモーテム)
- 障害が起きた後に、「何が起きたか / なぜ起きたか / どう対応したか / 再発防止」を記録する文書。実運用してる会社の証拠。
- Core Web Vitals
- Google が定義したサイトのユーザー体験メトリクス。LCP（読込）/ INP（操作応答）/ CLS（レイアウト安定）の 3 指標。
- p95 / p99
- パーセンタイル統計。p95 = 全リクエストの 95% 以下のレイテンシ、p99 = 99% 以下。「最悪値ではなく、ほぼ全員の体感値」を示す。
- WAF (Web Application Firewall)
- Web アプリへの攻撃（SQLi / XSS / Bot 等）を遮断するファイアウォール。AWS WAF は CloudFront にアタッチして使う。
- Amplify
- AWS の Web アプリ向けマネージドホスティング。内部で CloudFront + S3 + Lambda を使うが、抽象化が強くインフラ層がブラックボックス化する。本シリーズでは「不採用」の選択肢として位置付け。
- Vercel
- Next.js を最適に動かす PaaS。本シリーズでは「AWS 設計力を可視化する目的と矛盾」のため不採用。
- ECS / Fargate
- AWS のコンテナ実行サービス。常駐型ワークロード向けで、フォーム程度の用途には過剰のため本シリーズでは不採用。
- テンプレ感
- 「教科書的に書かれていて個人の意思や経験が見えない」状態。設計書では避けたい印象。
- OSS の脆弱性
- Open Source Software に発見される脆弱性。Lambda ランタイム・Node.js・npm パッケージ・利用 OSS は定期的にセキュリティパッチ管理が必要。
- SCA / SAST
- SCA = Software Composition Analysis（依存ライブラリの脆弱性スキャン）。SAST = Static Application Security Testing（コード静的解析）。