Software MansionのAgentic Engineering Guideを要約してみた

Software MansionがAgentic Engineering Guideというドキュメントを公開しています。AIエージェントをプロのソフトウェア開発に取り入れるための実践的な知見をまとめたもので、読んで面白かったのでポイントを日本語でまとめてみました。

Part 1: Getting Started

Agentic Engineeringとは

"Agentic engineering is professional software development with AI agents as active collaborators."

単なるコード補完やコード生成ではなく、AIエージェントがリポジトリを自律的に探索し、ツールを使い、複数ステップにわたるタスクを完遂する開発スタイルのことです。

重要な前提として、「成果の責任は常に人間にある」という原則が強調されています。エージェントに任せっきりにするのではなく、レビュー可能な変更・明確なプロンプト・品質管理を維持することが前提になっています。

まず何から始めるか

ガイドは2つの入り口を提示しています。

パスA — 新規プロジェクト ゼロからエージェントと一緒にプロジェクトを立ち上げます。技術スタックの知識がなくても問題なく、アイデアの検証から初期実装まで一気通貫で進められます。

パスB — 既存プロジェクト すでに動いているコードベースに参加する場合。未知のシステムを素早く理解し、外科的な変更を加える用途での活用です。

共通して強調されているのは「読むだけでは習得できない」という点です。実際にプロンプトを書き、差分を確認し、エージェントの誤りを追跡し、修正を依頼するサイクルを繰り返して初めて身につきます。

Part 2: Becoming Productive

日々の開発でエージェントを使いこなすための実践的なパターンを扱います。ガイドの中核となる節です。

ワークフローの基本

会話の単位をスレッドと呼び、理想的な1スレッドは5ステップで完結します。

モデルの限界を理解する

ガイドが挙げる主な制約は6つです。

制約	内容
知識の陳腐化	学習時点以降のAPI変更などは知らない
学習不可能性	セッションをまたいで改善しない（メモリ機能で補う）
コンテキスト劣化	スレッドが長くなると初期の指示が効かなくなる
非決定性	同じプロンプトでも結果が変わることがある
意図のズレ	人間の意図を誤解することがある
コンテキストの有限性	広くぼんやりしたプロンプトより、小さく焦点を絞ったものが優れる

プロンプト技法

実装前にフレーミングする

コードを書かせる前に、まず企画書を作らせます。問題・期待する結果・やらないこと・選択肢・未解決の疑問点を含む短い文書です。これによりエージェントが意図を理解しているという錯覚を防げます。

ソクラティック質問法

答えを与えるのではなく、エージェントが自力で結論にたどり着けるよう質問を投げかけます。「この仮定は常に成り立つか？」「エッジケースではどうなるか？」といった問いかけが有効です。

あえて情報を省く（アンダープロンプティング）

意図的に情報を少なくすることで、エージェントが独自に深く探索します。ドキュメントの抜けを発見する副次効果もあります。

知識はリポジトリに残す

チャット履歴には残りません。事実や決定事項は AGENTS.md やリポジトリ内のMarkdownに記録し情報源として機能させます。

Red/Green TDD

テストを先に書いて失敗を確認してから実装させるサイクルは、不要なコード生成を減らし、テストスイートを堅牢にします。

知識チェックポイント

計画をMarkdownファイルにまとめてコミットしてから実装開始。失敗したときに計画まで戻れるため、無駄な再計画が減ります。

リバースエンジニアリング

圧縮・コンパイル済みのコードを読み解くのはエージェントの得意分野です。真似したいWebサイトやAndroid APKをエージェントに渡すと、必要なツールを自ら選択しながら解析を進めてくれます。

並列実装

複数の解決策が考えられるとき、git worktree などで複数のエージェントに同時実装させて比較します。インターフェース設計など創造的な作業に特に有効です。

ハーネスエンジニアリング

プロンプトだけを磨くのではなく、エージェントを取り巻くツール・指示・コンテキスト全体を設計するというアプローチです。ガイドでは5つの手段が紹介されています。

AGENTS.md

リポジトリ内でエージェントを操舵するための最軽量な方法。以下を書くと効果的です。

