Codex × CloudFormation で既存AWS環境をIaC化した話〜handover文書でコンテキストを外出しし、AIエージェントを使いこなす戦略〜

Last updated at 2026-04-01Posted at 2026-04-01

はじめに

本記事では、既存のAWS環境をCloudFormationでIaC化した際に活用した
handover文書戦略についてご紹介します。

この記事で得られること

CodexなどのAIコーディングエージェントを使ったIaC化の進め方
セッションをまたいでもコンテキストを失わないhandover文書の設計方法
AIへの指示をシンプルに保つ、シーン別プロンプトテンプレート

想定読者

AWSをコンソールで管理しており、そろそろIaC化したいと思っている方
CodexなどのAIエージェントを実務に活用したいと思っている方
AIへの指示コストを下げる仕組みづくりに興味がある方

使用技術

項目	内容
IaCツール	AWS CloudFormation
AIエージェント	OpenAI Codex
ドキュメント管理	Markdown

背景・課題

AWS環境の管理状況

複数のAWSリソースをコンソールのぽちぽち操作で構築・管理していた
構成がコードとして残っておらず、何がどこにあるか把握しづらい状態だった
「同じ環境をもう一度作れるか？」と聞かれたら自信を持って答えられない状況

IaC化に踏み切った理由

環境の再現性を高めたい
変更履歴をコードで管理したい
インフラの属人化を解消したい

AIエージェントを使ってみたが…

Codexを使ってIaC化を進めようとしたところ、すぐに壁にぶつかりました。

セッションをまたぐとコンテキストがリセットされる
- 「前回どこまで進めたっけ？」を毎回説明する必要があった
毎回同じ前置きを書くのが手間
- プロジェクトの概要・方針・現在の状態を毎回説明するのは非効率
作業の全体像をAIが把握できていない
- ロードマップや優先順位を共有できていないため、的外れな提案が来ることがあった
判断の経緯が追えない
- 「なぜこの構成にしたのか」という判断理由が残っておらず、後から振り返れない

課題の整理

課題	具体的な問題
コンテキストの揮発	セッションをまたぐと状況説明をゼロからやり直し
指示コストの高さ	毎回長いプロンプトを書く必要がある
全体像の欠如	AIがロードマップや優先順位を把握できていない
判断経緯の消失	なぜその構成にしたかが後から追えない

これらの課題を解決するために考えたのが、handover文書でコンテキストを外出しするという戦略です。

解決アプローチ概要

基本的な考え方

コンテキストをコードと同じ場所に置く

AIエージェントが作業するたびに、プロジェクトの状態・判断理由・次のタスクを
Markdownファイルとして記録・更新していきます。
次のセッション開始時にそのファイルを渡すだけで、AIがすぐに状況を把握できる状態を目指しました。

handover文書群の概要

プロジェクト直下に以下のファイルを用意しました。

cloudformation/
  ├── ONBOARDING.md        # 人向けの入口
  ├── CONTEXT.md           # AI・新規セッション向けの入口
  ├── CURRENT_STATE.md     # 今の状態とblockerの要約
  ├── TASKS.md             # 次にやることと依存関係
  ├── DECISIONS.md         # 方針と判断理由の記録
  ├── DEPLOYMENT_RUNBOOK.md# Stack実行と運用手順の正本
  └── HISTORY.md           # 日付別の詳細な作業履歴

人向けとAI向けで入口を分ける

このアプローチの核心は、入口を用途別に分けたことです。

入口	対象	役割
`ONBOARDING.md`	👤 人間	ローカルセットアップ・読む順番を案内
`CONTEXT.md`	🤖 AIエージェント	プロジェクト概要・AIへの指示方針を集約

課題とアプローチの対応

課題	解決するファイル
コンテキストの揮発	`CONTEXT.md` + `CURRENT_STATE.md`
指示コストの高さ	`CONTEXT.md` を入口にしたシーン別テンプレート
全体像の欠如	`TASKS.md` で優先順位・依存関係を管理
判断経緯の消失	`DECISIONS.md` に方針と理由を蓄積

Before / After

