AWS Step FunctionsをAWS CDKとAWS Toolkit for Visual Studio Codeで開発する

こんにちは、医療機関支援事業本部の森田です。今年、JMDCではアドベントカレンダーに参加しています。

本記事は、JMDC Advent Calendar 2025 の 7日目の記事です。

はじめに
準備
ASLを軸にAWS ToolkitとCDK、AIが紐付く
まとめ

はじめに

ワークフローを構築する Step Functionsですが、開発を行うにあたりさまざまな理由でとっつきにくさを感じることがあります。
マネジメントコンソールでのGUI構築が可能であってもチームでの開発になると管理が煩雑になったり、ローカルでコードを使って構築する場合でもコード（ASL定義）の可読性やメンテナンス性に課題があります。

今回はAWS Toolkit (Visual Studio Code拡張) とCDKを組み合わせての開発を試したところ、なかなか良い体験が得られたのでその内容を紹介します。

準備

まず、開発環境の準備です。
Visual Studio Codeを用意し、CDKプロジェクトのセットアップとAWS Toolkit for Visual Studio Codeのインストールを行います。 AWS Toolkitでステートマシンを表示できるようにするため、ステートマシン定義はASLファイル(.json)で管理しCDKでデプロイできる形を作ります。
CDKコードのファイル構成は以下のようなイメージです。

.
├── lib
│   └── my-workflow-stack.ts
└── statemachines
    └── my-workflow.asl.json

CDKのリソースの書き方はJSONファイルを読み込んで DefinitionBody として持たせます。これによりCDKのコードを変更することなくASL側の修正だけでロジックを変更可能になります。

import * as fs from 'fs'
import * as path from 'path'
import * as sfn from 'aws-cdk-lib/aws-stepfunctions'

// ASLファイルの読み込み
const aslFilePath = path.join(
  __dirname,
  '../statemachines/my-workflow.asl.json'
)
const aslContent = fs.readFileSync(aslFilePath, 'utf8')

// ステートマシンの定義
new sfn.StateMachine(
  this,
  'MyWorkflowStateMachine',
  {
    stateMachineName: `my-workflow-statemachine`,
    comment: 'ワークフロー定義サンプル',
    // クエリ言語にJSONataを使う
    queryLanguage: sfn.QueryLanguage.JSONATA,
    // ここでASLを読み込む
    definitionBody: sfn.DefinitionBody.fromString(aslContent),
    //・・・(略)・・・
  }
)

ASLを軸にAWS ToolkitとCDK、AIが紐付く

ここから開発体験の話です。
良かった点を挙げていきます。

AWS Toolkit によるビジュアライズ

AWS Toolkitをインストールした状態で .asl.json ファイルを開くとマネジメントコンソールと変わらないデザインモード表示ができます。 GUIでの操作も可能ですし、別タブでJSONを直接操作してもちゃんと反映されるためストレスなく作業を進めることができます。

Visual Studio Code作業中のイメージ、デザインモードはAIなどでコードを更新しても自動的に反映します

JSONata によるデータ変換で Lambda を削減

最新のStep Functions のデータ入出力ではJSONataというクエリ言語が使えます。
以前のStep Functions ではクエリ言語としてJSONPathを使っていましたが、「直前のステップの出力結果を加工して次に渡すためだけに Lambda を書く必要がある」という課題がありました。
JSONataではLambdaを使用することなくステップの簡略化ができるようになります。

例：S3のオブジェクトキーからファイル名を取り出す

$split(s3Key, "/")[-1]

JSONPathではJSONのデータは扱えても中の値を変更することはできませんでした。このようにデータ変換用Lambdaを大幅に削減でき、リソース管理もスッキリしました。

AIとのペアプログラミング

最も感動したのは、AI アシスタントとの相性の良さです。 ASL（JSON構造）はAIにとっても読み書きがしやすい形式なので扱いやすく以下の流れで開発を進めることができます。

1. 作業者がAIに指示
　AWS Toolkit上で視覚的にワークフローを確認し作業指示
2. AIが実装
　指示に従ってステートマシンを実装
3. 作業者が動作確認
　デザインモードの表示が更新されるので処理内容が意図通りか視覚的にチェック。個々のステートの入出力もローカルでできるのでテスト実施

この「AIに書かせて、人間は視覚的にレビューする」というサイクルが手元で回せることでロジックのみに集中でき非常に有意義な体験が得られました。