エージェントが推測できないBashコマンド
テストランナーの設定・実行方法
ブランチ命名などリポジトリのルール
アーキテクチャ上の決定事項や非自明な挙動

逆に書くべきでないのは、コードから読み取れる情報や変更頻度が高い内容です。

Claude Code では AGENTS.md はデフォルトで読み込まれません。Claude Code を使う場合は CLAUDE.md が相当するファイルです。AGENTS.md は OpenAI Agents SDK や GitHub Copilot Workspace など他のエージェント向けの慣例です。

スキル

繰り返し使うドメイン知識やワークフローをパッケージ化したもの。SKILL.md を含むディレクトリとして実装し、エージェントが明示的に読み込む形で使います。複雑なルール定義や特定ツールチェーンのドキュメントに向いています。なお、サードパーティ製スキルは更新時にソースを必ずレビューしてください（悪意ある変更が混入するリスクがあります）。

MCP（Model Context Protocol）

外部サービス（Linear、Figma、Slack など）への認証済みアクセスが必要なときに使います。ただし、MCPツールの情報はすべてシステムプロンプトに注入されるため、数が増えすぎるとエージェントの能力が低下します。gh CLIで代替できる GitHub MCP など、CLIで十分な場合は使わないほうが得策です。

サブエージェント

メインのエージェントが限定的・並列化可能なタスクを別のエージェントに委譲する仕組みです。長い会話で蓄積した探索ノートや失敗試行がメインスレッドを圧迫するのを防ぎ、コンテキストを分離することが主な目的です。

Hooks

毎回必ず実行すべきロジックはモデルに覚えさせるのではなくHooksに任せます。コードフォーマット、linter実行、センシティブなコマンド前の承認などが典型例です。Hooksは判断不要な機械的処理に使い、判断が必要なものは指示として書くのが設計の基本です。

手段	使いどき
AGENTS.md / CLAUDE.md	同じ情報を毎回プロンプトに書いている
スキル	再利用可能な知識・ワークフローをまとめたい
MCP	外部サービスへの認証アクセスが必要
サブエージェント	タスクを分離してメインスレッドを軽くしたい
Hooks	毎回必ず実行する決定論的なロジック

フィードバックループを閉じる

エージェントが自律的に問題を診断・修正できるようにするには、適切なフィードバックループを用意する必要があります。

テストを書く

バグを見つけたらまず再現テストを書いてから修正させましょう。ただし、エージェントが書くテストは 今まさに直したバグ だけを通過させるような、ピンポイントすぎる検証になりがちです。一見テストが増えていても、別の場所で同じ問題が起きたときに気づけない。そういう穴があることを意識してレビューする必要があります。

ログとDBアクセスを与える

アプリのログを *.log ファイルに出力するようにしておくと、エージェントがランタイムの動作を確認できます。また psql や sqlite3 でデータベースに直接アクセスできる環境を整えておくと、エージェントの調査能力が大きく上がります。

CLIを活用する

エージェントはCLIを通じて環境を操作します。エージェントが使いやすいCLIの設計原則は以下の通りです。

非インタラクティブ化 — すべての入力をフラグで渡せるようにする
--help を充実させる — サブコマンドに実行例を含める
stdin を受け付ける — パイプラインで使えるようにする
高速に失敗する — エラーメッセージを明確にする
べき等にする — 同じコマンドを何度実行しても結果が変わらないようにする
--dry-run を用意する — 破壊的操作の事前確認ができるようにする
--yes フラグ — 確認プロンプトをスキップできるようにする
一貫した構造 — resource + verb のようなパターンを守る

WebフロントエンドのQA自動化

フロンティアモデル¹はブラウザ操作も得意です。Cursor Browser や Claude in Chrome などのツールを使うと、UIのQAをエージェントに任せられます。複数エージェントを並列で動かす場合はインスタンスごとに異なるポートを割り当てましょう。

モバイルアプリのQA自動化

シミュレータを使ったモバイルアプリのテストも自動化できます。Argent（Software Mansion製）や Radon AI などのツールが対応しています。

セキュリティ

