cdk-imp

name	cdk-imp
description	AWS CDK実装専用コマンド。GitHub IssueからCDK実装・テスト・CDK合成まで自動実行する。CDKインフラの実装を依頼されたときに使用すること。
argument-hint	<Issue番号>

指定されたGitHub Issueを元に、設計書を参照してAWS CDKコード（cdk/ディレクトリ配下）のみを実装し、テスト・合成まで実行してください。 backend/やfrontend/配下のアプリケーションコードは絶対に実装・変更しないでください。 Issueのタスク一覧のうち、CDK/インフラに関するタスクのみを対象としてください。 完了したCDKタスクのみ gh issue edit コマンドでGitHub Issueのチェックリストを更新してください。

Issue指定:

引数が空の場合は、ユーザーにIssue番号を確認してください。

---

CDK実装の詳細手順

GitHub IssueからAWS CDK実装を実行する。 設計書を参照し、CDKルールを遵守したインフラコードを実装、テスト・合成まで実行する。

⚠️ スコープ制約（厳守）

• CDKコード（cdk/ディレクトリ配下）のみを対象とする
• backend/、frontend/配下のアプリケーションコードは絶対に実装・変更しないこと
• Issueのタスク一覧のうち、CDK/インフラに関するタスクのみを実装対象とする
• backendのLambdaハンドラー実装、frontendのUI実装、アプリケーションのテストコード等は対象外
• 対象外のタスクはスキップし、GitHub Issueのチェックリストも更新しないこと

実行プロセス

Phase 1: Issue読み込みと実装仕様の抽出

ステップ 1-1: Issue番号の取得

タスクプロンプトの「Issue指定:」の値を確認する。値が含まれている場合はそれを使用し、空の場合のみAskUserQuestionでユーザーに確認する。

question: "CDK実装を行うIssueを指定してください。Issue番号（例: 1）を入力してください。"
header: "Issue指定"
options: [
  { label: "その他（手動入力）", description: "Issue番号を入力してください" }
]
multiSelect: false

取得情報:

• Issue番号

ステップ 1-2: GitHub IssueのJSON取得

Bash ツールで GitHub Issue の情報を取得:

gh issue view {番号} --json number,title,body,labels

エラーハンドリング:

Issue が見つからない場合:

=== Issue 読み込みエラー ===

Error: Issue #{番号} が見つかりませんでした。
gh issue list で利用可能なIssue一覧を確認してください。

→ AskUserQuestion で再入力を促す（最大3回まで）

body が空の場合:

=== Issue 読み込みエラー ===

Error: Issue #{番号} の本文が空です。

→ 処理を中止

ステップ 1-3: Issue内容の解析

取得したJSONから以下の情報を抽出:

1. Issue番号とタイトル

• Issue番号: .number フィールド
• タイトル: .title フィールド

2. ラベル

.labels[].name フィールドから抽出

• 抽出例: [{name: "cdk"}, {name: "infra"}] → ['cdk', 'infra']

3. スコープ/作業項目

body内 ## スコープ / 作業項目 セクションの内容全体を抽出

4. タスク一覧（CDKタスクのみ抽出）

body内 ## タスク一覧 セクションのチェックリスト（- [ ] 形式）を抽出し、CDK/インフラに関するタスクのみをフィルタリングする。

フィルタリングルール:

• 対象: 「CDK」「cdk」「インフラ」「スタック」「Construct」「デプロイ」「synth」「スナップショット」等のキーワードを含むタスク
• 対象外（スキップ）: 「Lambda実装」「ハンドラー実装」「API実装」「フロントエンド」「画面」「テストコード作成」「TDD」「単体テスト」等、アプリケーションコードに関するタスク
• キーワードだけで判断が難しい場合は、タスクの文脈からCDK/インフラ関連かどうかを判断する
• フィルタリング結果（対象タスク・スキップしたタスク）を明示的に表示する

5. 対象ファイル

body内 ## 📂 コンテキスト または ### 対象ファイル セクションから抽出

