# AIエージェントをソフトウェアに組み込むプラクティス # Dry-run & Commit｜差分提示してから実行 🎯 LLMがハルシネーションしたパラメータで決済が走る。それ、dry-runで防げます。 Terraformの plan → apply と同じ発想をエージェントのツール呼び出しに適用。「何が変わるか」を見てから実行する二相プロトコルです。 🔥 解決する課題 LLMはハルシネーションで意図しないパラメータを生成することがあり、ツール呼び出しは副作用を伴います。この二つが掛け合わさると、存在しないリソースIDや桁違いの金額で不可逆な操作が実行されるリスクが生まれます。dry-runなしの直接実行では、人間が「エージェントが何をしようとしているか」を確認する手段がなく、問題は事後にしか検出できません。 💡 提案パターン 副作用を伴う操作を「計画（dry-run）→ 差分提示 → 承認 → 実行（commit）」の二相で行います。dry-runフェーズではシステムを一切変更せず差分だけを計算し、承認を得てからcommitフェーズで書込を実行します。承認方式はリスクに応じて段階化し、高リスクは人間承認、中リスクはポリシー自動検証、低リスクは自動承認とします。planにはTTLを設け、状態変化が起きていたら再生成を強制します。 ✅ 選定条件 使うとき： - 不可逆な操作（データ削除、外部API書込、課金処理）をエージェントが実行する - 誤操作が金銭的・法的・運用的な実害を生みうる - 差分を評価するための数秒〜数分の待機が許容される 使わないとき： - 全操作が読み取り専用の場合 - 全操作が可逆かつ低コストの場合（チャット応答生成など） - レイテンシ制約が極めて厳しく承認待ちが許容されない場合 ⚠️ 落とし穴 - planとcommitの間に状態が変わるTOCTOU問題があります。commit時に前提条件を再検証する設計が必須です - 外部APIがdry-runモードを提供していない場合は、パラメータ検証とシミュレーションで代替し「推定」であることを明示します - commitエンドポイントがplan IDなしで呼べると、dry-runを迂回できてしまいます 🔧 実装方針 - ツール実行をdry-run（差分計算のみ）→承認→commit（実行）の三段階パイプラインとして構成し、各フェーズを独立したエンドポイントに分離します - planオブジェクトに変更前後の値・影響範囲・ロールバック手順・前提条件のハッシュを含め、commit時に前提条件の再検証（TOCTOU対策）を行います - commitエンドポイントは有効なplan IDと承認トークンの両方を必須パラメータとし、直接呼び出しによるdry-run迂回を構造的に防止します - planにTTLを設定し、期限切れの場合は再planを強制することで、古い差分に基づく実行を防ぎます #AIエージェント# #ソフトウェアアーキテクチャ#

# Claude Agent SDKの便利で実践的な使い方 ✅ 危険な操作の前にユーザー承認を求め、6 種類の応答パターンで柔軟に制御できます。 承認とユーザー入力の処理は、`canUseTool` コールバックで危険操作を検知してユーザーに確認を求め、`AskUserQuestion` で要件収集を行う機能です。 📌 タイトル：承認とユーザー入力を処理する 🔗 URL： 🧩 概要 `canUseTool` で各ツール呼び出しをインターセプトし、承認/拒否/代替案提案など 6 パターンの応答が可能です。`AskUserQuestion` ツールでは、Claude がユーザーに複数選択肢の質問を投げて要件を収集できます。 🛠 使い方 `canUseTool` コールバックを定義し、ツール名・引数に基づいて `PermissionResultAllow` / `PermissionResultDeny` を返します。 🏗 実践的な使い方 ・ファイル削除や Bash 実行を検知して y/n を問う対話的承認 UI を構築します。「全 Bash コマンドを `/tmp/sandbox` にスコープ」のように変更を加えて承認することも可能です。 ・「承認して記憶」パターンで `updated_permissions` を使い、`.claude/settings.local.json` に永続化します。 ・`AskUserQuestion` で「モバイルアプリのテックスタック」について選択肢を提示し、`plan` モードと組み合わせて変更前に要件収集する対話ワークフローを実現します。 💡 ユースケース 🛡 危険操作の対話的承認 UI 📋 複数選択肢による要件収集 🔐 承認ルールの永続化による学習 ⚠️ 注意点 サブエージェントでは AskUserQuestion は使用できません。質問は 1〜4 個、選択肢は 2〜4 個の制限があります。Python では `can_use_tool` にストリーミングモードとダミー PreToolUse フックが必要です。 #ClaudeAgentSDK# #AI#