エージェントを実用的にするツール群（ファイルアクセス、コード実行、ネットワーク通信）は、制御が不十分だとデータ漏洩や悪意ある操作の入り口にもなります。能力を排除するのではなく、能力を適切に管理するというのがエージェントセキュリティの基本的な考え方です。

危険なトリフェクタ（3つの条件が揃うと危険）

1つのエージェントが以下の3つを同時に持つと攻撃面が一気に広がります。

条件	具体例
プライベートデータへのアクセス	独自コードベースやローカルシステム
信頼できないコンテンツへの露出	悪意あるプロンプト、Web検索結果、ツールのレスポンス
外向きの通信能力	ネットワークアクセスや副作用を持つ操作

どれか1つを取り除くだけでリスクは大きく下がります。ただし、コーディングエージェントは現実的にこの3つのうち少なくとも2つを持つことが多く、完全な隔離は難しいです。なお、攻撃者は外部だけとは限りません。不注意な同僚や放置されたプロセスも同等のリスクです。

実際に起きた事故

攻撃者が作成したIssueが過剰な権限を持つAIワークフローを起動し、キャッシュポイズニング²と悪意あるパッケージの公開につながった
承認なしにTerraformコマンドを実行できる状態のエージェントが、本番インフラを削除した
悪意あるリポジトリのIssueがエージェントを誘導し、自動生成されたプルリクエスト経由でプライベートデータが流出した

セキュリティ対策

パーミッション（人間の承認ゲート） 書き込み・ネットワーク呼び出し・破壊的操作に対して人間の承認を挟む。読み取りは基本フリー。ただしパターンマッチの限界もあり、ユーザーの摩擦にもなる。

信頼済みワークスペース（Trusted Workspace） エージェントをセーフモードで動かし、プロジェクトレベルの設定ファイルや潜在的に悪意ある設定の読み込みを拒否する。

サンドボックス OS/ランタイムレベルで境界を設け、ファイルシステムへの書き込みをワークスペースディレクトリに限定し、センシティブなパスを保護し、プロセスの起動を制限する。

ネットワークアクセスの制限 デフォルトでネットワークを無効化し、ライブブラウジングの代わりにキャッシュ済み検索結果を使うことでプロンプトインジェクション³への露出を下げる。

Hooks プロジェクト固有のセキュリティポリシーをHooksとして実装する。たとえば特定のシェルコマンドをブロックするなど。

運用方針

これらの保護はすべて無効化できます（いわゆるYOLOモード⁴）。推奨はまずデフォルトの保護を有効にした状態で始め、ワークフローの要件と脅威評価に基づいて選択的に調整していくというアプローチです。セキュリティと利便性はトレードオフですが、デフォルト保護のまま作業できる場合はそれを維持するのが賢明です。

生産性を10倍にするには

並列エージェント

人間1人が複数のエージェントを並行制御することが、生産性向上のポイントです。git worktree で各エージェントに独立したチェックアウトを与えると競合が防げます。

コード品質の維持

「モデルはタスク完了で報酬を得るように訓練されており、長期的なアーキテクチャ責任を持たない」という認識が重要です。対策として：

小さく境界を明確にしたモジュール設計 — 「認証・DB・ビジネスロジック・UI」をそれぞれ独立したモジュールに分け、エージェントが1タスクで触る範囲を限定する。巨大な utils.ts にすべてが混在していると、エージェントは無関係な関数まで書き換えがちになる。
型とテストによる不変条件の強制 — 例えば UserId を string ではなく type UserId = string & { _brand: "UserId" } のようにブランド型にしておくと、エージェントが誤って生の文字列を渡したときにコンパイルエラーで気づける。テストも同様で「この関数は必ずXを返す」という仕様をテストで明文化しておけば、エージェントが壊したときに即検出できる。
エージェント向けのlinterとCI — ESLintやBiomeのルールをCIに組み込み、エージェントのPRがマージされる前に自動でチェックされる仕組みを作る。エージェントはCIが通れば完了と判断するため、CIが厳しいほど品質が安定する。
リポジトリ内での知識管理 — AGENTS.md や docs/decisions/ にアーキテクチャ上の決定や禁止事項を書いておく（例：「このプロジェクトではクラスを使わない」「外部APIの呼び出しは必ず src/lib/api/ 経由」）。エージェントは毎回ゼロから文脈を読むので、コードより先にこれらのファイルを読むよう指示すると一貫性が保たれる。