• cdk/lib/oidc-sandbox-stack.ts
• cdk/lib/constructs/*.ts（新規Constructの場合）

出力例:

=== Issue解析結果 ===

Issue: #1 CDK初期構築

ラベル: cdk, infra
対象ファイル: cdk/lib/oidc-sandbox-stack.ts

対象タスク（CDK/インフラ関連）:
- [ ] CDKコード実装
- [ ] スナップショットテスト更新
- [ ] cdk synth確認

スキップするタスク（アプリケーションコード関連）:
- [ ] Lambdaハンドラー実装 → 対象外
- [ ] フロントエンド実装 → 対象外

スコープ:
- CDKプロジェクト初期化
- スタック基本構成作成

ステップ 1-5: 実装仕様の整理と確認

抽出した情報をユーザーに提示し、開始確認:

question: "以下の内容でCDK実装を開始します。よろしいですか？"
header: "実装開始確認"
options: [
  { label: "はい、開始します", description: "CDK実装を開始します" },
  { label: "いいえ、中止します", description: "処理を中止します" }
]

Phase 2: 設計書参照と実装方針確認

ステップ 2-1: ラベルから対象設計書を特定

Phase 1で抽出したラベル情報から、対象設計書を推測:

ラベルマッピングルール:

const labelToDesignDoc: Record<string, string[]> = {
  cdk: ['docs/design/infrastructure-design.md'],
  infra: ['docs/design/infrastructure-design.md'],
  backend: ['docs/design/backend-design.md', 'docs/design/infrastructure-design.md'],
  frontend: ['docs/design/frontend-design.md', 'docs/design/infrastructure-design.md']
}

推測ロジック:

1. 各ラベルをマッピングルールで変換
2. 重複を除去
3. infrastructure-design.md は常に参照対象

結果例:

対象設計書:
- docs/design/infrastructure-design.md
- docs/design/backend-design.md（Lambda関数関連の場合）

ステップ 2-2: infrastructure-design.md の読み込み

Read ツールで以下のセクションを読み込み:

必須セクション:

• セクション2「設計判断サマリー」（ADRへのリンクと決定内容）
• セクション3「アーキテクチャ概要」（全体構成図、コンポーネント）
• セクション6「補足」（スタック構成）

file_path: docs/design/infrastructure-design.md

抽出する情報:

• 設計判断サマリーから主要な決定事項
• アーキテクチャ概要からコンポーネント構成
• 補足セクションからスタック構成

ステップ 2-3: 関連設計書の読み込み（必要に応じて）

ラベルに応じて追加の設計書を読み込み:

Lambda関数追加の場合:

file_path: docs/design/backend-design.md

CloudFront/S3変更の場合:

file_path: docs/design/frontend-design.md

ステップ 2-4: CDKルールの確認

file_path: .claude/rules/cdk.md

確認事項:

• Import形式: import { aws_s3 as s3 } from 'aws-cdk-lib'
• L2 Construct優先
• IAM Role自動生成の活用
• Import順序: 標準ライブラリ → サードパーティ → 自作モジュール

ステップ 2-5: 実装方針の整理と確認

設計書とCDKルールから抽出した情報を整理してユーザーに提示:

=== 実装方針サマリー ===

設計判断:
- Lambda Function URLs を使用（ADR-001）
- OAC + IAM認証（ADR-004）

CDKルール:
- L2 Construct優先
- Import形式: aws_s3 as s3
- IAM Role自動生成を活用

循環参照回避戦略:
- SSM Parameter Store の利用
- ワイルドカードリソース指定
- L1 Construct（Cfn）の活用

AskUserQuestion で実装方針を確認:

question: "上記の実装方針でCDKコードを実装します。よろしいですか？"
header: "実装方針確認"
options: [
  { label: "はい、この方針で実装します", description: "CDKコード実装に進みます" },
  { label: "いいえ、修正が必要です", description: "実装方針を見直します" }
]

Phase 3: CDK実装

ステップ 3-1: 対象ファイルの特定

Issue内の「📂 コンテキスト」または「### 対象ファイル」セクションから対象ファイルを取得:

• 通常は cdk/lib/oidc-sandbox-stack.ts（メインスタック）
• 新規Constructの場合は新規ファイル作成も検討

ステップ 3-2: 既存CDKコードの読み込み

Read ツールで対象ファイルを読み込み:

file_path: cdk/lib/oidc-sandbox-stack.ts

確認事項:

• 既存の実装パターン
• 既存のImport形式
• 既存のConstructの構成

ステップ 3-3: CDKルールの遵守チェック

実装前に以下を確認:

Import形式:

// ✅ 正しい形式
import { aws_s3 as s3 } from 'aws-cdk-lib'
import { aws_lambda as lambda } from 'aws-cdk-lib'

// ❌ 避けるべき形式
import * as s3 from 'aws-cdk-lib/aws-s3'

Import順序:

// 1. 標準ライブラリ
import * as path from 'path'

// 2. サードパーティライブラリ（CDK含む）
import { Stack, StackProps, RemovalPolicy } from 'aws-cdk-lib'
import { aws_s3 as s3 } from 'aws-cdk-lib'

// 3. 自作モジュール
import { AppParameter } from '../parameter'

L2 Construct優先:

• 可能な限りHigh-level APIを使用
• L1（Cfn）は循環参照回避時のみ使用

IAM Role自動生成:

• L2 ConstructのIAM Role自動生成機能を活用
• 明示的なRole定義は避ける

ステップ 3-4: CDKコードの実装

Edit または Write ツールで実装:

実装ガイドライン:

コメント・JSDoc は docs/policy/code-comment-policy.md に従う（実装コメントは WHY、doc comment は契約。コードが語る WHAT/HOW は書かない）。

1. JSDocコメント: 関数の役割・引数・戻り値・例外を契約として明記
2. 日本語コメント: コードから読み取れない WHY（判断理由・制約・罠）を説明
3. 循環参照の回避:
   • SSM Parameter Storeの活用（CloudFront URLなど）
   • ワイルドカードリソース指定（Secrets Managerなど）
   • L1 Construct（Cfn）の活用（後付け設定）

実装例:

/**
 * S3バケットを作成
 * @param {string} bucketName - バケット名
 * @returns {s3.Bucket} - 作成されたS3バケット
 */