ハーネスエンジニアリングのプラクティス P17. ドライラン既定とブラスト半径プレビュー 🎯 ポイント 「40ポッドを再起動します」は事後に発見するのではなく、事前に提示するものです。副作用は実行前にプレビューしましょう。 📝 概要 副作用を伴う行為は、まず効果のプレビュー（どのファイル・どの行・どのポッド）を出し、ゲートまたは人間確認を経てから実行します。既定はドライラン（実行しないで結果を表示）とし、明示的な承認があってから実行します。 🔍 解説 エージェントが「何をするか」を事前に知ることは、安全性の基本です。コードの差分プレビュー、影響を受けるサービスのリスト、再起動されるポッドの数、送信されるメッセージの内容。これらを実行前に提示することで、人間は情報に基づいた判断ができます。特にインシデント対応では、是正案のブラスト半径（影響範囲）とロールバック計画をセットで提示し、承認後に実行・監視するパターンが有効です。ドライランを既定にすることで、「うっかり実行」のリスクを構造的に排除します。 🛠 実践方法 ・副作用を伴う全操作に「プレビューモード」を実装し、実行前に影響範囲を表示します ・ドライランの出力に「影響ファイル数」「影響ポッド数」「変更行数」等の定量情報を含めます ・不可逆な操作にはドライランを必須にし、可逆な操作ではオプションにして効率を保ちます ・ドライラン結果と実行結果の乖離を記録し、ドライランの精度を継続的に改善します 💼 ユースケース ・インシデント対応で、是正アクションのブラスト半径とロールバック計画を事前提示する場面 ・ペアプログラミングで、エージェントの編集を適用前に差分プレビューとして表示する場面 ・マイグレーションで、各ユニットの変更内容をカナリアとして一部先行適用し、問題がないか確認する場面 ⚠ 落とし穴 ドライランが常に正確とは限りません。ドライランでは問題なくても、実行時に環境の違いで失敗することがあります。また、ドライランが形骸化して「常にスキップ」になると意味がなくなります。P15（取り消し可能性）と組み合わせて、可逆な操作はドライランなしで即実行、不可逆な操作のみドライランを必須とする設計が効率的です。 #HarnessEngineering# #AIAgent#

【こりっちチケット！】公式アプリをリリースしました！（管理画面もアプリから） 団体様の管理画面も、お客様の予約・入場も、アプリひとつで完結します。 ■ 団体様もアプリからご利用いただけます 団体管理・公演管理の画面を、アプリからそのまま操作できます。 稽古場や仕込みの合間、移動中にも、ブラウザを開いてログインし直すことなく、予約状況の確認や公演情報の更新が行えます。 ■ お客様側に起きる変化 ・公演ページから日時・席種を選んで、クレジットカードやPayPayでそのまま購入できます ・購入後すぐに電子チケットが発行され、当日はQRコードを提示するだけで入場できます ■ ダウンロードはこちら（無料） iPhone： Android： 現在ご利用中のアカウントで、そのままログインいただけます。 ■ お客様へのご案内のお願い 公演ページやSNSで、上記URLをお客様にもご案内いただけますと、当日の受付がよりスムーズになります。 なお、既に公開中の公演も含め、団体様側での設定や切り替えは必要ありません。アプリを入れていないお客様も、これまでどおりブラウザからご予約・ご入場いただけます。