Before：毎回ゼロから説明

プロジェクトの概要を書く
現在の状態を書く
今日やりたいことを書く
…これを毎回繰り返す😓

After：ファイルを渡すだけ

CONTEXT.md を渡す
今日やりたいことだけ一言添える
それだけでCodexが動き始める🎉

handover文書の設計思想

設計の3原則

短く保つ：各ファイルは役割を1つに絞り、情報を詰め込みすぎない
更新しやすくする：セッション終了時にCodexが自動で更新できる粒度にする
入口を明確にする：どこから読めばいいかで迷わせない

各ファイルの役割詳解

ONBOARDING.md

対象：初めてプロジェクトに触れる人間
役割：ローカルセットアップ手順と、各ファイルの読む順番を案内する唯一の入口
更新タイミング：初回構築時・構成変更時

# ONBOARDING

## このプロジェクトについて
既存AWS環境をCloudFormationでIaC化するプロジェクトです。

## 読む順番
1. CONTEXT.md           → プロジェクト全体像を把握
2. CURRENT_STATE.md     → 今どこにいるかを把握
3. TASKS.md             → 次に何をするかを確認
4. DECISIONS.md         → なぜそうするかを理解
5. DEPLOYMENT_RUNBOOK.md→ 実行手順を確認

## ローカルセットアップ
- AWS CLI のプロファイル設定: `aws configure --profile myproject`
- 作業ディレクトリ: `cloudformation/`

CONTEXT.md

対象：AIエージェント・新規セッション
役割：プロジェクト概要とAIへの行動指針を集約したAI向けの入口
更新タイミング：プロジェクト方針の変更時

# CONTEXT

## プロジェクト概要
既存AWS環境をCloudFormationでIaC化するプロジェクト。
対象リソース: VPC / EC2 / RDS / ALB / S3

## AIエージェントへの指示
- 作業前に CURRENT_STATE.md で現状を確認すること
- 判断に迷ったら DECISIONS.md を参照すること
- 作業後は CURRENT_STATE.md / TASKS.md / HISTORY.md を更新すること

## ディレクトリ構成
cloudformation/
  ├── templates/   # CloudFormationテンプレート
  └── *.md         # handover文書群

CURRENT_STATE.md

対象：AIエージェント・人間
役割：今の状態とblockerを短く把握するための要約
更新タイミング：毎セッション終了時

# CURRENT_STATE
最終更新: 2025-06-01

## 完了済みリソース
- VPC / Subnet / IGW ✅
- SecurityGroup ✅

## 作業中
- EC2 (web-server-01) 🔄

## 未着手
- RDS / ALB / S3

## Blocker
- RDSのパラメータグループ名が不明 → 担当者に確認中

TASKS.md

対象：AIエージェント・人間
役割：次にやることと依存関係を管理
更新タイミング：毎セッション終了時

# TASKS