private createS3Bucket(bucketName: string): s3.Bucket {
  // 1. S3バケット作成（L2 Construct使用）
  const bucket = new s3.Bucket(this, 'FrontendBucket', {
    bucketName: bucketName,
    removalPolicy: RemovalPolicy.DESTROY,
    autoDeleteObjects: true,
  })

  // 2. バケットポリシー設定（OAC用）
  // 循環参照回避のため、CloudFront作成後にL1 Constructで設定

  return bucket
}

ステップ 3-5: 実装内容の確認

実装したコードをユーザーに提示:

=== CDK実装完了 ===

実装ファイル: cdk/lib/oidc-sandbox-stack.ts

変更内容:
- Lambda Function作成（NodejsFunction使用）
- Lambda Function URL設定
- CloudFront Origin設定
- IAMポリシー自動生成

AskUserQuestion で確認:

question: "実装内容を確認してください。このままテストに進みますか？"
header: "実装確認"
options: [
  { label: "はい、テストに進みます", description: "npm testを実行します" },
  { label: "いいえ、修正が必要です", description: "実装を見直します" }
]

重要な考慮事項:

• TypeScriptコンパイルは実施しない（CLAUDE.mdより）
• テスト実行で型エラーが検出される

Phase 4: テスト実行

ステップ 4-1: npm test の実行

Bash ツールでCDKテストを実行:

cd cdk && npm test

成功判定: 終了コード 0

ステップ 4-2: テスト結果の解析

成功時:

✅ Tests Passed

All CDK tests passed successfully.

失敗時:

テストエラーメッセージを解析:

1. スナップショット不一致の検出:

   • エラーメッセージに "snapshot" または "does not match" が含まれる
   • → ステップ 4-3 へ

2. その他のエラー:

   • 型エラー、構文エラー、ロジックエラー等
   • → ステップ 4-4 へ

ステップ 4-3: スナップショット更新の確認

スナップショット不一致が検出された場合:

⚠️ Snapshot Mismatch Detected

スナップショットテストが不一致です。以下のファイルで差分が検出されました:

cdk/test/__snapshots__/cdk.test.ts.snap

差分内容:
- CloudFormation テンプレートの変更
- リソース追加/削除

スナップショットを更新しますか？

AskUserQuestion でスナップショット更新の可否を確認:

question: "スナップショットを更新しますか？（実装内容が正しい場合は更新してください）"
header: "スナップショット更新"
options: [
  { label: "はい、更新します", description: "npm test -- -u を実行してスナップショットを更新" },
  { label: "いいえ、実装を修正します", description: "CDKコードを見直します" }
]
multiSelect: false

「はい」選択時:

cd cdk && npm test -- -u

スナップショット更新後、再度テスト実行:

cd cdk && npm test

「いいえ」選択時:

Phase 3に戻り、実装を修正

ステップ 4-4: エラーがあれば修正提案

テスト失敗（スナップショット以外）の場合:

🔴 Test Failed

以下のエラーが検出されました:

cdk/lib/oidc-sandbox-stack.ts:42:7
  Error: Property 'functionUrl' does not exist on type 'Function'.

原因:
Lambda Function URLはNodejsFunctionのプロパティとして直接アクセスできません。