ハーネスエンジニアリングのプラクティス P17. ドライラン既定とブラスト半径プレビュー 🎯 ポイント 「40ポッドを再起動します」は事後に発見するのではなく、事前に提示するものです。副作用は実行前にプレビューしましょう。 📝 概要 副作用を伴う行為は、まず効果のプレビュー（どのファイル・どの行・どのポッド）を出し、ゲートまたは人間確認を経てから実行します。既定はドライラン（実行しないで結果を表示）とし、明示的な承認があってから実行します。 🔍 解説 エージェントが「何をするか」を事前に知ることは、安全性の基本です。コードの差分プレビュー、影響を受けるサービスのリスト、再起動されるポッドの数、送信されるメッセージの内容。これらを実行前に提示することで、人間は情報に基づいた判断ができます。特にインシデント対応では、是正案のブラスト半径（影響範囲）とロールバック計画をセットで提示し、承認後に実行・監視するパターンが有効です。ドライランを既定にすることで、「うっかり実行」のリスクを構造的に排除します。 🛠 実践方法 ・副作用を伴う全操作に「プレビューモード」を実装し、実行前に影響範囲を表示します ・ドライランの出力に「影響ファイル数」「影響ポッド数」「変更行数」等の定量情報を含めます ・不可逆な操作にはドライランを必須にし、可逆な操作ではオプションにして効率を保ちます ・ドライラン結果と実行結果の乖離を記録し、ドライランの精度を継続的に改善します 💼 ユースケース ・インシデント対応で、是正アクションのブラスト半径とロールバック計画を事前提示する場面 ・ペアプログラミングで、エージェントの編集を適用前に差分プレビューとして表示する場面 ・マイグレーションで、各ユニットの変更内容をカナリアとして一部先行適用し、問題がないか確認する場面 ⚠ 落とし穴 ドライランが常に正確とは限りません。ドライランでは問題なくても、実行時に環境の違いで失敗することがあります。また、ドライランが形骸化して「常にスキップ」になると意味がなくなります。P15（取り消し可能性）と組み合わせて、可逆な操作はドライランなしで即実行、不可逆な操作のみドライランを必須とする設計が効率的です。 #HarnessEngineering# #AIAgent#

# Claude Agent SDKの便利だけど知られていない機能 🌍 コードを変更せずに計画だけ立ててほしい？planモードなら読み取り専用でClaudeが分析・提案します！ Claude Agent SDKのplanモードは、ソースファイルを一切編集せず、読み取り専用ツールだけでコードを探索し、変更計画を立てるモードです。 📌 タイトル：plan モード（読み取り専用のみ実行） 🔗 URL： 🧩 概要 `permission_mode="plan"` を設定すると、Claudeは読み取り専用ツール（Read、Grep、Globなど）と読み取り専用のシェルコマンドだけを使ってコードベースを探索します。Edit、Write、Bashでの書き込み操作は実行されません。要件の明確化が必要な場合は `AskUserQuestion` を使ってユーザーに質問することもあります。コードレビューや変更提案を安全に行いたい場面で最適です。 🛠 使い方 ```python # Python - コードレビュー用のplanモード import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="認証モジュールのセキュリティ問題を分析し、改善計画を提案してください", options=ClaudeAgentOptions( permission_mode="plan", # 読み取り専用で分析 ), ): if hasattr(message, "result"): print(message.result) ``` ```typescript // TypeScript for await (const message of query({ prompt: "Analyze security issues in the auth module and propose a fix plan", options: { permissionMode: "plan" // Read-only analysis } })) { if ("result" in message) console.log(message.result); } ``` 🏗 本番システムへの組み込み方 ・プルリクエストの自動レビューで、コードを変更せず問題点と改善案だけを提示します ・新しいコードベースの調査・理解フェーズで安全に探索できます ・変更を実行する前の「計画フェーズ」として、人間が計画を確認してから実行モードに切り替える運用ができます ・`set_permission_mode()` と組み合わせて、計画承認後に `acceptEdits` に切り替えるワークフローが構築できます 💡 ユースケース 📋 コードレビューで変更提案だけを生成し、実際の変更は人間が判断する 🔍 大規模コードベースのアーキテクチャ分析を安全に行う 📝 リファクタリング計画を立てて、チームで合意してから実行する ⚠️ 注意点 ・読み取り専用のシェルコマンドは実行される場合があります ・`AskUserQuestion` が発生する可能性があるため、完全な無人実行にはdontAskモードの方が適しています ・計画結果を実行に移す場合は、新しいセッションまたは権限モードの動的変更が必要です ✨ 「まず計画、次に実行」のワークフローはエンジニアリングの基本です。planモードで安全に分析し、納得してから変更を実行しましょう！ #ClaudeAgentSDK# #AIAgent#

