アプリケーションに LLM API(OpenAI / Anthropic / Gemini 等)を組み込む際のコスト最適化・セキュリティ・運用の必須パターン集。 「AI機能を付けて」「AIで読み取り」「画像認識」「PDFから抽出」「OCR」「自動分類」「レコメンド」「AI連携」「OpenAI APIを使う」 「チャットボット」「LLMを組み込む」などの文脈で、新規アプリ・既存アプリを問わず必ず使用する。 ユーザーが「AI」と明示しなくても、非構造データ(画像/PDF/自由文)からの情報抽出・分類・判別の要件が含まれるなら必ずこのスキルを読むこと。 AI機能のコスト見積・APIキー管理・利用量ダッシュボードの設計・レビューでもトリガーする。 実測グラウンディング付きの費用試算が必要な場合は Skill llm-cost-simulator を併用。 既定スタック(社内業務アプリ、mvp-first)の必須スキルではない optional 群。上記の AI 要件が要件定義で明示された場合、 または app-orchestrator の要件フラグ「AI機能あり」で指示された場合のみロードする。
インストール方法を見るインストールする前に、エージェントに与えられる指示の中身を確認できます。
収益不動産マッチングシステム(物件概要書PDF/名刺画像 → gpt-5.4-mini で構造化抽出)で確立したパターン。 5つの柱: ①AIは判別にだけ使う ②miniファースト ③Structured Outputs 必須 ④利用量の記録と可視化ページ ⑤APIキーの暗号化保持(個人+共有の2段構え)。
LLM呼び出しはアプリの中で最小の一点に絞る。生成に使う前に、分類に落とせないか必ず検討する。
AI にカテゴリ判定だけさせ、カテゴリごとの文言・処理はコード側に持つ。出力トークンが激減し、品質も安定する。
// AI がやるのはこれだけ(出力は数トークン)
property_type: "apartment_building" | "office_building" | "hotel"
| "store" | "warehouse" | "land" | "other" | null
// 説明文・アイコン・後続処理はコード側の定義を引く(AI に書かせない)
const PROPERTY_TYPE_LABELS: Record<PropertyType, string> = { ... }
抽出タスクでは幻覚を仕組みで抑え、人間のレビューに繋ぐ:
low_confidence_fields: string[] をスキーマに必ず含め、換算した値・不鮮明な値のフィールド名を列挙させるexport const DEFAULT_MODEL = "gpt-5.4-mini"; // コスト重視の既定
export function extractionModel(env: AppEnv): string {
return env.OPENAI_MODEL || DEFAULT_MODEL;
}
推論系モデル(GPT-5系等)は、判別・抽出タスクなら推論強度を最低にする。コストとレイテンシが大きく下がる:
...(model.startsWith("gpt-5") ? { reasoning: { effort: "low" as const } } : {}),
「言われすぎない」ためのガードは入力側に置く:
detail は用途で選ぶ(細かい文字を読むなら high、分類だけなら auto/low)自由テキストを返させて JSON.parse で祈るのは禁止。json_schema + strict: true で出力をスキーマに強制する(パース失敗・リトライループが消える = コスト削減でもある):
const response = await client.responses.create({
model,
input: [
{ role: "system", content: systemPrompt },
{ role: "user", content: [contentPart, { type: "input_text", text: instruction }] },
],
text: {
format: { type: "json_schema", name: schemaName, strict: true, schema },
},
});
const data = JSON.parse(response.output_text) as T;
input_file(data URL)、画像は input_image で直接渡せる(OpenAI Responses API)AI 機能を持つアプリには利用状況ページを必ず1枚作る。「いくら使ったか分からない AI 機能」はリリースしない。
// AI ラッパーの戻り値に usage を必須で含める
return {
data: JSON.parse(text) as T,
usage: {
inputTokens: response.usage?.input_tokens ?? 0,
outputTokens: response.usage?.output_tokens ?? 0,
},
};
// 呼び出し側は必ず DB に記録(usage_log テーブル)
await insertUsage({
userEmail: user.email,
kind: "ai_extract",
model: extractionModel(env),
inputTokens: usage.inputTokens,
outputTokens: usage.outputTokens,
detail: { doc: "property", keySource: resolved.source }, // 何に・どのキーで使ったか
});
// 価格改定に追従できるよう単価はコードにハードコードしない
OPENAI_PRICE_IN_USD_PER_M=0.25
OPENAI_PRICE_OUT_USD_PER_M=2.0
USD_JPY_RATE=155
「会社で1個の共有キー」と「利用者が自分で入れる個人キー」を両立させる。解決順は 個人 → 共有 → なし:
export async function resolveApiKey(env: AppEnv): Promise<ResolvedApiKey> {
const user = await getUser();
// 1. 本人が設定した暗号化キー(D1に保存)
if (env.KEY_ENCRYPTION_SECRET) {
const row = await getUserApiKeyRow(user.email);
if (row) {
try {
const apiKey = await decryptSecret(row.key_ciphertext, env.KEY_ENCRYPTION_SECRET);
return { user, apiKey, source: "personal" };
} catch (error) {
console.error("api key decrypt failed:", user.email, error);
// マスターキー変更等で復号不能 → 共有キーにフォールバック
}
}
}
// 2. 会社の共有キー(wrangler secret / 環境変数)
if (env.OPENAI_API_KEY) return { user, apiKey: env.OPENAI_API_KEY, source: "shared" };
// 3. キーなし → AI機能だけ無効。アプリ自体は動く
return { user, apiKey: null, source: null };
}
keySource(personal/shared)も記録し、誰のキーで呼んだか追跡できるようにするユーザーがアプリ画面から入れるキーは平文で DB に置かない。マスターシークレット(wrangler secret 等、環境のシークレットストア)で AES-GCM 暗号化して保存する:
KEY_ENCRYPTION_SECRET(任意の長いランダム文字列)を SHA-256 で 256bit 鍵に正規化base64(iv || ciphertext) を DB に保存crypto.subtle)で実装できるので外部ライブラリ不要(Workers/Node 両対応)/^sk-[A-Za-z0-9_-]{20,}$/)。不正形式は保存前に弾くKEY_ENCRYPTION_SECRET 未設定ならこの機能自体を無効表示にする(中途半端に平文保存しない)AI が使えない状態でもアプリは成立させる:
aiAvailable: boolean を含め、キー未設定なら手入力・無料OCRモードで同じフローを完走できるようにするmode=store: 原本ファイルだけ保存)を用意すると、無料運用とAI運用を同じAPIで切り替えられる設計時:
実装時:
運用機能:
まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
アプリ・Webサービス・業務ツールの制作を、証拠分析→確定的な初稿→要件定義→体験設計→機能分解→実装→品質ゲート→リリース判定の手順ゲート制で進めるスキル。質問で要件を埋めるのではなく、依頼文・既存コード・資料・ログから最有力案を選び、動く成果物を先に出して差分で改善する。ユーザーが「アプリを作りたい」「ツールを作って」「〜を自動化したい」「システム化したい」「要件定義」「仕様を決めたい」「UI/UXを設計して」「体験を良くしたい」「機能を洗い出して」「MVPを決めたい」「品質チェック」「リリースしていいか判断して」などと言ったら必ず使用する。外部データの取込・マスタ・締め処理を伴う業務システムでは references/data-lifecycle.md も併用する。新規・既存を問わずアプリの制作・改善・リニューアルで使用する。
Webアプリの準備→要件定義→設計→実装→公開→品質ゲートを実行する内部オーケストレーター。Claude Codeの /build-app /improve-app、Codexの $build-app / $improve-app から明示的に委譲された場合、custom agent起動時、または利用者が $app-orchestrator を明示した場合だけ使用する。一般のアプリ相談から暗黙起動しない。
run-extract-blueprint が生成した章別ブループリントの忠実性を独立 context で評価したいとき、事実/推測区別と粒度と被覆を検証し draft_hash に束縛した PASS/FAIL verdict をローカル品質ゲート (C01 の周回内の受入判定・差し戻し) へ渡したいときに使う。
確認点で利用者が見る深さを選んだあと打ち合わせ資料を作り手とは別の目で確かめたいとき、正確さ・言葉・見た目・シンプルさの指摘を資料の編集なしで受け取りたいときに使う。
生成した handout 資料が初心者に伝わるか読みやすさレビューを依頼したいとき、独立 context のレビュアーから指摘と根拠つきの verdict を回収したいときに使う。
Notion ページを描画する直前に粒度を検証したいとき、info-collector-agent ページと同等の section 充足度を section_canonical_map 基準で機械検証したいときに使う。