Claude Codeのaws-serverlessプラグインでLambdaを設計から検証まで進める

AWSが公開しているaws-serverlessプラグインは、Claude Codeに「Lambdaの設計・構築・デプロイ・テスト・デバッグ」の手順書(skill)、操作用のMCPサーバー、SAMテンプレートの検証フックをまとめて足します。入れるだけでsam initからsam deployまでをClaudeが呼び出せるようになりますが、同じ仕組みでsam_deployも既定で許可されています。この記事は、何が入るのか、どう導入するのか、デプロイだけを人の承認に残すにはどう設定するのかを順に扱います。

aws-serverlessプラグインに入っているもの

プラグインはAWSのagent-pluginsリポジトリの一部で、Claude Code・Codex・Cursor向けに配られています。aws-serverlessの中身は、skill・MCPサーバー・フックの3種類です。

skillごとの役割は、トリガーとなる語で見分けられます。

skillの数は、見る場所で食い違う

マーケットプレイスの紹介ページは「3つの専用skill」と説明し、リポジトリのREADMEのトリガー表には4つが載っています。プラグインのskillsディレクトリを開くと、さらにapi-gateway、aws-lambda-microvms、aws-step-functionsを含む7つのフォルダーがあります。説明が実体に追いついていない部分があるため、入れる前に手元で何が読み込まれるかを見るほうが確実です。見方はclaude plugin detailsでプラグインのコンテキスト消費を測るにまとめています。

導入手順と前提ツール

導入は、マーケットプレイスの登録とプラグインのインストールの2段です。

/plugin marketplace add awslabs/agent-plugins
/plugin install aws-serverless@agent-plugins-for-aws

シェルから入れる場合はclaude plugin marketplace addとclaude plugin installが同じ引数を取ります。チームのリポジトリで共有するなら--scope projectを付けます。ただし、設定に書かれるのは「有効にする」という記録だけで、各メンバーは自分の環境で一度インストールが要ります。@形式とフラグの使い分けはclaude plugin installの導入経路の記事が詳しいです。

プラグインが動くには、手元に次のものが要ります。

• AWS認証情報(AWS CLIで設定済みであること)
• SAM CLI
• Docker互換のコンテナランタイム(sam_local_invokeとコンテナビルドに使う)
• jq(フックが使う。無いと検証が飛ばされる)
• uv(MCPサーバーがuvxで起動する)

aws sts get-caller-identity
sam --version
docker --version
jq --version
uv --version

最初の1行で認証が通らなければ、以降のデプロイ系の操作は全部失敗します。先に確かめておくと原因の切り分けが早くなります。

最初の依頼で言語とIaCを指定する

プラグインの既定は、言語がTypeScript、IaCがCDKです。指定がなければ必ずこの組み合わせで生成する、とskillに書かれています。SAMやPythonで進めたいなら、依頼の中で明示します。

Pythonで、SQSキューをトリガーにするLambdaを作ってください。
IaCはSAMを使います。まず設計案と、使うイベントソースの設定を示してください。

これは書き方の一例です。「use SAM」「use Python」「use CloudFormation」といった指定が、skillに上書きの書式として定義されています。SAM前提で既存のテンプレートを育てているプロジェクトでは、最初の1回でこれを言わないと、CDKのスタックが生成される可能性があります。CDKで進める場合の流れはClaude CodeでAWS CDKスタックを書くが対応します。

設計から検証までの流れ

プラグインが想定している流れを、検証の観点で並べ直します。

手順4を確実に踏ませるには、CLAUDE.mdに順序を書いておきます。

## Lambdaの作業手順(aws-serverlessプラグイン使用)
 
テンプレートかハンドラーを変えたら、次の順で進めて結果を読む。
 
1. `template.yaml`を保存し、フックの検証結果を確認する
2. `sam_build`でビルドする
3. `events/`のJSONを使って`sam_local_invoke`を1回実行する
4. `sam_deploy`は自分から呼ばない。変更内容を要約し、人の依頼を待つ

ツール名はMCPサーバーのドキュメントにある名前のとおりです。Bashのsamコマンドを直接叩く場合の線引きは、Claude CodeでAWS Lambda(SAM)を開発する記事に設定例があります。

設計の段階でClaudeが持っている数字

aws-lambdaskillは、よく突き当たる制限を表で持っています。設計相談で「このペイロードは同期呼び出しで通るか」と聞いたとき、この表が根拠になります。

実際の上限はアカウントごとに違うことがあります。skillもaws lambda get-account-settingsでの確認を勧めています。

書き込み権限が既定で有効という点

このプラグインで最も注意が要るのは、MCPサーバーの権限です。

