🤔 「AIがコードを書けるようになったら、ソフトウェア設計なんてもう要らないのでは?」多くの人がそう感じ始めています。この記事は、その直感がまったく逆だと教えてくれます。 コーディングは、要件理解・設計・コーディング・検証・サポートという5つの活動のうちの1つに過ぎません。人間の開発者は、設計書が多少あいまいでもチームの暗黙知や経験で補えます。しかしAIコーディングエージェント（AI-SDE）にはそれができません。設計情報が明示的に存在しなければ、既存のコードを再利用すべき場面で気づかず重複コードを生成してしまい、成熟したシステムを修正するたびに複雑さが積み重なっていきます。 さらに興味深いのは、設計の「経済学」自体が変わるという指摘です。これまでのオブジェクト指向やクラス階層は「人間が書くコード量を減らす」ためのものでした。AIによる実装コストがほぼゼロに近づく時代には、複雑な再利用構造を組むより、AIに振る舞いをシンプルに説明できる設計の方が価値を持つようになります。問いは「どう書く量を減らすか」から「AIが実装する前提で、何が最良の設計か」へと変わっていくのです。 Software Design in the Age of AI: Why AI coding makes software design more important AIが速く安くコードを書けるようになるほど、それを支える設計の質こそが問われる時代になりそうです。 #ソフトウェア設計# #AIエージェント#

"Learning Software Architecture" というタイトルの記事から。 ・ソフトウェア設計は、実際のプロジェクトを通じて実践で学ぶのが一番 ・プログラミングにおいてコード以上に重要なのはアーキテクチャ ・アーキテクチャ以上に重要なのは組織の社会的な問題 ・科学（研究に近い）向けのコードが産業界のコードと異なるのは、開発者の知識の差ではない ・これは、3ヶ月後に論文を出す、といったインセンティブ構造の違いによる ・プロジェクトのインセンティブ構造自体を設計できる機会は稀だが、できれば非常に効果的になる ・構造を変えられない場合は、諦めて制約の中で最善を尽くすしかない ・筆者は rust-analyzer の開発において、コントリビューターの層に合わせたアーキテクチャを採用した ・中核部分には優秀な開発者を惹きつけるため、依存関係を減らしてビルドを徹底的に高速化 ・周辺機能には週末だけプログラミングできる層を集めるため、各機能を完全に独立させた ・周辺機能の品質基準も正常系が動けばOKとして、クラッシュが全体に波及しない仕組みを作っておいた （つまり、コントリビューターが取り組みやすい構造を設計に取り入れて、社会構造に対応しようとした） ・ただ、適応を優先して実験的に作ったコードが、そのまま本番運用され続けるリスクもあるが ・なお、ソフトウェア設計の真理が1冊にまとまった本は存在しない ・それでも、おすすめの書籍や講演はいくつかある ・APoSDとか、Software Engineering at Googleとか