# AIエージェントをエンタープライズシステムに組み込む意思決定ポイント # Pull vs Push｜エージェントの起動モデル 🎯 ポイント エージェントを「ユーザーが呼んだら動く」だけの設計にしていませんか？実はエージェントの起動トリガには、ユーザーの明示的な要求で動くPull型と、システムイベントで自動起動するPush型の2つがあります。どちらを選ぶかでユーザー体験・負荷特性・権限モデルが根本的に変わります。多くの本番環境ではPullとPushの比率が7:3から5:5に落ち着くのが現実です🔑 📋 概要 Pull型はユーザーが意図を持って質問や指示を出す対話型タスクに適しています。Slack Botへの問い合わせやSalesforceの商談画面からの指示がその典型です。Push型はシステムイベント（Webhook、CDC、スケジュール）をトリガに自動起動し、異常検知や予防的アクションを行います。JiraチケットのSLA超過を検知して自動エスカレーションしたり、夜間バッチで勤怠異常を検出して翌朝是正案を提示したりするケースです。エンタープライズでは両方を組み合わせるハイブリッド構成が一般的です📊 🔍 意思決定のポイント 判断の軸は3つあります。 まず、トリガが明確なシステムイベント（Webhook、CDC、cron）で定義できるかどうか。定義できるならPushを検討してください。 次に、ユーザーの意図やコンテキスト（選択中の画面、直前の操作）が実行に不可欠かどうか。不可欠ならPullを主軸にしましょう。 そして「ユーザーが気づく前に対処する」ことに価値があるかどうか。SLA違反の予防やインシデントの早期検知のように、先手を打つことで損失を防げるならPushが有効です。 両方に該当する場合は、Pushで通知してPullで深掘りするハイブリッド構成が最適解です。Pushを採用する場合は、イベント量の見積もりとスロットリングの設計を必ず行ってください⚡ 💡 要点と詳細 ハイブリッド構成の典型パターンを理解しておくことが重要です： Pushで気づかせ、Pullで深掘り — イベント駆動でサマリ通知を送り、ユーザーが詳細を知りたければ対話に移行します。Zendeskで顧客満足度が急落した際にアラートを飛ばし、担当者が「原因を分析して」と指示する流れです。 Pullの裏でPushを仕込む — ユーザーの問い合わせ対応中に、関連するイベント（同じ顧客の未解決チケット）をバックグラウンドで監視し、追加情報をプロアクティブに提示します。 Push型では権限設計に特に注意が必要です。Pull型はリクエスト発行者のセッションに権限が紐づくため認可モデルがシンプルですが、Push型はユーザーセッションに紐づかないため、どの権限でAPIを叩くかを明確にしないと過剰権限のサービスアカウントを使ってしまうリスクがあります🔄 ⚖️ トレードオフ Push過多は通知疲れを引き起こします。イベントの閾値を適切に設定しないと大量のアラートがユーザーに押し寄せ、Slackチャンネルが未読通知で埋まって結局すべて無視されます。通知の価値がゼロになるだけでなく、本当に重要なアラートも見落とされます😰 一方、Pullのみで運用すると予防機会を逃します。異常を検知できるイベントソースがあるのにPullだけに頼ると、ユーザーが気づいた時にはSLA違反が確定しています。「気づいてからでは遅い」タイプの問題には、Pushが不可欠です。 もう一つの落とし穴はイベントストームです。デプロイ直後やシステム移行時に大量のCDCイベントが発生し、Pushエージェントがバックログを処理しきれずタイムアウトが連鎖する事態は、事前のスロットリング設計で防ぐ必要があります⚠️ 🛠️ ユースケース インシデント対応エージェント（ServiceNow連携）：Push型でP1インシデントの昇格を即座に検知し、オンコール担当への通知と初期分析を自動送信。担当者がPull型で「影響範囲を詳しく分析して」と指示すると、関連システムのログを横断的に調査して報告します。Pushで初動を高速化し、Pullで深掘りするハイブリッドの好例です🏢 勤怠管理エージェント（Workday連携）：夜間バッチのPush型で勤怠異常（残業超過、打刻漏れ）を検出し、翌朝マネージャーに是正案を提示。マネージャーがPull型で「この部門の先月の傾向は？」と質問すると、詳細な分析レポートを生成します📚 営業支援エージェント（Salesforce連携）：商談のステージ変更をPush型で監視し、長期間滞留している案件を自動で営業担当にリマインド。担当者がPull型で「この顧客の過去のサポート履歴をまとめて」と指示すると、Zendeskの対応履歴も含めた総合レポートを生成します🔧 実践のコツ：Push型を導入する際は「通知の閾値設計」から始めてください。全イベントを通知するのではなく、ビジネスインパクトのあるイベントだけを選別する仕組みが必須です。また、Pushエージェントのサービスアカウント権限は最小権限の原則を徹底しましょう💪 #AIエージェント# #エンタープライズアーキテクチャ#