一方、sam_logsが返すLambdaとAPI Gatewayのログは、--allow-sensitive-data-accessを足さない限り既定では取れません。書き込みは開き、ログは閉じている、という組み合わせです。

askルールでデプロイだけ止める

Claude Codeの権限ルールは、プラグイン同梱のMCPサーバーをmcp__plugin_<プラグイン名>_<サーバー名>__<ツール名>の形で指定します。このプラグインなら、プラグイン名がaws-serverless、サーバー名がaws-serverless-mcpです。

{
  "permissions": {
    "ask": [
      "mcp__plugin_aws-serverless_aws-serverless-mcp__sam_deploy",
      "mcp__plugin_aws-serverless_aws-serverless-mcp__deploy_webapp",
      "mcp__plugin_aws-serverless_aws-serverless-mcp__configure_domain",
      "mcp__plugin_aws-serverless_aws-serverless-mcp__update_webapp_frontend",
      "mcp__plugin_aws-serverless_aws-serverless-mcp__update_frontend"
    ]
  }
}

フロントエンドの更新ツールは、READMEの書き込み一覧がupdate_frontend、ツール定義の節がupdate_webapp_frontendと別の名前で書いています。README内で表記が割れているため、両方を並べています。存在しない名前のルールは何にも一致せず、害はありません。

守るべき規則が2つあります。

• MCPのルールに括弧は付けられません。括弧付きのmcp__ルールは読み込み時に捨てられ、claude doctorの出力に出ます。引数で絞りたい場合は--disallowedToolsを使います
• 同じ操作はBashのsam deployでも実行できます。MCP側だけ止めても、Bash側のaskが空なら抜け道になります。両方に置いてください

ESM系のツール(esm_guidanceなど)は書き込み一覧に入っていますが、ドキュメント上はテンプレートを生成するだけで、デプロイには人の明示的な確認が要ると書かれています。

SAM検証フックの動き方と、効かない場面

フックはPostToolUseのイベントで、対象はEditとWriteです。スクリプトは、編集されたパスがtemplate.yamlかtemplate.ymlで終わるときだけsam validate --template <ファイル> --lintを実行します。タイムアウトは120秒です。

挙動は次のとおりです。

• 検証が通れば「SAM template validation and linting passed.」を返す
• 失敗すれば出力をそのままメッセージにして返す。Claudeはそれを読んで直せる
• jqかsamが無いときは、検証を飛ばした旨のメッセージを返して終わる
• スクリプトの終了コードは常に0。結果はメッセージで伝わるだけで、編集そのものを巻き戻したり、止めたりはしない

効かないのは、パスがtemplate.yaml系でないときです。infra/api.yamlのように名前を変えたSAMテンプレートや、CDKのスタックは対象外です。CDKを使う場合の検証は、別のMCPサーバーで補います。CloudFormationとCDKをMCPで検証する方法はaws-iac-mcp-serverの使い方にあります。

フックが邪魔なら、skillの説明にあるとおり/hooksから無効にできます。

Deploy on AWSプラグインとの使い分け

同じリポジトリにあるdeploy-on-awsは、構成の提案・コスト見積もり・IaCデプロイを担います。aws-lambdaとaws-serverless-deploymentの両方のskill説明に、非サーバーレスのアプリはdeploy-on-awsを使うよう書かれています。

構成が決まる前はdeploy-on-aws、Lambdaに決まってからはaws-serverlessという順に並べると、役割が重なりません。

つまずきやすい点

skillのトラブルシューティング表には、気づきにくい症状も載っています。

• Stack is in ROLLBACK_COMPLETEは前回のデプロイ失敗の跡で、aws cloudformation delete-stackで消してから再デプロイする
• EventBridgeのイベントが黙って落ちるのは、再試行を使い切ってもDLQが無いとき
• durable functionsが再開しないときは、lambda:CheckpointDurableExecutionとlambda:GetDurableExecutionStateの権限が足りない

プラグインのインストール直後に「packages are not installed」と出る場合は、別の原因です。対処は該当エラーの記事に書いています。

本番運用に使う前に

リポジトリのREADMEは、生成したコードとコストを必ず人が確認すること、AWS認証情報に最小権限を使うこと、生成したIaCにセキュリティスキャンをかけることを勧めています。MCPサーバーのドキュメントも、本番向けには読み取り専用の既定を保ち、書き込み用と読み取り用でIAMロールを分けるよう案内しています。

READMEの冒頭には、このリポジトリの後継として「Agent Toolkit for AWS」が公開されたとの案内もあります。リポジトリは引き続き動作し、貢献も受け付けますが、有用なものは時間をかけて後継へ移っていく、という書き方です。プラグイン名や配布経路は将来変わる可能性があるため、導入時にはREADMEの最新の案内を一度見ておくと安全です。