自動コードレビュー

実装と並列でレビューを実行すると、人間レビュアーの負担を軽減できます。ただし完全自動化ではなく、適切なコンテキストを与えることが鍵です。

やってはいけないこと（アンチパターン）

1. 1スレッドに複数の責任を持たせる スレッドには1つのタスクだけを持たせましょう。責任が増えるほど集中が散漫になります。

2. モデルの記憶力を信頼する モデルは学習データに依存します。関連するドキュメントやソースコードを都度提示しましょう。

3. 仮定を積み重ねる 各ステップを確認しながら進めましょう。人間が実行していないコードと同じく危険です。

4. 黙って従うことを許す エージェントに「疑問があれば聞く」「おかしいと思ったら指摘する」権限を与えましょう。

5. スレッドを腐らせるまで使い続ける 新しいタスクは新しいスレッドで始める方が、劣化したスレッドをデバッグするより常に安上がりです。

6. 質問に解決策を埋め込む 「〇〇する方法を教えて」ではなく「複数のアプローチを探索して」と指示し、その後選択肢を評価させましょう。

7. 初回案を最終版と見なす 複数回の試行と人間によるレビューを前提にしましょう。

Part 3: Expanding Horizons

より深いメンタルモデルと、エージェントを組織・自動化規模で運用するための発展的な話題を扱います。オプション扱いですが、規模を拡大したい人には特に参考になります。

エージェントの艦隊を動かす

ここまでは1人のエンジニアが1つのエージェントを操作する文脈でした。ガイドの後半では、複数のエージェントを同時に走らせるフェーズへの移行が語られています。問いかけが「エージェントに何をさせるか」から「どうエージェントの群れを管理するか」へと変わります。

並列エージェントの実行

独立したタスクを複数のエージェントセッションで同時に実行します。各エージェントは git worktree で独立したチェックアウトを持ち、互いに干渉しません。人間はそれぞれのセッションをリアルタイムで監視するのではなく、出力をまとめて非同期にレビューします。

なおサブエージェント（親エージェントが子エージェントを生成してコンテキストを分割する仕組み）とは別の概念です。並列エージェントはそれぞれが独立したタスクを持ちます。

並列エージェント（人間が管理）

サブエージェント（エージェントが管理）

スケジュール実行と定期エージェント

エージェントをcronジョブやCIパイプラインのように定期実行できます。典型的なユースケースは以下の通りです。

毎日のIssueトリアージ
CI失敗のサマリー生成
リリースノートの下書き
リグレッション検出

人が呼んだときだけ動くツールからスケジュールに従って勝手に動くプロセスへ。実行結果は自動で保存されるか、レビュー待ちとして通知されます。

Issueトラッカー連携

IssueボードをAIが監視し、関連するIssueに対して自動的にエージェントを起動するパターンです。エージェントはCI結果・PRフィードバック・複雑度分析などのエビデンスを収集し、人間がクローズ前にレビューできる形で提示します。ワークフローの定義はコードと同じリポジトリにバージョン管理されます。

エージェント間の通信

複数エージェントの連携には2つの主要なパターンがあります。

Hub-and-spoke: リードエージェントがワーカーを生成し、出力を収集して集約します。シンプルですが、中間の詳細が積み重なってリードのコンテキストが劣化するリスクがあります。

協調チーミング: エージェントがタスクリストを共有し、各自が独立してタスクを引き受け、直接通信します。リードのコンテキストを清潔に保てますが、設計が複雑になります。

連携の深さに応じて、実装は3段階に分類できます。

レベル	説明
1	独立したワーカーが呼び出し元に出力を返す
2	共有ファイルや集約結果を持つオーケストレーション
3	タスクグラフを共有しメッセージングで直接通信する協調チーム

コードファクトリー

エージェントが自律的にコードを書いてプルリクエストを開き、別のレビューエージェントが機械的に検証するループです。

重要な注意点として、品質ゲートが堅牢でないと自動化しないほうがましな状態になります。粗悪なPRが自動マージされ続ける状況は、自動化なしより悪いです。