修正方法:
1. FunctionUrl Constructを使用してURLを作成
2. または、addFunctionUrl() メソッドを使用

修正しますか？

AskUserQuestion で修正するか確認:

question: "上記のエラーを修正しますか？"
header: "エラー修正"
options: [
  { label: "はい、修正します", description: "エラーを修正してテストを再実行" },
  { label: "いいえ、中止します", description: "処理を中止します" }
]

「はい」選択時: Phase 3に戻り、実装を修正

エラーハンドリング:

• 最大3回まで修正を試行
• 3回失敗した場合は処理を中止し、ユーザーに手動修正を促す

Phase 5: CDK合成と循環参照チェック

ステップ 5-1: cdk synth の実行

Bash ツールでCloudFormationテンプレート合成:

cd cdk && npx cdk synth

成功判定: 終了コード 0

ステップ 5-2: 合成結果の確認

成功時:

✅ CDK Synth Passed

CloudFormation テンプレートが正常に生成されました:

cdk.out/oidc-sandbox-app.template.json
cdk.out/oidc-sandbox-app.assets.json
cdk.out/manifest.json
cdk.out/tree.json

失敗時:

合成エラーメッセージを解析:

1. 循環参照エラーの検出:

   • エラーメッセージに "Circular dependency" が含まれる
   • → ステップ 5-3 へ

2. その他のエラー:

   • 構文エラー、リソース設定エラー等
   • → ステップ 5-4 へ

ステップ 5-3: 循環参照エラーのチェック

循環参照エラーが検出された場合:

🔴 Circular Dependency Detected

循環参照エラーが検出されました:

Error: Circular dependency between resources:
- CloudFrontDistribution depends on LambdaFunctionUrl
- LambdaFunction depends on CloudFrontDistribution (via IAM policy)

原因:
CloudFrontのURLをLambda関数のIAMポリシーで参照しようとしています。

回避方法:
1. SSM Parameter Store を利用してCloudFront URLを保存
2. Lambda関数のIAMポリシーでワイルドカード指定（'*'）
3. L1 Construct（Cfn）を使用して後付け設定

AskUserQuestion で修正方法を確認:

question: "循環参照を回避するため、以下のいずれかの方法で修正します。どれを選択しますか？"
header: "循環参照回避"
options: [
  { label: "SSM Parameter Store を利用", description: "CloudFront URLをSSMに保存し、Lambda側で参照" },
  { label: "ワイルドカード指定", description: "IAMポリシーで '*' を使用" },
  { label: "L1 Construct 活用", description: "Cfn を使用して後付け設定" },
  { label: "手動で修正", description: "処理を中止して手動で修正" }
]

選択に応じて Phase 3 に戻り、実装を修正

ステップ 5-4: エラーがあれば修正提案

合成エラー（循環参照以外）の場合:

🔴 Synth Failed

以下のエラーが検出されました:

Error: Bucket name must be lowercase

原因:
S3バケット名に大文字が含まれています。

修正方法:
bucketName を小文字に変更してください。

AskUserQuestion で修正するか確認:

question: "上記のエラーを修正しますか？"
header: "エラー修正"
options: [
  { label: "はい、修正します", description: "エラーを修正してcdk synthを再実行" },
  { label: "いいえ、中止します", description: "処理を中止します" }
]

「はい」選択時: Phase 3に戻り、実装を修正

循環参照の回避戦略（既存実装を参考）:

• SSM Parameter Store の利用（CloudFront URL保存など）
• ワイルドカードリソース指定（'*'）
• L1 Construct（Cfn）の活用（後付け設定）

Phase 6: 結果報告と Next Actions

ステップ 6-1: 実装サマリーの表示

## CDK実装完了レポート

### 実装サマリー

Issue: #{番号} {タイトル}

実装ファイル:
- cdk/lib/oidc-sandbox-stack.ts

変更内容:
- Lambda Function URLの追加
- CloudFrontのOrigin設定更新
- IAMポリシーの自動生成

ステップ 6-2: テスト結果サマリー

### テスト結果

| チェック項目 | 結果 |
| --- | --- |
| npm test | ✅ Passed (X tests) |
| cdk synth | ✅ Passed |
| 循環参照チェック | ✅ OK |

または失敗時:

### テスト結果

| チェック項目 | 結果 |
| --- | --- |
| npm test | 🔴 Failed |
| cdk synth | - |
| 循環参照チェック | - |

ステップ 6-3: Next Actions の提案

成功時:

### Next Steps