# AIエージェントをソフトウェアに組み込むプラクティス # 階層化メモリ 🎯 「全部コンテキストに詰め込む」設計は、ウィンドウ溢れとハルシネーションの永続化を同時に引き起こします。 メモリを3層に分けるだけで、コンテキスト効率と記憶の信頼性を両立できます。 🔥 解決する課題 エージェントが複数ターンに跨がるタスクを扱うとき、すべての情報をコンテキストウィンドウに詰め込む「フラット記憶」では2つの問題が同時に起きます。会話履歴・ユーザ属性・中間結果・外部知識が混在するとウィンドウが溢れ、古い情報から押し出されて文脈が断絶します。さらにLLMが生成した推測をそのまま永続化すると、ハルシネーションが長期記憶に定着し、以降のセッションを汚染し続けます。 💡 提案パターン メモリを作業記憶（ターン内の中間状態）・短期記憶（セッションストア、TTL付き）・長期記憶（ベクトルDB/KVS）の3層に分離します。作業記憶は自由に読み書きし、コンテキストリセットで消えます。短期記憶には信頼度タグを付与し、ユーザ発話由来は高信頼、LLM推測由来は低信頼とマークします。長期記憶への昇格には反復確認やユーザ承認を要求し、ハルシネーションの永続化を防ぎます。failure_costが高い領域ほど昇格閾値を厳しくし、TTLを長めにとって安全側に寄せます。 ✅ 選定条件 使うとき： - 複数セッションにわたって情報を引き継ぐ必要がある - 中間結果の量がコンテキストウィンドウの30%を超える見込みがある - 確定事実と推測の区別が必要で、誤った記憶の波及影響が大きい 使わないとき： - 1ショットで完結しセッション間の引継ぎが不要な場合 - コンテキストウィンドウに全情報が収まる場合 - メモリの書込制御だけが課題で、階層分離自体は不要な場合 ⚠️ 落とし穴 - 作業記憶と短期記憶の境界が曖昧になりがちです。外部ストアへの書込を境界線にし、LLMの内部状態に頼らないでください - 長期記憶のエントリ数が増えると無関係な記憶がコンテキストに混入し、ハルシネーションの原因になります - マルチエージェント構成で各Workerが直接長期記憶に書き込むと整合性が崩れます。長期記憶はSupervisorが一元管理しましょう 🔧 実装方針 - 作業記憶（dict/インメモリ）・短期記憶（Redis等TTL付きセッションストア）・長期記憶（ベクトルDB）の3層を明確に分離し、外部ストアへの書込を境界線とします - recall時はコンテキスト予算内で3層から関連情報を想起し、関連度と信頼度でランク付けして注入量を制御します - 短期→長期への昇格には信頼度スコアの閾値チェックと承認状態の検査を設け、未検証情報の永続化を防ぎます - 記憶種別ごとにTTLを設計し（リアルタイムデータは分単位、ユーザ嗜好は週単位、不変属性は無期限）、failure_costが高いほど短めに設定します #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # 読取自由・書込ゲート 🎯 「全ツール呼び出しに承認を求める」設計は、承認疲れで自壊します。 読取と書込を非対称に扱うだけで、安全性と生産性の両立が実現できます。承認すべき操作に人間の注意を集中させましょう。 🔥 解決する課題 エージェントのツール呼び出しには副作用のある操作とない操作が混在しています。すべてに一律の承認を求めると、読取が大半を占める実運用では承認疲れが発生し、肝心の書込操作の承認が形骸化してしまいます。かといってすべてを自由にすれば、不可逆な書込操作で取り返しのつかない変更が走るリスクが残ります。 💡 提案パターン ツール呼び出しを「読取（検索・取得・参照）」と「書込（作成・更新・削除・送信）」に二分し、読取は自由に許可、書込にだけ認可・検証・承認・監査のゲートを設けます。R/W分類はツール定義時に静的に付与し、LLMの判断には委ねません。書込ゲートの厳格度は可逆性で段階化し、不可逆操作（メール送信・決済）は人間承認必須、可逆操作（下書き保存）はポリシー検証のみとします。これにより承認疲れを劇的に減らしつつ、副作用の安全性を維持できます。 ✅ 選定条件 使うとき： - 読取と書込が混在し、読取が多数を占める - 不可逆な書込操作（メール送信、決済、本番DB変更）が含まれる - 承認疲れを防ぎ、人間のレビュー帯域を高リスク操作に集中させたい 使わないとき： - 読取自体が機密データへのアクセスを含む場合（個人情報検索など）は、読取にも認可が必要 - 全操作が読取専用で書込がそもそも存在しない場合 - 実験環境で全操作が可逆かつ低コストな場合 ⚠️ 落とし穴 - R/W分類をLLMに任せてはいけません。インジェクションで書込ツールが「読取」と判断される経路を作ります - 「読取だが副作用がある」操作（API呼び出し回数カウント、閲覧履歴記録など）を見落とさないでください - 可逆な書込と不可逆な書込を同じ厳格度にすると、承認疲れの問題が再発します 🔧 実装方針 - ツール定義時にtype（read/write）とgate種別（none/auto/human_approval）を静的に付与し、実行時にLLMが分類を変更できない構造にします - 読取パスではメタデータのみをログに記録し、書込パスでは入力検証・ゲート判定・実行・監査ログの全量記録をパイプラインとして実装します - 書込ゲートの厳格度をreversibleフラグで段階化し、不可逆操作にはdry-runの前段必須化も組み合わせます - ゲート判定ロジックはゲートウェイ層のコードで強制し、プロンプトによる制御は一切使用しません #AIエージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # 読取自由・書込ゲート 🎯 「全ツール呼び出しに承認を求める」設計は、承認疲れで自壊します。 読取と書込を非対称に扱うだけで、安全性と生産性の両立が実現できます。承認すべき操作に人間の注意を集中させましょう。 🔥 解決する課題 エージェントのツール呼び出しには副作用のある操作とない操作が混在しています。すべてに一律の承認を求めると、読取が大半を占める実運用では承認疲れが発生し、肝心の書込操作の承認が形骸化してしまいます。かといってすべてを自由にすれば、不可逆な書込操作で取り返しのつかない変更が走るリスクが残ります。 💡 提案パターン ツール呼び出しを「読取（検索・取得・参照）」と「書込（作成・更新・削除・送信）」に二分し、読取は自由に許可、書込にだけ認可・検証・承認・監査のゲートを設けます。R/W分類はツール定義時に静的に付与し、LLMの判断には委ねません。書込ゲートの厳格度は可逆性で段階化し、不可逆操作（メール送信・決済）は人間承認必須、可逆操作（下書き保存）はポリシー検証のみとします。これにより承認疲れを劇的に減らしつつ、副作用の安全性を維持できます。 ✅ 選定条件 使うとき： - 読取と書込が混在し、読取が多数を占める - 不可逆な書込操作（メール送信、決済、本番DB変更）が含まれる - 承認疲れを防ぎ、人間のレビュー帯域を高リスク操作に集中させたい 使わないとき： - 読取自体が機密データへのアクセスを含む場合（個人情報検索など）は、読取にも認可が必要 - 全操作が読取専用で書込がそもそも存在しない場合 - 実験環境で全操作が可逆かつ低コストな場合 ⚠️ 落とし穴 - R/W分類をLLMに任せてはいけません。インジェクションで書込ツールが「読取」と判断される経路を作ります - 「読取だが副作用がある」操作（API呼び出し回数カウント、閲覧履歴記録など）を見落とさないでください - 可逆な書込と不可逆な書込を同じ厳格度にすると、承認疲れの問題が再発します 🔧 実装方針 - ツール定義時にtype（read/write）とgate種別（none/auto/human_approval）を静的に付与し、実行時にLLMが分類を変更できない構造にします - 読取パスではメタデータのみをログに記録し、書込パスでは入力検証・ゲート判定・実行・監査ログの全量記録をパイプラインとして実装します - 書込ゲートの厳格度をreversibleフラグで段階化し、不可逆操作にはdry-runの前段必須化も組み合わせます - ゲート判定ロジックはゲートウェイ層のコードで強制し、プロンプトによる制御は一切使用しません #AIエージェント# #ソフトウェアアーキテクチャ#

