 本記事は TechHarmony Advent Calendar 2025 12/15付の記事です。 |
こんにちは!
SCSK 品田です。
もうすぐクリスマスということで、アドベントカレンダーのイベントに参加させていただいております。
その他の記事については以下をご覧ください🎁
サンタさんは世界中にいると信じてやまないですが、サンタさんにもプロジェクトマネジメント(PM)は存在するのでしょうか…?
もしPMが存在するのであれば、納期ゼッタイ、納品物は冬くらいにならないとわからない、納品先は世界全体だったりするので、大変なのでしょうか…
では。
本記事の要点と前提条件
要点
・AWSのインフラ構築にはなるべくIac(Infrastructure as Code)を導入する。
・アプリケーション側のソースコードもAIエディタが参照できる場所に配置する。
上記構成を取ることで、VSCode+Amazon Q/Kiro等のAIエディタによる開発が行いやすくなる。
前提条件
・IaC利用ができるプロジェクトであること。
・VSCode+Amazon Q / Kiro等のAIエディタを利用できるプロジェクトであること。
・マークダウン化されている設計書を利用できるプロジェクトであること。
・インフラ側とアプリケーション側でチームが別れている場合、インフラ側とアプリケーション側で綿密にコミュニケーションが取れること。(または、デプロイ状態とソースの状態を確認しやすいこと)
したがって、2025年12月時点では、小規模アプリケーションかつ新規開発の場合が推奨となります。
レポジトリ構成案
IaC+アプリソースを含んだレポジトリ構成案
project-root/ │ ├── documents/ # 設計資料 │ ├── 01_project/ │ │ ├── 01_overview/ # プロジェクト概要 │ │ │ ├── プロジェクト概要.md │ │ │ └── 用語集.md │ │ └── 02_requirements/ # 要件定義 │ │ ├── 機能要件.md │ │ ├── 非機能要件.md │ │ └── ユースケース.md │ │ │ ├── 02_architecture/ # アーキテクチャ │ │ ├── システムアーキテクチャ.md │ │ ├── 技術スタック.md │ │ └── セキュリティ設計.md │ │ │ ├── 03_design/ │ │ ├── 01_infra/ # インフラ設計 │ │ │ ├── インフラ構築図.drawio.svg │ │ │ └── インフラ設計方針.md │ │ │ │ │ └── 02_app/ # アプリ設計 │ │ ├── 機能設計書.md │ │ ├── API設計書.md │ │ └── データモデル.md │ │ │ ├── 04_operation/ # 運用 │ │ ├── デプロイ手順.md │ │ └── トラブルシューティング.md │ │ │ └── 99_misc/ # その他 │ ├── 議事録/ │ └── 参考資料/ │ ├── src/ # 実装ソース │ ├── frontend/ # アプリケーション（Next.js） │ │ ├── app/ │ │ ├── components/ │ │ ├── lib/ │ │ ├── types/ │ │ ├── middleware.ts │ │ ├── auth.ts │ │ ├── Dockerfile │ │ └── package.json │ │ │ ├── infrastructure/ # インフラコード（CDK） │ │ ├── bin/ │ │ ├── lib/ │ │ └── package.json │ │ │ └── utils/ # 共通ライブラリ、あれば │ ├── README.md # プロジェクトREADME └── package.json # ルートpackage.json（モノレポ管理）
レポジトリ構成案のポイント✏️
- documents フォルダには、ウォーターフォールにおける要件定義～設計段階に相当するドキュメントを格納する。
→ 実装段階において必要なインプラントをgit管理・共有しておくため。 - src フォルダには、実装成果物を格納する。src の直下は、アプリケーション側とインフラコードで分ける。
※アプリケーションは今回はNext.jsの例を、IaCは今回はCDKの例を示す。 - Excel等の利用をやめ、成果物はすべてテキスト化(orマークダウン化)しておく。
- プロジェクト的に可能であれば、会議の議事録をテキスト化(orマークダウン化)しておき、設計実装に反映できるようにする。
【オプション】Kiro利用の場合のレポジトリ構成
project-root/
│
├── documents/ # 設計資料 # 上と同じ
├── src/ # 実装ソース # 上と同じ
│
├── .kiro/ # Kiro設定
│ ├── settings/
│ └── specs/
│
└── package.json # ルートpackage.json（モノレポ管理）Kiro利用の場合のレポジトリ構成案のポイント👻
- specsのためのさらにインプットが必要となる場合、documentsフォルダに上位工程の資料として配置しておく。
- specsの単位は事前に検討しておく必要あり。specsファイルが増えるごとに、ファイル内容自体が冗長になってくる/平仄が取れなくなっていくる可能性があるため。
例) インフラで1つ、アプリケーションの共通機能で1つ、アプリケーションの各機能で1つずつ.. 等、事前にspecsファイルの内容が重複しないように切り分けを検討する。
【オプション】モノレポvsマルチレポ構成の検討
本記事はモノレポ構成として例示していますが、実運用上はマルチレポ構成の方がよい場合があります。プロジェクトの規模やGitHub連携の特性を考慮して検討する必要があります。
モノレポとは?
本記事では、アプリケーションのフロントエンド、バックエンド、インフラソース(IaC)すべてを単一のgitプロジェクトで管理することをモノレポと呼ぶこととします。
| モノレポ構成 | マルチレポ構成 | |
| 【単一レポジトリの範囲】 | 設計書、アプリケーションソース、インフラソース(IaC)すべて | 設計書のみ / アプリケーションソースのみ / インフラソース(IaC)のみ |
| GitHub/GitLabの管理上のメリデメ | ・シンプルで管理しやすい。 ・アプリケーション/インフラソースのソース管理責任者を分けにくい。 |
・アプリケーション/インフラソースで、ソース管理責任者を分けやすい。 |
| CI/CD観点の自動デプロイ上のメリデメ | ・Gitコミットをデプロイのトリガーとしている場合、デフォルトではアプリケーション/インフラのトリガーが同一となってしまう。(ため、制御する必要がある。) | ・Gitコミットをデプロイのトリガーとしやすい。 |
本記事のレポジトリ構成を取って開発を行ってみました
メリット例：フロントエンド→API Gateway→Lambda構成におけるCORSエラー対処が容易に
・CORSエラー対処についてはアプリケーション側/インフラ側双方の把握が必要ですが、アプリケーション側/インフラ側双方の情報がレポジトリに集約されているため、解析と対処が容易となります。
→ 次回のインフラ解析時にも、リソースの状態を確認するよりもソースの状態を確認すればよいため、解析が容易となります。
※AWSについては2025年時点ですべての操作をIaC化できるわけではなく、マネジメントコンソール経由で操作したものに関しては別途手作業でドキュメントを生成しておく必要があります。
実プロジェクトで運用してみた所感
小規模アプリケーションの実プロジェクトにて、このような構成を利用してみました。
Gitはモノレポ、フロントエンドはAmplify、インフラはCDKを利用しました。
Good
- 上記メリットの通り、エラー時の解析と対応がらく。
- モノレポのため、新規メンバが参画した場合にはGitクローンを1度行って貰えば成果物はほぼすべて渡せた。
※node.jsやnpm installは別途必要。
No Good
- フロントエンドはAmplify、インフラはCDKで、フロントエンドのデプロイ契機はGitコミットとしていた。CDKソースのみ修正してコミットした場合にもフロントエンドのデプロイが走る設定としていたため、無駄にフロントエンドのデプロイが走っていた。
→ デプロイの設定ファイルまたはGitHub Actions側で設定すべき。 - (構成関係なくIaCの話だが、、、)CDKソースを修正する作業員が2人以上となった瞬間があった。Gitの操作ミスで、環境上のリソースがデグレした瞬間があった。
→インフラテンプレートはなるべく1人の作業が望ましい。が、教育することやCDKデプロイ前にブランチを最新化させる等、Kiroのhooks等で制御できるかもしれない。
総じて快適なので、どんどん取り入れて行きたいです。