はじめに
GMOコネクトの永田です。
「数年前に組まれた既存 DEV 環境を、別の AWS アカウントに丸ごと再現してほしい。CFn template はあるがメンテされておらず当時のメンバーは離任＋手動構築も多々ある、ビルド・構築手順書は無い。動作している環境を read-only で覗くことはできる。」
(スタックの内訳は Aurora + ECS Fargate + ALB + CloudFront + WAF + Route53 + S3 + Java 系アプリ、というよくある web アプリ構成)
今動いている環境が神であり壊れたらお終いという、現場でわりとよく出くわす案件パターンだと思います。（よくあって欲しくはないパターンですが😇）
IaC でゼロから組む系の記事は世に溢れていますが、「ドキュメントが失われた既存環境を、暗黙知ごと別アカウントへ移植する」 ほうは、普通に人手でやると暗黙知の棚卸しと debug で 数週間 は溶けます。今回それを Claude Opus 4.7 主導で 1 日で完走 できたので、その記録です。
軸は 前回の記事 で確立した engineer to delegate to スタイル (Anthropic 公式解説) と同じです。今回はそれを、インフラ + アプリ + IdP + DB を縦断する applied infra 領域に適用しました。副産物として、debug と並行して構築手順書も同時に出来上がり、「次に新規アカウントで作るときは、もう 1 日もかからない」状態が残っています。
先にまとめ
普通に人手でやると 数週間 → Claude 駆動で 1 日 (内部結合疎通スコープ、検証含む) で完走。
- Claude による IaC ベースの自動構築 + E2E 疎通確認まで完走
- debug の過程で発覚した暗黙知はすべて その場で構築手順書 (5 文書構成) に反映 → 次回の新規アカウント構築では同じ穴を踏まない
軸は前回と同じく engineer to delegate to。ただし今回は applied infra + ドキュメント陳腐化 が対象なので、人が事前に整えた 4 つの環境設計を再掲します。
| # | ポイント | これをやらないと | 効いた場面 |
|---|---|---|---|
| 1 | Acceptance criteria を E2E round-trip で握る | 「ALB 200 だけ」で OK 判定し、後続の IdP (ID Provider) 認証や DB write で死ぬ | Done を「E2E ステップ全 200」と握っただけで、Claude が途中の 404/401/500 を自律で潰しに行く |
| 2 | Constraints (作業ルール) に「本番無干渉」「secret は commit 前に人確認」を明文化 | source 環境 (本番系 DEV) への意図しない書き込み、git 履歴への secret 混入 | source 環境は read-only 参照のみ、IdP の client_secret/DB password の新規 commit はすべて人が承認 |
| 3 | CLI 直叩き環境 (AWS CLI multi-account / IdP CLI / Aurora Data API / Playwright) を整える | 「Claude 出力 → 人が実行 → 結果を貼る」の往復で人が呼び戻され続ける | AWS profile を source/target 両方に切り、Claude が aws --profile target ... と aws --profile source ... を自分で使い分け |
| 4 | 試行錯誤を都度ドキュメントへ昇華するルール | 1 回目だけ通って 2 回目 (別アカウント) は再現できない | debug session の解消ごとにリポジトリ内の構築手順書を更新、最終的に 5 文書構造に再編 |
この 4 つが揃った瞬間、「次は何のリソースを作るんだっけ → コマンド打って → 出力を Claude に貼って → 解析させて」のループが消え、Goal を渡して別の作業をしながら待つ スタイルに変わりました。
第1部: 設計編 ─ なぜ「ドキュメントが失われた環境の移植」は普通にやると重いのか
IaC ゼロ構築なら「最新の AWS ベストプラクティス + 想定要件」だけ握れば組めますが、移植 はそうはいきません。「いま動いているもの」を別アカウントで再現する必要があるため、source 環境に染み込んだ暗黙知をすべて洗い出さないと完了しないのが本質です。普通にやると重い理由を分解すると:
- CFn template が古い / 手動構築リソースが混ざっている ─ template の parameter が当時のままで別アカウントで使う値が分からない、DEV と PRD の差分も誰も把握していない。さらに「template には載っていない手動構築リソース」も別途存在し、template だけ deploy しても足りない
-
DDL は repo にあっても運用パッチ + 初期マスターデータが抜けている ─ production hotfix の
ALTER TABLEが DDL 系に反映されていない、加えて サービスが起動するために必要な初期マスターデータ も SEED 化されておらず、空の DB ではアプリが動かない - 認証基盤 (IdP) realm が手動構築 ─ realm export が repo に無いと、別アカウントで管理 API が突然 401 になる
- アプリが起動時に S3 から読み込むファイルが repo に無い ─ 一部 file 欠落で、起動はするが特定機能だけ 500
- アプリ properties に環境固有値がハードコード ─ 別アカウントで起動すると旧 URL/旧 ARN を読みに行って即死
これら 1 つ 1 つは個別 debug すれば解けますが、「全部出揃うまで E2E が通らない」 ので、人手で 1 個ずつ潰すと数週間溶けます。Claude 主導でやったのは、「source 環境は read-only で覗いて良い、target 環境への構築手順書では source 環境への依存を最終的にゼロにする」というルールでの 暗黙知棚卸しの一括委譲 でした。
1.1 暗黙知の具体例と、Claude が掘り当てた修正
冒頭で挙げた暗黙知は、いずれも E2E ステップが進行中に 特定 API だけが 4xx/5xx を返す形で初めて顕在化します。今回の構築で詰まったものを、Claude が掘り当てた修正とセットでまとめます (個別 debug 記事ではないので要点のみ)。
| 暗黙知 | 詰まり方 | Claude が掘り当てた修正 |
|---|---|---|
| CFn template に載らない手動構築リソース | stack 投入直後に「resource not found」で連鎖失敗 | 手動構築分を Step 1 として手順書化 |
| DDL/SEED の運用パッチ抜け + 初期マスターデータ未投入 | アプリは起動するが、API 呼び出しで NPE / FK 違反 / Service 層の post-filter で空 list → 500 | DDL に追記 + 該当 SEED を INSERT |
| 認証基盤 (IdP) realm の手動設定 | realm import しても管理 API が 401 (master realm との取り違えで連鎖) | アプリ realm に管理 user + realm-management:realm-admin 付与 + ECS env で override |
| 環境固有値 / credential のハードコード | URL / DB ARN / IdP credential が source 環境向けのまま残存、change_pass が DB mirror 未 populate で 404 等の派生も |
プレースホルダ化 + ECS env 注入、password reset を E2E ステップに組込み |
| アプリ起動時の S3 ファイル欠落 + OSS ライブラリ default 変更 | 特定機能だけ S3 NoSuchKey で 500、Lombok upgrade で Jackson の setter 解決が壊れ admin login が 500 |
S3 contents を repo 同梱 + sync を Step 化、lombok.config 1 行で旧 default 復元 |
中でも 認証基盤 realm の取り違え は症状 (管理 API 401) と真因 (master realm vs アプリ realm) の距離が遠く、Claude が ECS exec → IdP CLI で realm 内 user 一覧を取りながら 自己診断 → 修正までを 1 セッション内で完走したのが象徴的でした。これら 1 件 1 件を人が追うと数日仕事ですが、複数連鎖した状態を 1 日で潰しきれたのが今回の肝です。
第2部: 委譲スタイルを applied infra に拡張する
前回記事で確立した Goal / Constraints / Acceptance criteria の渡し方を、今回はインフラ + アプリ + DB + IdP の縦断作業に適用しました。
2.1 Goal を E2E round-trip で握る
ALB から 200 が返るだけでは Done とは言えません。今回 Acceptance criteria に組んだのは、ユーザー操作起点の round-trip が完走すること です。
Step 1: POST /api/admin/login → 200 (access_token 取得)
Step 2: POST /api/admin/users/reset-password → 200 (user の password 設定)
Step 3: POST /api/users/login → 200 (user で login)
Step 4: POST /api/users/me/password → 200 (新 password 設定)
Step 5: POST /api/users/login (新 password) → 200 (再 login 成功)
これは 認証系の土台 5 step ですが、実際にはこの上にアプリ固有の業務 API E2E (一覧取得 / 詳細取得 / フォーム送信 / 集計レポート描画 等) も Claude にひと通り流させ、admin 画面の全画面 navigate と業務ワークフロー 1 周まで Done に含めています。記事中の例示は分かりやすさのため認証系に絞っていますが、Acceptance criteria の実態は「土台 + 業務系の E2E まで全 200」でした。
全 200 を引いただけで、Claude は各ステップの 4xx/5xx を自分で解析しに行きます。Step 4 で 404 が出れば IdP password の管理経路を遡り、Step 2 で 400 が出れば JSON schema を取りに行く ─ という具合に、Done の粒度が debug の起点を自動で生んでくれます。
2.2 Constraints は「本番無干渉」と「secret 確認」を最初に明文化
| ルール | 効いた場面 |
|---|---|
| source 環境 (本番系 DEV) は read-only | source の DB に test data を書き込みかける誘惑を即遮断 |
| 新規 secret の commit は人承認 | IdP の client_secret や DB password の git 履歴混入を防止 |
| 同パターン全件検索 (前回も使ったルール) | 1 箇所修正したら同種の問題箇所を Claude が自動で grep |
| Java ソース修正はインフラ担当からは直接行わない | アプリチームへの handoff 票を作る方向に倒す |
2.3 CLI 直叩き + multi-account profile
Claude が AWS CLI を 複数アカウント分 直接叩ける状態を最初に作りました。具体的には:
-
aws --profile source ...(調査用、source 環境 = 既存 prod-like) -
aws --profile target ...(構築側、target 環境 = 新規アカウント) -
IdP CLIを ECS exec 経由で IdP コンテナ内で実行 - Aurora Data API による DDL/SEED 投入 (psql クライアント不要)
- Playwright + playwright-chromium で E2E での動作検証
ECS exec → IdP コンテナ → IdP CLI の経路は特に効きました。realm 内に admin user を作って role を付与し、ECS task definition の環境変数で値を override し、新しい revision で起動 ─ という一連が、人の介入なしに 1 セッション内で回ります。
なお、source/target の AWS account を 1 シェルから安全に並行操作するための aws login dual session 構成は別章でコラムとしてまとめます (第2部のあとに置きました)。
2.4 試行錯誤をその場でドキュメントへ昇華
これが今回いちばん効いた工夫です。debug session が解消するたびに、解消した内容をリポジトリ内の構築手順書に「再現可能な手順」として書き戻す ことを Claude のルーチンに入れました。
「次回新規アカウントで同じ穴を踏まないか」を session 終了ごとに確認させ、踏まないために必要な追加コミット (例: 認証基盤の設定 export を repo に同梱、欠落していた S3 file を repo に追加) を都度生成します。最終的にできあがった構築手順書は、次回別アカウントで同じ環境を 1 から再構築できる粒度 にまとめ直し、source 環境への依存はゼロになりました。
コラム: aws login で 2 account を 12 時間並行保持する
「source / target を両方触る」状況で意外に効いたのが、AWS の新しい aws login コマンド を使った dual session 構成です。SSO の sso-session 共有は世に記事が多いのですが、IAM user 直接認証経路 (login_session = arn:aws:iam::<account>:user/<iam_user>) で複数 profile を並行保持する構成 は記事化が少なかったので、今回の構成を残しておきます。
~/.aws/config に追記するだけ:
[profile source]
login_session = arn:aws:iam::<source_account_id>:user/<source_iam_user>
region = ap-northeast-1
[profile target]
login_session = arn:aws:iam::<target_account_id>:user/<target_iam_user>
region = ap-northeast-1
それぞれ 1 度ずつ aws login --profile <name> を叩けば、profile ごとに独立した credential cache が確立されます (long-term access key は不要)。1 回の login で 最大 12 時間 (15 分ごとに自動ローテーション) 並行有効、片方を login したからもう片方が無効化される、ということも起きません。
aws login --profile source # ブラウザで承認
aws login --profile target # ブラウザで承認 (別 account 用)
# 以降 12 時間は再 login 不要、--profile 明示で切替自在
for p in source target; do
aws --profile $p sts get-caller-identity --query Account --output text
done
# → <source_account_id>
# → <target_account_id>
Claude Code に委譲するとき特有のハマりが 1 つあって、AWS_PROFILE env で切り替えると同一セッション内で source/target を行き来したときに env 状態の追跡が混乱しやすい です。--profile を毎回明示するルールを Constraints に入れておくと、Claude が source/target を取り違える事故が起きにくくなります。
第3部: アウトプットが「次回の構築手順書」になる
ここが今回の記事でいちばん伝えたい部分です。debug が終わるたびに「再現可能な手順」へ書き戻すサイクルを回すと、最終的に 構築手順書そのものが debug の成果物として残る 形になります。
3.1 debug を即手順化するサイクル
特別な仕掛けがあるわけではなく、Constraints (作業ルール) の goals に 「次回新規アカウントで 1 から再構築できるレベルの構築手順書を Markdown で repo に整備すること」 を 1 行入れておくだけです。これさえ握っておけば、Claude は debug session が解消するたびに自発的に:
- この問題は次回の新規アカウント構築で再現するか?
- 再現するなら、何を repo にコミットしておけば踏まないようにできるか?
- 該当する手順書のセクションはどこか? 無ければ新設すべきか?
を自問自答し、必要な手順書更新と repo コミットを生成します。人がいちいち振らなくて良い のがポイントで、Constraints 1 行で運用が回ります。
3.2 副産物として repo に揃う「足りない物資」
このサイクルを回していると、source 環境への参照を手順書から消すために必要な物資が、debug の副産物として一通り repo に揃っていきます。典型例:
- source 環境から取得した config (認証基盤 realm の partial export 等)
- 起動時に読み込まれるが repo に欠落していた S3 contents
- DDL の運用パッチ差分、初期マスターデータの SEED
- ECS task definition env で注入すべき credential の一覧 (値は別管理)
source 環境への調査用アクセスは引き続き行って OK ですが、手順書本体には source 環境への参照を残さない という線引きが効きます。「source を読まないと再構築できない」状態と「source を読まなくても再構築できる」状態の間には大きな差があり、後者に持っていけるかは記事の主題でもあります。
3.3 最終的にどこまで整備できたか
ゴールはシンプルで、「次回別アカウントで同じ環境を組むときに、これだけ読めば 1 から組み直せる」 粒度です。debug で踏んだ落とし穴はすべて手順側に昇華されているので、「手順通り進めれば発生しないハマり」は本体の手順書からは消えています。途中の試行錯誤の生ログは archive ディレクトリに退避させ、本体は 結論ファースト で読めるよう再編しました。
社内では 2 人目以降の構築担当者 (人 / Claude いずれも) を想定して整備しており、source 環境への参照は手順書本体からはすべて除去済みです。
まとめ
Before / After
工数と体験を 1 つの表で並べておきます (Before = 逐次指示型 / After = 委譲型)。
| 観点 | Before | After |
|---|---|---|
| source 環境の暗黙知棚卸し | 数日、人が source を覗いて台帳に書き写す | 半日、Claude が source/target を自分で diff |
| 基盤 CFn 投入 | 数日 | 半日、DEV/PRD param diff 表を先に握る |
| DDL/SEED + 認証基盤 realm import | 数日 | 半日、Aurora Data API + IdP CLI を Claude が自走 |
| E2E debug | 数週間、人がログを Claude に転送して解析依頼 | 数時間、Claude が ECS exec / IdP CLI を自分で叩いて検出→修正→再検証まで自走 |
| 構築手順書の整備 | debug 後の別工程、後回しになりがち | debug と同時に完了、Constraints 1 行で運用 |
| マルチアカウント切替 | 人が --profile を意識して組み立て |
Claude が source/target を自分で切替 (誤爆防止ルール込み) |
| 合計 (内部結合疎通スコープ) | 数週間 | 1 日 |
注: 同じスコープ (内部結合疎通) で揃えました。本番投入レベルの監視/CI-CD 整備や、source 環境との設定 100% 一致を求めるなら追加工数が必要です。
体験として大きかったのは 「debug がそのまま手順書を兼ねるようになった」 ことです。逐次指示型では「動いたから OK」で終わって属人化していた知見が、Constraints 1 行を握っておくだけで永続的な成果物として残ります。次に新規アカウントで同じ環境を作るときは、もう 1 日もかからない 状態が成果物として残りました。
前回 の「メジャーアップは大変、を過去のものにする」に続いて、今回は 「ドキュメントが失われた環境の移植は属人化案件、を過去のものにする」 話として、Opus 4.7 の applied infra への応用事例を書き残しておきます。
最後に、GMOコネクトではサービス開発支援や技術支援をはじめ、幅広い支援を行っておりますので、何かありましたらお気軽にお問合せください。