「支持率下げてやる!」でおなじみのオールドメディア各社が、高市総理のX活用にまたブツブツ文句を言ってますね。 「高市首相が連日のX連投!」 「経済政策の実績をアピール!」 「記者会見ではなくSNSで発信!」 「お盆も休まず投稿、体調が心配!」 もはや何を批判したいのか、自分たちでも分からなくなってるんじゃないでしょうか。 本来、事実関係を確認し、発言を正確に伝え、権力と国民の間に情報を流通させることこそマスコミの仕事だったはずなんですけどね。なのにあなた方は「報道の自由!」「国民の知る権利!」を盾にして、好き勝手に編集し、都合の悪い事実は報じず、都合のいい文脈だけ流してきちゃいましたから。 そりゃ総理も直接「一次情報を出すよ!」となるだろうし、国民も脚色や偏向や捏造のない「一次情報を知りたい!」ってなるのは当然のことでしょうよ。自分たちよりもXを優先されてることに文句をタレる前に、あなた方が間に入ることが明らかに迷惑視されてるくらい、自分たちの報道が低次元であることを恥じたほうがいいですよ。 そもそも政府が直接発信を強化したところで、正確に報道してきたメディアなら何にも困らないじゃないですか。政府発表と記事が一致していれば、「やっぱりこの新聞は正確だ!」と信用が高まるだけです。 困るのは、見出しで煽り、発言を切り取り、文脈を削り、記者の願望や「お気持ち」を混ぜ、読者が一次情報まで確認しないことを前提に記事を作ってきた側でしょう。「支持率下げてやる」的な手法も、一次情報と即座に比較検証できる時代には明らかに通用しなくなりますからね。 だから総理も政府も、一次情報をどんどん出せばいいんですよ。 ・誤報には事実関係を提示する。 ・切り取りには全文を公開する。 ・印象操作には一次資料を示す。 ・会見では誰が何を質問し、政治家が何と答えたのか、国民が直接確認できるようにする。 総理や政府のXより翌日の新聞の方が遅い。全文は政府サイトで読める。会見は動画で見られる。統計も一次資料まで辿れる。そんな時代に「我々が政治家の発言を編集して、国民に正しい解釈を教えてあげます!」みたいな昭和型の情報流通を続けてたら、そりゃ読者は離れますよ。 総理のX発信を嘆く暇があったら、「それでも新聞を読む価値がある!」「一次情報を見たうえでも、この記者の記事を読みたい!」と思われる仕事をしてくださいな。あなた方はもはや、監視される側なんですから。