なんかソフトウェアの保守性とか、どうでもいいんじゃね？という気がしてきてしまった。 10万行のWPFアプリを、Fable 5が1日でReactに移植しきったんよね。テストさえちゃんと維持していれば、「保守できなくなったらきれいな設計で作り直す」で良くね？ってちょっと思ってしまった。

# AIエージェントをソフトウェアに組み込むプラクティス # Risk-based Human Approval｜リスクベース人間承認 🎯 エージェントに「全部お任せ」も「全部確認」も間違いです。操作のリスクに応じて自動実行・人間承認・禁止を動的に振り分けるのが正解です。 🔥 解決する課題 エージェントが外部システムに副作用を持つ操作を実行できるとき、すべてを自動実行すれば不可逆な損害が起きえます。しかしすべてに人間承認を求めれば待ち時間で業務が止まり、エージェントの自動化の価値が消失します。LLMに「危険だと思ったら聞いて」と指示しても、その判断自体が確率的でありすり抜けが起きます。 💡 提案パターン 操作をリスクスコア（不可逆性 x 失敗コスト）で3層に分類します。低リスク（読取・可逆操作）は自動実行、中〜高リスク（不可逆または高コスト）は人間承認を経由、極高リスク（不可逆かつ致命的）は禁止とします。分類はLLMではなく決定論的なルールエンジンで行い、承認タイムアウト後のデフォルトは安全側（自動却下）に倒します。さらに段階的自律性（Autonomy Ladder）により、エージェントの実績に応じて閾値を動的に調整する仕組みも設計できます。 ✅ 選定条件 使うとき： - エージェントが書込・削除・送信など副作用を伴う操作を実行する - 操作によって不可逆性と失敗コストが異なり、一律ポリシーでは過剰か不足になる - 人間がレビューに関与できる運用体制がある 使わないとき： - すべての操作が読取専用で副作用がない - 失敗コストが一律に低くロールバックが容易 - レイテンシ要件が極めて短く人間介在を許容できない ⚠️ 落とし穴 - リスク分類自体をLLMに任せてはいけません。分類は決定論的なコードかポリシーエンジンの責務です - 承認待ちの状態を永続化しないと、プロセス再起動で承認待ち操作が消失します - 条件付き承認（パラメータ修正して実行）を設計に含めないと、却下と再提案のラウンドトリップが増えます 🔧 実装方針 - リスク分類はツール名×アクション名の静的テーブルまたはポリシーエンジンで行い、LLMには委譲しません - リスクスコアは不可逆性（reversibility）と失敗コスト（failure_cost）の積で算出し、閾値で3層（auto/approval/forbidden）に振り分けます - 承認待ち状態は耐久的なストア（キュー＋永続化）に保持し、プロセス再起動で消失しない設計にします - 承認タイムアウト時のデフォルト動作は安全側（自動却下）に倒します - リスクポリシーはYAML等の宣言的設定として外部化し、コード変更なしでルール追加・変更できるようにします #AIエージェント# #ソフトウェアアーキテクチャ#

