TL;DR
-
Claude Code の Agent Skill として、Azure の
gpt-image-2でテキストから画像を生成する仕組みを作りました。 - 作り方は Kiro 流の仕様駆動開発（Spec-Driven Development, SDD）。
要件 → 設計 → タスク → 実装を Claude Code のスラッシュコマンドで段階的に進めます。 - 設計の肝は「Claude に API を手書きさせない」「パラメータは検証付き CLI 引数 +
.envで既定値を設定」の2点。 - この記事では、SDD の進め方・スキルの構成・Git からの導入 / グローバルインストール /
.env既定設定まで、実際の生成画像つきで解説します。
なぜ「仕様駆動開発」なのか
LLM にいきなり「画像生成スキルを作って」と頼むと、それっぽいコードは出てきますが、
- API の呼び出しがハードコードされ、検証もエラー処理も曖昧
- 要件と実装の対応が追えず、レビューもしづらい
- あとから「ここ仕様どうだっけ？」が発生
になりがちです。
Kiro 流の SDD は、これを次の3フェーズ + 実装に分け、各フェーズで人間がレビュー・承認してから次へ進みます。
Phase 1: 要件 (requirements.md) ← EARS 形式で「何を」
Phase 2: 設計 (design.md) ← アーキテクチャと契約で「どう」
Phase 3: タスク (tasks.md) ← 実装可能な単位に分解
Phase 4: 実装 (TDD) ← テスト先行で1タスクずつ
ドキュメントが残るので、要件 ↔ 設計 ↔ タスク ↔ コードのトレーサビリティが確保できるのが最大の利点です。
この記事の
/kiro:*コマンドは cc-sdd（OSS）が提供します。 cc-sdd は Kiro 互換の仕様駆動開発を Claude Code・Cursor・Gemini CLI などに導入するツールで、steering/spec-init/spec-requirements/spec-design/spec-tasks/spec-implのスラッシュコマンドと、.kiro/配下のテンプレート・ルール一式を用意してくれます。導入はワンコマンドです。npx cc-sdd@latest --lang ja --os windows # mac / linux も指定可本スキルも、この cc-sdd による仕様駆動開発で開発しました。
作るもの：gpt-image-2 画像生成 Skill
Claude Code 上で「画像を生成して」と頼むと、自動的にスキルが読み込まれ、Azure AI Foundry にデプロイした gpt-image-2 を呼び出して画像をローカル保存します。
設計の中心方針
-
モデル（Claude）に API を手書きさせない。 生成ロジックは自己完結した Python スクリプトに閉じ込め、Claude は
SKILL.mdの手順どおりスクリプトを呼ぶだけ。再現性と安全性を担保します。 -
パラメータは検証付き CLI 引数 + 妥当なデフォルト。 必須は
--promptのみ。size/quality/formatなどは検証付きの名前付き引数として公開し、未指定なら.envまたは組み込み既定を使います。
生成サンプル
実際にこのスキルで生成した画像です（プロンプトを変えるだけ）。
| プロンプト（要約） | 生成結果 |
|---|---|
| 秋の居心地のよいブックカフェ、暖かい照明、シネマティック |  |
| 夜明けの霧の山脈、パノラマ |  |
| ファッション誌ドラマ風の人物相関図（日本語ラベル付き） |  |
冒頭のバナーもこのスキルで生成 → 仕上げに Pillow でリサイズしたものです。
仕様駆動開発の実際の流れ
Claude Code のスラッシュコマンド（cc-sddのコマンドパック）で進めます。
Phase 0〜1：ステアリングと要件
/kiro:steering # プロジェクト全体のルール・文脈を生成
/kiro:spec-init gpt-image_specs.md
/kiro:spec-requirements gpt-image-2-skill
gpt-image_specs.mdはClaudeと壁打ちした要件書です。
要件は EARS 形式（When ... the system shall ...）で記述します。たとえば size 制約の要件はこうなりました。
### Requirement 3: パラメータ値の検証（size 制約）
1. If `--size` の両辺のいずれかが 16px の倍数でないとき、
then the 画像生成スクリプト shall API を呼び出さずにエラーを返す。
2. If `--size` の長辺が 3840px を超えるとき、then ... エラーを返す。
...
Phase 2：設計
/kiro:spec-design gpt-image-2-skill -y
このフェーズで Web 検索により Azure の公式 API 仕様を実際に確認しました（後述の「ハマりどころ」参照）。設計は次のレイヤード構成に。
ユーザー依頼 → Claude（SKILL.md）→ generate_image.py
├─ config : .env / 環境変数読み込み
├─ validation : size 制約・依存関係の検証
├─ auth : Entra ID 優先・APIキー代替
├─ client : API 呼び出し・リトライ
└─ storage : Base64 デコード・保存
依存方向は Types → Config → Validation/Auth → Client → Storage、CLI が統括する一方向に固定。各層が単体テスト可能になります。
Phase 3：タスク分解
/kiro:spec-tasks gpt-image-2-skill -y
要件・設計から実装タスクを生成。各タスクには対応する要件 ID（_Requirements: 3.1, 4.2_）と境界（_Boundary:_）が付き、並列実行可能なタスクには (P) マークが付きます。
Phase 4：TDD 実装
/kiro:spec-impl gpt-image-2-skill 1,2,3 # タスク 1〜3 を実装
Kent Beck の RED → GREEN → REFACTOR に従い、テストを先に書いてから実装。最終的に 82 件のテストが通る状態になりました。
$ python -m pytest -q
......................................................... (82 passed)
セキュリティ設計：シークレットを「載せない」
生成 AI 連携で最重要なのが認証情報の扱いです。このスキルでは徹底して：
- 認証情報は 環境変数 /
.envからのみ取得 -
SKILL.mdやスクリプトに直書きしない（モデルのコンテキストに載るため） - キー・トークンを stdout / stderr / ログ・例外メッセージに一切出力しない
- 認証は Entra ID（キーレス）を優先し、API キーは代替
# auth.py（抜粋）：Entra ID 優先・失敗時は API キーへフォールバック
def resolve_auth(api_key, credential=None):
if credential is None:
credential = _default_credential()
if credential is not None:
try:
token = credential.get_token(TOKEN_SCOPE)
return AuthHeader("Authorization", f"Bearer {token.token}")
except Exception:
pass # Entra ID 不可 → API キーへ
if api_key:
return AuthHeader("api-key", api_key)
raise AuthError("有効な認証情報が見つかりません ...") # ← キー値は含めない
導入方法
1. Git リポジトリからダウンロード
git clone https://github.com/potofo/gpt-image.git
cd gpt-image
スキル本体はリポジトリ内の .claude/skills/gpt-image-2/ にあります（SKILL.md / scripts/ / requirements.txt で自己完結）。
2. グローバルインストール（全プロジェクトで使う）
個人用スキルディレクトリ ~/.claude/skills/ にコピーすると、どのプロジェクトを開いてもスキルが有効になります。
macOS / Linux
mkdir -p ~/.claude/skills
cp -r .claude/skills/gpt-image-2 ~/.claude/skills/
pip install -r ~/.claude/skills/gpt-image-2/requirements.txt
Windows (PowerShell)
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse -Force ".claude\skills\gpt-image-2" "$env:USERPROFILE\.claude\skills\"
pip install -r "$env:USERPROFILE\.claude\skills\gpt-image-2\requirements.txt"
コピー後、Claude Code を再起動すると gpt-image-2 スキルが認識されます。「画像を生成して」と頼めば自動で読み込まれます。
プロジェクト単位で使いたい場合は、
.claude/skills/gpt-image-2/をそのプロジェクトに置くだけでOKです。
3. デフォルトの環境設定（.env）
認証情報と生成パラメータの既定値は .env から読み込めます。テンプレートをコピーして編集します。
cp .env.example .env # Windows は Copy-Item .env.example .env
.env の探索ルール：
- スキル実行時、カレントディレクトリから上位へ辿って最初の
.envを使用 -
OS 環境変数が優先、
.envは未設定分のみ補完
Azure 接続設定
# 必須
AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com
AZURE_OPENAI_DEPLOYMENT=gpt-image-2
# API キー認証を使う場合のみ（未設定なら Entra ID キーレス認証）
AZURE_OPENAI_API_KEY=
# 既定: 2025-04-01-preview（gpt-image-2 には 2025-04-01-preview 以降が必須）
AZURE_OPENAI_API_VERSION=2025-04-01-preview
生成パラメータの既定値（地味に便利）
GPT_IMAGE_* で、よく使う設定を .env に固定できます。優先順位は CLI 引数 > .env > 組み込み既定。
# 常に横長・高画質 PNG を ./assets に出力する例
GPT_IMAGE_SIZE=1536x1024
GPT_IMAGE_QUALITY=high
GPT_IMAGE_FORMAT=png
GPT_IMAGE_OUTPUT_DIR=./assets
| パラメータ | 環境変数 | 既定 | 取り得る値 |
|---|---|---|---|
| size | GPT_IMAGE_SIZE |
1024x1024 |
WxH（制約あり） |
| quality | GPT_IMAGE_QUALITY |
high |
low/medium/high
|
| format | GPT_IMAGE_FORMAT |
png |
png/jpeg
|
| background | GPT_IMAGE_BACKGROUND |
auto |
auto/transparent
|
| compression | GPT_IMAGE_COMPRESSION |
100 |
0–100（JPEG のみ） |
| n | GPT_IMAGE_N |
1 |
1–10
|
| output | GPT_IMAGE_OUTPUT_DIR |
./images |
任意のパス |
これで --prompt だけ渡せば、毎回フラグを書かずに好みの設定で生成できます。
注意：
.envは秘密情報を含むので 絶対にコミットしない。.gitignoreに.envを入れ、.env.exampleだけを追跡しましょう。
使い方
Claude Code から（自然言語）
「Azure で水彩画風の富士山の画像を作って」
と頼むだけ。Claude がスキルを読み込み、スクリプトを実行して保存先パスを返します。
CLI から直接
# 既定の正方形 PNG を ./images に
python scripts/generate_image.py --prompt "桜並木の通学路、アニメ風"
# 透過 PNG（ロゴ・アイコン向け）
python scripts/generate_image.py --prompt "ミニマルな山のロゴ" \
--background transparent --format png
# 複数枚を任意フォルダへ
python scripts/generate_image.py --prompt "猫のキャラクター案" --n 4 --output ./out
成功すると保存ファイルの絶対パスが stdout に出ます。ファイル名は <プロンプト由来のタイトル>_<タイムスタンプ>_<連番>.<拡張子> で一意になります。
ハマりどころ（実際に踏んだ罠）
仕様駆動開発の「設計フェーズで一次情報を確認する」習慣のおかげで、事前に潰せたもの／実装中に気づいたものを共有します。
1. gpt-image-2 の size 制約が独特
任意解像度をサポートしますが、次をすべて満たす必要があります。
- 両辺が 16px の倍数
- 長辺 3840px 以下
- アスペクト比 3:1 以下
- 総ピクセル数 655,360〜8,294,400
たとえば「1208×512 のバナーを」と頼まれても、1208 は 16 の倍数でなく、総画素も下限割れ。そこで 1280×512 で生成し、Pillow で 1208×512 にリサイズする、という運用にしました。検証ロジックが API 呼び出し前にエラーを返すので、無駄な課金を防げます。
2. api-version が古いと gpt-image-2 が動かない
ポータルが例示する 2024-02-01 は DALL·E 3 世代のもので、gpt-image-2 では 2025-04-01-preview 以降が必須。設計時の Web 調査で気づき、既定値を 2025-04-01-preview にしました。
3. ドキュメントの表記ゆれ
公式ドキュメントのコード例コメントに background / output_format を「GPT-image-1 only」と書く箇所と、本文で「両対応」と書く箇所があり、表記がゆれています。実装時は使用する api-version で実挙動を検証するのが安全です。
4. DefaultAzureCredential の冗長ログ
Entra ID が使えない環境だと azure-identity が長大なエラーログを stderr に吐きます（機能的にはフォールバックして成功します）。気になる場合はログレベル調整で抑制可能です。
まとめ
- 仕様駆動開発で作ると、要件 → 設計 → タスク → コードが一直線につながり、レビューも保守もしやすい。
-
Agent Skill の勘所は「Claude に API を手書きさせない」「検証 + デフォルトを
.envで外出し」。 - Azure
gpt-image-2特有の size 制約 / api-version は設計フェーズの一次情報確認で先回りできた。
生成 AI を「呼ぶ側」のツールを作るとき、仕様駆動開発はかなり相性が良いと感じました。Claude Code のスラッシュコマンドで段階的に進められるので、個人開発でも導入のハードルは低いです。
リポジトリ
git clone https://github.com/potofo/gpt-image.git
- スキル本体:
.claude/skills/gpt-image-2/ - 仕様一式:
.kiro/specs/gpt-image-2-skill/（requirements / design / tasks / research） - ライセンス: MIT
この記事のサンプル画像はすべて本スキル（Azure gpt-image-2）で生成しました。