# AIエージェント開発の意思決定ポイント 🎯 **ポイント** AIエージェントに「何でも覚えさせる」のは本当に良いことでしょうか？メモリ書込の積極度は、エージェントの賢さと安全性を左右する最も繊細なダイヤルの一つです。書き込みすぎればメモリ汚染、書き込まなさすぎれば学習しないエージェント。この絶妙なバランスをどう取るか、実務の視点で掘り下げます。 📋 **概要** メモリ書込の積極度とは、エージェントが対話やタスク遂行の過程で得た情報を長期メモリにどれだけ積極的に保存するかを制御するパラメータです。データベースへのINSERTと同じ重みで考えるべき、準不可逆的な操作です。LLMが生成した推測やユーザーの曖昧な発言を安易に書き込むと、以後のすべてのセッションで「過去に記録された事実」として参照され、誤りが自己強化するループ、すなわちメモリ汚染に陥ります。 🔍 **意思決定のポイント** この設定は主に2つの変数で決まります。 🔹 **入力の信頼度（input_trust）** — エンドユーザーの自由入力が主なソースなら、インジェクションや誤情報のリスクが高いため書込ゲートの閾値を上げます。管理者が入力を管理している環境なら、ある程度積極的に書き込めます。 🔹 **失敗コスト（failure_cost）** — 医療・法務・金融では、誤った事実の永続化が深刻な結果を招きます。社内チャットボットなら、多少の誤記憶は修正すれば済みます。失敗コストが高いほど書込を抑制するのが鉄則です。 🔹 **説明責任（accountability）** — 「なぜこの情報をメモリに保存したか」を後から説明できる必要がある場合、出典と確信度を記録する設計が必須になります。 💡 **要点と詳細** 書込の判定基準は3段階で考えるのが実践的です。 ✅ **自動書込可** — ユーザーが直接的かつ明示的に述べた事実（「私の名前は山田です」「Pythonを使っています」） ⚠️ **確認後に書込** — ユーザーの発言から推測される情報（「Python好みのようですね」→ユーザーに確認してから保存） 🚫 **書込禁止** — LLMが生成した推測、外部ソースからの未検証情報、一時的な文脈 メモリエントリには確信度（confidence）タグを付与し、検索時に確信度の低いエントリはランキングを下げるのが効果的です。これにより書込を完全に禁止しなくてもメモリ汚染の影響を限定できます。重複検出も書込パイプラインに必ず組み込みましょう。コサイン類似度0.90〜0.95で既存エントリとの重複をチェックし、同一エンティティの同一属性は最新値で上書きするのが原則です。 ⚖️ **トレードオフ** 📉 書込が消極的すぎると — エージェントが学習しません。ユーザーが繰り返し伝えた好みを記憶せず毎回デフォルトに戻り、「また同じことを聞かれた」という不満を生みます。パーソナライゼーションの欠如は、長期的な関係構築が必要なユースケースで致命的です。 📈 書込が積極的すぎると — ハルシネーションの永続化が最大のリスクです。「おそらくAさんは東京在住でしょう」という推測が「Aさんは東京在住」として保存され、以後のセッションで確定事実として扱われます。さらに深刻なのがプロンプトインジェクションの持続化で、通常は1セッション限りの攻撃がメモリに永続化されると「持続型インジェクション」になります。 🛠️ **ユースケース** 🏥 **医療・法務・金融** — 失敗コストが極めて高い領域。書込は最小限に抑え、明示的に確認された事実のみを記録。出典と確信度の追跡は必須。 💬 **カスタマーサポート** — ユーザーの好みや過去の問い合わせ履歴を蓄積する必要があるが、自由入力のリスクも高い。反復確認された情報（2回以上の一致）のみ自動永続化し、暗黙的な好みは隔離期間を設けてから昇格させる設計が有効。 🏢 **社内ナレッジボット** — 組織の暗黙知（「このAPIはこのパラメータを渡すと壊れる」）を蓄積したい。管理者入力が主なら比較的積極的に書き込めるが、定期的な「メモリの棚卸し」でユーザーに保存情報を提示して確認を得る運用を組み込むと品質が保たれます。 書込ログの監査可能性も忘れずに。いつ・何が・どのソースから書き込まれたかを追跡できれば、メモリ汚染が発覚した場合に原因特定と修正が可能になります。 #AIエージェント# #ソフトウェアアーキテクチャ#