1. /cdk-ci で包括的な品質チェック（静的解析、型チェック）
2. cdk diff でデプロイ前の差分確認
3. cdk deploy で実際にデプロイ（人間が実施）
4. 結合テスト実行（人間が実施）
5. /git-commit でコミット作成

失敗時:

### Next Steps

1. 上記のエラーを修正
2. /cdk-imp を再実行

ステップ 6-4: GitHub Issueのタスクチェックリスト更新

Bash ツールで実装・テスト・CDK合成に関するタスクを完了マークに更新:

BODY=$(gh issue view {番号} --json body --jq '.body')
# CDK実装・テスト・synth完了に関連するタスクを完了マークに更新
UPDATED_BODY=$(echo "$BODY" | sed 's/- \[ \] \(.*実装.*\)/- [x] \1/g' \
  | sed 's/- \[ \] \(.*テスト.*\)/- [x] \1/g' \
  | sed 's/- \[ \] \(.*synth.*\)/- [x] \1/g')
gh issue edit {番号} --body "$UPDATED_BODY"

該当するタスクが見つからない場合はスキップ（エラーにしない）。

出力フォーマット（完全版）:

## CDK実装完了レポート

### 実装サマリー

Issue: #1 CDK初期構築

実装ファイル:

- cdk/lib/oidc-sandbox-stack.ts

変更内容:

- スタック基本構成作成
- S3バケット作成
- CloudFront設定

### テスト結果

| チェック項目     | 結果                |
| ---------------- | ------------------- |
| npm test         | ✅ Passed (2 tests) |
| cdk synth        | ✅ Passed           |
| 循環参照チェック | ✅ OK               |

### Next Steps

1. /cdk-ci で包括的な品質チェック（静的解析、型チェック）
2. cdk diff でデプロイ前の差分確認
3. cdk deploy で実際にデプロイ（人間が実施）
4. 結合テスト実行（人間が実施）
5. /git-commit でコミット作成

### GitHub Issue更新

✓ Issue #1 のタスクチェックリストを更新しました（gh issue edit で実装・テスト・synth完了を反映）

エラーハンドリング一覧

エラー種別	判定方法	処理内容
Issue が見つからない	gh issue view がエラー	エラーメッセージを表示し再入力を促す（最大3回）
Issue の body が空	JSON body フィールドが空	処理を中止
設計書ファイルが見つからない	Read でエラー	警告を表示し、Issueの情報のみで処理継続
npm test 失敗	終了コード 非0	エラーメッセージを解析し、修正方法を提案
スナップショット不一致	テストエラーメッセージに "snapshot" 含む	AskUserQuestion でスナップショット更新の可否を確認
cdk synth 失敗	終了コード 非0	エラーメッセージを解析し、修正方法を提案
循環参照エラー	エラーメッセージに "Circular dependency" 含む	原因リソースを特定し、回避方法を提案（SSM/ワイルドカード/L1 Construct）
修正試行回数超過	3回連続で同じエラー	処理を中止し、ユーザーに手動修正を促す

制約事項

TypeScriptコンパイル

CLAUDE.md の指示により、TypeScriptコンパイル（tsc）は実行しない。 型エラーは npm test または cdk synth で検出される。

デプロイ

cdk deploy は実行しない。デプロイは人間が実施。

スタック構成

基本的に単一スタック構成（oidc-sandbox-stack.ts）を想定。 複数スタックの場合は設計書を確認。

実装上の注意点

循環参照の回避

CloudFormationの循環参照は以下のパターンで発生しやすい:

1. CloudFront ⇔ Lambda Function URL

   • CloudFrontがLambda URLをOriginとして参照
   • LambdaのIAMポリシーがCloudFrontのURLを参照
   • → SSM Parameter Storeで回避

2. Lambda ⇔ DynamoDB

   • LambdaがDynamoDBテーブルを参照
   • DynamoDBストリームがLambdaを参照
   • → ワイルドカード指定で回避

3. S3 ⇔ CloudFront

   • S3バケットポリシーがCloudFrontのOACを参照
   • CloudFrontがS3をOriginとして参照
   • → L1 Construct（Cfn）で後付け設定

スナップショット更新のタイミング

以下の場合はスナップショット更新が必要:

• 新規リソース追加
• リソースプロパティ変更
• CloudFormationテンプレート構造変更

ユーザーに確認後、npm test -- -u で更新。

エラー修正の上限

同じエラーで3回連続失敗した場合は処理を中止。 無限ループを避け、ユーザーに手動修正を促す。