エンジニア1人が「会社」を動かす

コードファクトリーのパターンが成熟すると、1人のエンジニアがかつてはチーム規模が必要だった仕事をこなせるようになります。コミュニケーションプラットフォーム・スケジューラー・外部サービスと接続したエージェント群を、個人が運用する形です。

この変化により、競争優位は「自分でコードを書く速さ」より「エージェントの群れをどれだけうまく指揮できるか」に移行しつつあります。

コーディング以外への応用

エージェントの活躍の場はコード生成に限りません。プロジェクト管理や運用業務にも幅広く使えます。いずれも共通する原則はエージェントの出力は人間がレビューしてから実行・公開するという点です。

Issueトリアージ 受信したIssueのタグ付け・重複検出・追加質問の依頼・深刻度による優先付けを自動化します。スケジュール実行で新しいIssueを処理し、本当に人間の判断が必要なものだけをエスカレーションします。

カスタマーサポート ドキュメントや過去の解決事例をもとに繰り返しの問い合わせに対応します。ハルシネーション⁵防止のためのリフレクション機構⁶を必ず組み込むこと、そしてエージェントだけでチケットをクローズさせない（少なくとも異議申し立ての手段を残す）という点がガイドで強調されています。

ミーティングの議事録作成 会議の文字起こしから決定事項・未解決の問い・担当者付きのアクションアイテムを抽出します。手作業でやりがちな情報整理をエージェントに任せられます。

インシデント対応 本番障害のスタックトレースを調べて根本原因を特定し、最近の変更との相関を探り、修正案を提示します。人間がレビューする前段階の調査をエージェントが担います。

リリースノートの下書き コミットメッセージとPRの説明からリリースノートを生成します。最終的な文章の仕上げと精度確認は人間が行う必要があります。

依存関係の管理 メジャーバージョンアップが安全かどうかの評価や、脆弱性のある依存パッケージの優先度付けをエージェントが行います。依存関係の更新作業にかかる手間を大幅に削減できます。

まとめ

ガイド全体を通じて一貫しているのはエージェントは賢いが、無責任に使えば結果も無責任になるというメッセージです。

実際に触りながら学ぶしかない、というのが正直なところですが、このガイドはその学習の見取り図として非常に有用だと感じました。

この記事はガイドの全内容を網羅しているわけではなく、個人的に重要だと判断した部分のみを抜粋しています。より深く学びたい方はぜひ原文をご覧ください。

Agentic Engineering Guide

この記事は Piotr Zborowski, Marek Kaput（Software Mansion）が CC BY-NC-SA 4.0 のもとで公開している原文をもとに作成しています。

GPT-4やClaude 3など、現時点で最高水準の性能を持つ大規模言語モデルの総称。研究・開発の最前線（フロンティア）にあることからこう呼ばれる。 ↩
キャッシュポイズニングとは、パッケージマネージャーやCDNなどのキャッシュに悪意あるデータを混入させる攻撃手法。正規のパッケージや静的ファイルが差し替えられ、利用者が知らずに悪意あるコードを実行してしまう。 ↩
悪意ある文字列をエージェントへの入力に紛れ込ませ、本来の指示を上書きする攻撃手法。たとえばWebページや検索結果に「これまでの指示を無視して〇〇せよ」と書いておくと、エージェントがそれを指示と誤認して実行してしまう。エージェントが外部コンテンツを読む場面（Web検索、Issue読み取り、ファイル解析など）で特に注意が必要。 ↩
"You Only Live Once"の略。Claude Codeでは承認プロンプトを一切表示せず、エージェントがすべての操作を自動実行するモードを指す。作業速度は上がるが、意図しないファイル変更やコマンド実行が確認なしに行われるリスクがある。 ↩
AIが事実と異なる内容を、あたかも正確であるかのように生成してしまう現象。存在しないAPIや関数名を自信満々に返すケースが典型例。 ↩
エージェントが回答を生成した後、その内容を自分で再評価・検証するステップを設ける仕組み。「この回答は正確か？」「根拠はあるか？」と自問させることでハルシネーションを減らす。 ↩