## 進行中
- [ ] EC2テンプレート完成 (#3)

## 次のタスク（依存関係あり）
- [ ] RDSテンプレート作成 (#4) ※ #3完了後
- [ ] ALB設定 (#5)             ※ #4完了後

## 完了済み
- [x] VPCテンプレート作成 (#1)
- [x] SecurityGroupテンプレート作成 (#2)

DECISIONS.md

対象：AIエージェント・人間
役割：方針と判断理由を日付付きで蓄積する記録
更新タイミング：重要な意思決定をしたとき

# DECISIONS

## [2025-05-30] VPCを独立スタックにした理由
- 変更頻度が低いため独立管理が適切と判断
- 他スタックはOutputsで参照する方針

## [2025-06-01] EC2にEIPを付与しない判断
- NATGateway経由で外部通信するため不要
- コスト削減の観点からも省略

DEPLOYMENT_RUNBOOK.md

対象：人間（デプロイ担当者）
役割：Stackの実行手順と運用手順の正本
更新タイミング：手順変更時

# DEPLOYMENT_RUNBOOK

## デプロイ手順

### 1. VPCスタック
aws cloudformation deploy \
  --template-file templates/vpc.yml \
  --stack-name myproject-vpc \
  --profile myproject

### 2. EC2スタック（VPCスタックの完了後）
aws cloudformation deploy \
  --template-file templates/ec2.yml \
  --stack-name myproject-ec2 \
  --profile myproject

## ロールバック手順
aws cloudformation delete-stack \
  --stack-name myproject-ec2 \
  --profile myproject

HISTORY.md

対象：AIエージェント・人間
役割：日付別の詳細な作業履歴。CURRENT_STATE.mdには書ききれない詳細をここに逃がす
更新タイミング：毎セッション終了時

# HISTORY

## 2025-06-01
- EC2テンプレートの作成に着手
- AMI IDをパラメータ化する方針に変更（DECISIONS.md参照）
- RDSパラメータグループ名が不明のためブロック中

## 2025-05-30
- VPC / Subnet / IGW / SecurityGroupのテンプレート作成完了
- スタックを用途別に分割する方針を決定（DECISIONS.md参照）

ファイル間の関係性

詳細はHISTORYに逃がす：CURRENT_STATE.mdは常に短く保ち、詳細はHISTORY.mdに記録する
判断はDECISIONSに集約：「なぜそうしたか」はテンプレートのコメントではなくDECISIONS.mdに書く
CONTEXTは簡潔に：AIの入口として機能させるため、情報を詰め込みすぎない

Codexへの指示テンプレート集

基本的な考え方

毎回すべての文書を読むように指示する必要はありません。
基本は CONTEXT.md を入口にし、必要な文書だけ追加で参照させれば十分です。

これにより以下のメリットがあります。

不要なファイルを読ませないことでトークン消費を抑えられる
指示がシンプルになり、作業の精度が上がる
どのテンプレートを使えばいいか迷わなくなる

文書の使い分けチートシート

やりたいこと	渡すファイル
今どこにいるか把握したい	`CONTEXT.md` + `CURRENT_STATE.md`
続きのタスクを進めたい	`CONTEXT.md` + `TASKS.md`
判断理由を踏まえて進めたい	`CONTEXT.md` + `CURRENT_STATE.md` + `DECISIONS.md`
詳細な経緯も踏まえて進めたい	`CONTEXT.md` + `HISTORY.md`
とにかく最短で依頼したい	`CONTEXT.md` のみ

シーン別指示テンプレート

シーン1：状況把握から始めてほしいとき

作業の全体像を整理したいときや、久しぶりにセッションを再開するときに使います。

まず cloudformation/CONTEXT.md と cloudformation/CURRENT_STATE.md を確認して、
現状を把握した上で作業してください。
今回の作業は ○○ です。

シーン2：未完了タスクの続きを進めてほしいとき

前回セッションの続きをそのまま進めてほしいときに使います。

cloudformation/CONTEXT.md と cloudformation/TASKS.md を確認して、
未完了タスクのうち ○○ を進めてください。

シーン3：判断理由も踏まえて進めてほしいとき

過去の設計方針を守りながら作業してほしいときに使います。
新しいリソースのテンプレートを作成するときに特に有効です。

cloudformation/CONTEXT.md、cloudformation/CURRENT_STATE.md、
cloudformation/DECISIONS.md を確認して、方針を踏まえたうえで
○○ を進めてください。

シーン4：詳細な経緯が必要なとき

過去の作業履歴やトラブルの経緯を踏まえて進めてほしいときに使います。
普段はほとんど使わず、問題が発生したときの切り札として活用します。

cloudformation/CONTEXT.md を起点に必要な関連文書を確認してください。
詳細な作業履歴が必要なら cloudformation/HISTORY.md も参照して、
○○ を進めてください。

シーン5：最短で依頼したいとき

作業内容が明確でコンテキストの確認が最小限で済むときに使います。

cloudformation/CONTEXT.md を起点に現状を確認してから、
○○ を進めてください。

セッション終了時のテンプレート

作業が終わったら、以下のテンプレートでhandover文書を更新させます。
このひと手間が次のセッションの立ち上がりを大幅に短縮します。

本日の作業をもとに以下のファイルを更新してください。

- CURRENT_STATE.md：完了・WIP・未着手・Blockerの状態を更新
- TASKS.md：完了タスクにチェック、次タスクの依存関係を更新
- HISTORY.md：本日の作業内容を日付付きで追記
- 重要な判断があれば DECISIONS.md にも追記

テンプレート活用のポイント

○○ の部分だけ変えれば使い回せるため、指示を考える時間がほぼゼロになります
セッション終了時の更新テンプレートを習慣化することが、この仕組みを機能させる鍵です
迷ったらシーン5の最短テンプレートから始め、情報が足りなければファイルを追加するアプローチが効率的です

実際のワークフロー

全体の流れ

IaC化の作業は以下のサイクルで進めました。

このサイクルを1リソース〜数リソース単位で繰り返すことで、
無理なく少しずつIaC化を進めることができました。

ステップ別の詳細

STEP1：セッション開始・状況把握

依頼例：EC2テンプレートの作成を進める場合

cloudformation/CONTEXT.md と cloudformation/TASKS.md を確認して、
未完了タスクのうち EC2テンプレートの作成 を進めてください。

STEP2：既存リソースの調査

Codexが AWS CLI を使って既存リソースの設定値を調査します。

# 既存EC2インスタンスの情報を取得
aws ec2 describe-instances \
  --filters "Name=tag:Name,Values=web-server-01" \
  --query "Reservations[].Instances[]" \
  --profile myproject

# 既存SecurityGroupの情報を取得
aws ec2 describe-security-groups \
  --filters "Name=tag:Name,Values=web-sg" \
  --profile myproject

STEP3：CloudFormationテンプレートの生成

調査結果をもとにCodexがテンプレートを生成します。
以下はEC2テンプレートのサンプルです。

# templates/ec2.yml
AWSTemplateFormatVersion: '2010-09-09'
Description: EC2 Instance Stack

Parameters:
  AmiId:
    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
    Default: /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64
  InstanceType:
    Type: String
    Default: t3.micro

Resources:
  WebServerInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !Ref AmiId
      InstanceType: !Ref InstanceType
      SecurityGroupIds:
        - !ImportValue myproject-vpc-WebSecurityGroupId
      SubnetId: !ImportValue myproject-vpc-PublicSubnetId
      Tags:
        - Key: Name
          Value: web-server-01

Outputs:
  InstanceId:
    Value: !Ref WebServerInstance
    Export:
      Name: !Sub ${AWS::StackName}-InstanceId

STEP4：デプロイ・検証

DEPLOYMENT_RUNBOOK.md の手順に従ってスタックをデプロイします。

aws cloudformation deploy \
  --template-file templates/ec2.yml \
  --stack-name myproject-ec2 \
  --profile myproject

デプロイ後は以下を確認します。

スタックのステータスが CREATE_COMPLETE になっていること
既存リソースとテンプレートの設定値に差異がないこと（ドリフト検出）

# ドリフト検出
aws cloudformation detect-stack-drift \
  --stack-name myproject-ec2 \
  --profile myproject

STEP5：handover文書の更新

本日の作業をもとに以下のファイルを更新してください。

- CURRENT_STATE.md：完了・WIP・未着手・Blockerの状態を更新
- TASKS.md：完了タスクにチェック、次タスクの依存関係を更新
- HISTORY.md：本日の作業内容を日付付きで追記
- 重要な判断があれば DECISIONS.md にも追記

ワークフローのポイント

1セッション = 1〜3リソースを目安にすると無理なく進められます
検証（STEP4）は必ず人間が行います。Codexに任せず自分の目で確認することが重要です
STEP5を省略するとコンテキストが失われるため、セッション終了時の更新は必ず実施します

CloudFormation化の実例

IaC化の対象リソースと進め方

以下の順番でIaC化を進めました。
依存関係があるリソースを考慮し、土台となるリソースから順番にテンプレート化しています。

スタック分割の方針

1つのテンプレートにすべてを詰め込まず、リソースの変更頻度と依存関係をもとにスタックを分割しました。
この判断はDECISIONS.mdに記録しています。

スタック名	対象リソース	変更頻度
`myproject-vpc`	VPC / Subnet / IGW / RouteTable	低
`myproject-sg`	SecurityGroup	中
`myproject-ec2`	EC2	中
`myproject-rds`	RDS / SubnetGroup / ParameterGroup	低
`myproject-alb`	ALB / TargetGroup / Listener	中

スタック間の値の受け渡しは Outputs と ImportValue を使って行います。

テンプレート実例

VPCスタック

# templates/vpc.yml
AWSTemplateFormatVersion: '2010-09-09'
Description: VPC Stack

Parameters:
  VpcCidr:
    Type: String
    Default: 10.0.0.0/16
  PublicSubnetCidr:
    Type: String
    Default: 10.0.1.0/24
  PrivateSubnetCidr:
    Type: String
    Default: 10.0.2.0/24

Resources:
  VPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: !Ref VpcCidr
      Tags:
        - Key: Name
          Value: myproject-vpc

  PublicSubnet:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      CidrBlock: !Ref PublicSubnetCidr
      AvailabilityZone: !Select [0, !GetAZs '']
      Tags:
        - Key: Name
          Value: myproject-public-subnet

  PrivateSubnet:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      CidrBlock: !Ref PrivateSubnetCidr
      AvailabilityZone: !Select [0, !GetAZs '']
      Tags:
        - Key: Name
          Value: myproject-private-subnet

  InternetGateway:
    Type: AWS::EC2::InternetGateway
    Properties:
      Tags:
        - Key: Name
          Value: myproject-igw

  VPCGatewayAttachment:
    Type: AWS::EC2::VPCGatewayAttachment
    Properties:
      VpcId: !Ref VPC
      InternetGatewayId: !Ref InternetGateway

Outputs:
  VpcId:
    Value: !Ref VPC
    Export:
      Name: !Sub ${AWS::StackName}-VpcId
  PublicSubnetId:
    Value: !Ref PublicSubnet
    Export:
      Name: !Sub ${AWS::StackName}-PublicSubnetId
  PrivateSubnetId:
    Value: !Ref PrivateSubnet
    Export:
      Name: !Sub ${AWS::StackName}-PrivateSubnetId

RDSスタック

# templates/rds.yml
AWSTemplateFormatVersion: '2010-09-09'
Description: RDS Stack

Parameters:
  DBInstanceClass:
    Type: String
    Default: db.t3.micro
  DBName:
    Type: String
    Default: myprojectdb
  DBUsername:
    Type: String
    NoEcho: true
  DBPassword:
    Type: String
    NoEcho: true

Resources:
  DBSubnetGroup:
    Type: AWS::RDS::DBSubnetGroup
    Properties:
      DBSubnetGroupDescription: myproject DB Subnet Group
      SubnetIds:
        - !ImportValue myproject-vpc-PrivateSubnetId

  DBInstance:
    Type: AWS::RDS::DBInstance
    Properties:
      DBInstanceClass: !Ref DBInstanceClass
      Engine: mysql
      EngineVersion: '8.0'
      DBName: !Ref DBName
      MasterUsername: !Ref DBUsername
      MasterUserPassword: !Ref DBPassword
      DBSubnetGroupName: !Ref DBSubnetGroup
      VPCSecurityGroups:
        - !ImportValue myproject-sg-DbSgId
      MultiAZ: false
      Tags:
        - Key: Name
          Value: myproject-rds

Outputs:
  DBEndpoint:
    Value: !GetAtt DBInstance.Endpoint.Address
    Export:
      Name: !Sub ${AWS::StackName}-DBEndpoint

DECISIONS.mdとの連動例

テンプレートの設計判断はコメントではなく DECISIONS.md に記録しました。

# DECISIONS

## [2025-06-03] RDSをMultiAZ:falseにした理由
- 開発環境のため可用性よりコスト優先と判断
- 本番環境移行時は true に変更する予定

## [2025-06-03] DBの認証情報をParameterで渡す方針
- テンプレートにハードコードしない
- 本番環境ではSystems Manager Parameter Storeへの移行を検討

このようにテンプレートの設計とDECISIONS.mdがセットで機能することで、
後から「なぜこの設定にしたのか」を追えるようになりました。

ハマりどころ・工夫点

1. CONTEXT.mdに情報を詰め込みすぎた

CONTEXT.mdはAIの入口として機能させるために簡潔に保つことが重要です。
最初は「なるべく多くの情報を入れておけば安心」という考えで書いていたところ、
逆にCodexが重要な情報を見落とすケースが増えてしまいました。

対処方法

CONTEXT.mdにはプロジェクト概要・ディレクトリ構成・AIへの行動指針の3点のみ記載する
詳細な情報は適切なファイルに分散させ、必要なときだけ参照させる

❌ CONTEXT.mdに全部書く

プロジェクト概要
現在の状態
タスク一覧
判断理由
作業履歴

→ 情報が埋もれる

✅ 役割ごとに分散させる

CONTEXT.md → 概要のみ
CURRENT_STATE.md → 状態
TASKS.md → タスク
DECISIONS.md → 判断
HISTORY.md → 履歴

2. HISTORY.mdの肥大化

毎セッション追記していくHISTORY.mdは、放置するとどんどん長くなります。
長くなるとCodexが読み込むトークンが増え、参照コストが上がってしまいます。

対処方法

HISTORY.mdは詳細な経緯が必要なときだけ参照させる運用にする（シーン4のみ）
普段のセッションではCURRENT_STATE.mdの短い要約で十分なことがほとんど
月1回など定期的に古いエントリをアーカイブする

3. Codexへの指示が曖昧だと手戻りが発生した

「○○をやってください」という曖昧な指示では、
Codexが意図と異なるアウトプットを出すことがありました。

具体的な失敗例

「RDSのテンプレートを作ってください」だけ伝えたら、既存リソースの設定値を無視して新規構成で作られた
「テンプレートを修正してください」だけ伝えたら、関係ないリソースまで変更された

対処方法

対象リソース・作業範囲・完了条件を明示するようにした
既存リソースのIaC化であることを毎回明示する

cloudformation/CONTEXT.md と cloudformation/TASKS.md を確認して、
以下の条件でRDSテンプレートを作成してください。

- 対象：既存リソース myproject-rds の IaC化
- 既存リソースの設定値を aws rds describe-db-instances で調査してから作成すること
- 新規リソースの追加・既存テンプレートの変更は行わないこと

4. handover文書の更新を忘れた

作業に集中しているとSTEP5のhandover更新を忘れがちです。
更新を忘れると次のセッションでコンテキストがズレてしまい、
修正に余計な時間がかかりました。

対処方法

セッション終了時の更新テンプレートをメモ帳やスニペットに登録しておく
「デプロイが完了したらhandoverを更新する」を作業完了の定義に含める

成果・振り返り

handover文書戦略の効果

✅ Codexの初動が格段に速くなった

セッション開始時の説明がほぼゼロになった
CONTEXT.md を渡すだけでCodexがすぐに作業を開始できる状態になった

✅ 判断の経緯が追えるようになった

「なぜこの設定にしたのか」をDECISIONS.mdで振り返れるようになった
後からテンプレートを修正する際に、過去の判断を踏まえた変更ができるようになった

✅ 進捗が一目でわかるようになった

CURRENT_STATE.mdを見れば今どこにいるかが即座にわかる
TASKS.mdで依存関係を管理したことで、作業順序の迷いがなくなった

✅ 人間への引き継ぎにもそのまま使えた

チームメンバーへの共有もONBOARDING.mdを渡すだけで済んだ
ドキュメントを別途作成する手間が不要だった

振り返り：やってよかったこと

人向けとAI向けで入口を分けたことで、どちらにとっても迷いのない設計になった
シーン別テンプレートを用意したことで、毎回の指示コストがほぼゼロになった
DECISIONS.mdに判断理由を残す習慣をつけたことで、後から経緯を追えるようになった

振り返り：改善したいこと

HISTORY.mdの肥大化を防ぐ運用ルールをもっと早めに決めておくべきだった
CONTEXT.mdに情報を詰め込みすぎる時期があり、整理に時間がかかった
handover文書の更新をCodexに任せているため、稀に更新漏れが発生した

まとめ・今後の展望

3行まとめ

コンテキストはコードと同じリポジトリのhandover文書群で管理する
人向けは ONBOARDING.md、AI向けは CONTEXT.md と入口を分ける
シーン別の指示テンプレートで毎回の指示コストをほぼゼロにする

この仕組みが活きる場面

セッションをまたいでAIエージェントに作業を依頼するとき
複数のAIエージェントを使い分けるとき
チームメンバーへプロジェクトを引き継ぐとき
しばらく離れていたプロジェクトに戻るとき

今後の展望

短期的な改善

セッション終了時のhandover更新をCodexへの指示に自動で含める仕組みを作る
HISTORY.mdの肥大化を防ぐため、定期的なアーカイブフローを整備する

中長期的な展望

他のAIエージェント（Claude / GitHub Copilot）でも同じ仕組みを試す
チーム開発での活用（複数人でのhandover文書の運用ルール策定）
TerraformなどほかのIaCツールへの応用

おわりに

今回ご紹介したhandover文書戦略は、CloudFormationやCodexに限らず、
AIエージェントとの協働全般に応用できる考え方です。

「AIにどう伝えるか」を仕組みとして設計することで、
毎回の指示コストを下げながら、作業品質を安定させることができます。

ぜひ自分のプロジェクトに合わせてアレンジして試してみてください。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Codex × CloudFormation で既存AWS環境をIaC化した話 〜handover文書でコンテキストを外出しし、AIエージェントを使いこなす戦略〜

はじめに

この記事で得られること

想定読者

使用技術

背景・課題

AWS環境の管理状況

IaC化に踏み切った理由

AIエージェントを使ってみたが…

課題の整理

解決アプローチ概要

基本的な考え方

handover文書群の概要

人向けとAI向けで入口を分ける

課題とアプローチの対応

Before / After

handover文書の設計思想

設計の3原則

各ファイルの役割詳解

ONBOARDING.md

CONTEXT.md

CURRENT_STATE.md

TASKS.md

DECISIONS.md

DEPLOYMENT_RUNBOOK.md

HISTORY.md

ファイル間の関係性

Codexへの指示テンプレート集

基本的な考え方

文書の使い分けチートシート

シーン別 指示テンプレート

シーン1：状況把握から始めてほしいとき

シーン2：未完了タスクの続きを進めてほしいとき

シーン3：判断理由も踏まえて進めてほしいとき

シーン4：詳細な経緯が必要なとき

シーン5：最短で依頼したいとき

セッション終了時のテンプレート

テンプレート活用のポイント

実際のワークフロー

全体の流れ

ステップ別の詳細

STEP1：セッション開始・状況把握

STEP2：既存リソースの調査

STEP3：CloudFormationテンプレートの生成

STEP4：デプロイ・検証

STEP5：handover文書の更新

ワークフローのポイント

CloudFormation化の実例

IaC化の対象リソースと進め方

スタック分割の方針

テンプレート実例

VPCスタック

RDSスタック

DECISIONS.mdとの連動例

ハマりどころ・工夫点

1. CONTEXT.mdに情報を詰め込みすぎた

2. HISTORY.mdの肥大化

3. Codexへの指示が曖昧だと手戻りが発生した

4. handover文書の更新を忘れた

成果・振り返り

handover文書戦略の効果

✅ Codexの初動が格段に速くなった

✅ 判断の経緯が追えるようになった

✅ 進捗が一目でわかるようになった

✅ 人間への引き継ぎにもそのまま使えた

振り返り：やってよかったこと

振り返り：改善したいこと

まとめ・今後の展望

3行まとめ

この仕組みが活きる場面

今後の展望

短期的な改善

中長期的な展望

おわりに

Codex × CloudFormation で既存AWS環境をIaC化した話〜handover文書でコンテキストを外出しし、AIエージェントを使いこなす戦略〜

シーン別指示テンプレート