# 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エージェント# #ソフトウェアアーキテクチャ#

# AIエージェントをソフトウェアに組み込むプラクティス # ツールゲートウェイ・MCP仲介 🎯 エージェントのツール呼び出し、全部「野良API」になっていませんか？ AIエージェントが複数のツールやMCPサーバを直接呼び出す構成は、認可漏れ・二重実行・監査不能の温床です。単一のゲートウェイを挟むだけで、セキュリティの一貫性が劇的に変わります。 🔥 解決する課題 エージェントが外部ツールを直接叩く構成では、認可・レート制限・ログがツールごとにバラバラになります。プロンプトインジェクションで悪意ある引数が混入しても個別ツール側では弾けず、権限昇格や意図しない操作が起きえます。さらに呼び出しログが分散し、「誰の権限で・なぜこのツールが呼ばれたか」の事後追跡コストが跳ね上がります。 💡 提案パターン 全ツール呼び出しを単一のゲートウェイ層に集約し、認可・入力サニタイズ・レート制限・監査ログを一元管理します。タスク種別やユーザ権限に応じてツールを動的にスコーピングし、LLMに不要なツールを見せない設計にします。書込系ツールには操作単位の細粒度認可とHITL承認を、読取系にはカテゴリ単位の緩い認可を適用する非対称ポリシーが鍵です。ツールの追加・削除もゲートウェイの設定変更だけで完結し、エージェント本体のコード変更は不要になります。 ✅ 選定条件 使うとき： - エージェントが複数ツールを呼び出し、少なくとも一つが副作用を持つ - ユーザ入力や外部データがツール引数に含まれうる（input_trustが低い） - 「どのツールが・どの引数で・誰の権限で呼ばれたか」の説明義務がある 使わないとき： - ツールが1つだけかつ読み取り専用で、ゲートウェイのオーバーヘッドが見合わない - 全ツールが社内信頼済みの実験環境で、まずプロトタイプ速度を優先したい ⚠️ 落とし穴 - ゲートウェイ自体が単一障害点になります。ヘルスチェックと縮退モード（読取のみ許可など）の設計が必須です - 認可やサニタイズをプロンプトで行ってはいけません。「このツールは使わないで」はインジェクションで迂回されます - レート制限はセッション単位だけでは不十分です。大量セッション攻撃に備え、グローバル単位との二層で設けましょう 🔧 実装方針 - ゲートウェイのポリシーをYAML等の宣言的定義で管理し、ツールごとにtype（read/write）・認可粒度・レート制限・サニタイズ・ログレベルを設定します - タスク種別・ユーザ権限・会話フェーズに応じてLLMに露出するツールを動的にスコーピングし、不要なツールを選択肢から除外します - ヘルスチェックと縮退モード（読取のみ許可）を設け、ゲートウェイ障害時にもシステム全体が停止しない設計にします - MCPサーバ間のスキーマ不統一をゲートウェイ層で正規化し、エージェントには一貫したインターフェースを提供します - 高リスクなコード実行はサンドボックスへルーティングし、長時間セッションには短命の権限リースで権限範囲を時間制限します #AIエージェント# #ソフトウェアアーキテクチャ#