記事一覧へ
## AIエージェントへのプロンプトの極意
私はこの7年間、AIシステムへのプロンプトに費やしてきた。考えられるあらゆるアプローチを試してきた。
今日は、AIエージェントから最大限の成果を引き出すための私のフレームワークを公開する。
AIエージェントへの指示は、チャットボットへの指示とはまったく異なる。チャットボットは「答える」。エージェントは「働く」。ファイルを読み、コードを書き、テストを走らせ、ブラウザを開き、スクリーンショットを撮り、完璧になるまで自分の出力を繰り返し改善する。1時間かけてタスクに取り組み、本物の成果物を持って戻ってくる。
ただし、あなたが「本物」の意味を教えてやればの話だ。
最もよく見かける失敗は、エージェントをかつてのチャットボットのように扱ってしまうこと——一文の指示を与えて、汎用的な回答が返ってくるのを待つパターンだ。しかしエージェントに必要なのは一文ではない。「ブリーフ（業務指示書）」が必要なのだ。
この記事では、エージェントから実際に良い仕事を引き出すブリーフの書き方のフレームワークを説明する。私はそれを「3つのC」と呼んでいる：**Context（文脈）**、**Constraints（制約）**、**Composition（構成）** だ。
---
## 1. Context（文脈）
Contextとは、エージェントがその仕事をするために知っておくべきすべての情報と、アクセスが必要なすべての素材のことだ。状況・目標・対象読者・成功の定義が含まれる。さらには実際の素材も必要だ。デッキ（スライド）、データファイル、ブランドガイドライン、前バージョン、リポジトリ、関連ドキュメント——エージェントが触れるものはすべて、その存在と場所をエージェントが把握している必要がある。
ほとんどの人は、エージェントに与えるContextが劇的に不足している。「Q3のデッキを作って」と頼んでおきながら、参照用の前四半期デッキを共有しない。「ユーザーフィードバックを分析して」と頼んでおきながら、どのファイルか、どのセグメントか、どんな意思決定のための分析かを指定しない。「認証モジュールをリファクタして」と頼んでおきながら、既存のテスト、チームのスタイルガイド、従うべき設計ドキュメントを指示しない。
だからエージェントは推測する。そしてエージェントが推測するとき、1時間も間違った方向に進んでから気づくことが多い。
以下の2つのプロンプトを比べてほしい：
**悪い例：** 顧客フィードバックを分析して。
**良い例：** `/data/feedback_q3.csv` にある顧客フィードバックを分析してください。今四半期にSMB顧客が解約した主な理由をトップ3に絞り、代表的な引用文とともに示すのが目標です。オンボーディングの改善か料金体系の変更か、どちらに投資すべかを判断するための分析を求めています。`/docs/feedback_q2.md` に前四半期の分析があるので、構造のテンプレートとして参照してください。
2番目のプロンプトは2つのことをしている。仕事の内容を伝え、かつ仕事をするために必要なものの場所を伝えている。どちらも重要だ。
**インターンテスト：** 私はContextが十分かどうかを確認するためのシンプルなテストを使う。入社初日のインターンがこのプロンプトを課題として渡されたとして、何も聞き返さずに仕事を始められるだろうか？ Yesなら、ブリーフはほぼ完成している。Noなら、エージェントもインターンと同じ疑問を持っている——ただしエージェントは質問してこない。推測するだけだ。
---
## 2. Constraints（制約）
ここが、エージェントへのプロンプトとチャットボットへのプロンプトが最も大きく異なるところだ。Constraintsは「回答についてのルール」だけではない。**検証のアプローチ**そのものだ。エージェントが作業しながら自分の仕事をどうチェックすべきか、そして「本当に完了した」とはどういう状態かを記述する。
エージェントはコードを実行できる。ファイルを開ける。スクリーンショットを撮れる。自分の出力を読み直してミスに気づける。だからConstraintsは、そういったことを実際にやらせる内容にすべきだ。
弱い制約は「でたらめを言うな」。本物の制約はこうだ：
- スライドを生成したら、ファイルを開いてすべてのスライドをスクリーンショットし、レイアウトが実際に整っているか確認する。何かがずれていたり、テンプレートから外れていたり、テキストがはみ出していたりしたら、修正して再確認する。
- レポートを作成したら、引用したURLをすべて開き、ソースが実際にその主張を述べているか確認する。直接裏付けられない主張は削除する。
- 本番コードを書く前に、公開APIを検証するテストハーネスを構築する。すべてのテストが通るまで完了を主張してはならない。
- リファクタリング後、フルテストスイートを実行する。それまで通っていたものが落ちたなら壊したということだ。スイートが再びグリーンになるまで止まるな。
これらは提案ではない。**停止条件** だ。エージェントがこれらの条件を満たしたときにのみ、完了を宣言できる。
なぜこれが重要かというと、エージェントの失敗パターンによる。エージェントが明らかに間違った仕事をすることはほとんどない。もっともらしく見える仕事を生成し、自信満々に「完了しました」と告げることができる（ただしモデルの改善とともに、これは月を追うごとに減っている）。スライドデッキを開けば9枚のテキストがはみ出したスライドがある。リサーチサマリには3つの引用があり、エージェントが主張した内容が書かれていない。リファクタリングはコンパイルは通るが3つのテストが壊れていて、エージェントは一度も再実行しなかった。いずれもエージェントは「完了した」と報告していた。ただ実際には何も確認していなかったのだ。
これを防ぐには、検証を任意のオプションではなく仕事そのものの一部にすることだ。
**盗む価値のあるパターンをいくつか：**
- ファイルを生成したら、それを開いて説明した通りに見えることを確認する。
- 完了を宣言する前に、確認していないことをすべてリストアップし、それらを確認する。
- 何かについて確信がない場合は、もっともらしい推測をするのではなく、明示的にそう述べる。
- 変更を加えたら、それ以前に通っていたチェックを再実行する。壊れたものはすべて、私に返す前に修正する。
- 実装に着手する前にテストハーネスを構築する。すべてのテストが通るまで完了としない。
ここでの転換は、「書いている間はこのルールに従え」から「この仕事を——検証も含めて——完了させ、何を確認し何を確認しなかったかを教えろ」への移行だ。
---
## 3. Composition（構成）
Compositionとは、成果物をどんな形に整えるかだ。3つの中で最も過小評価されている。エージェントは素晴らしい仕事をできるが、形を伝えなければ、モデルがこれまで最も多く見てきたパターンにデフォルトする。それはほぼ確実にあなたが実際に欲しいものではない。
形を指定する例：
- 特定のセクションを持つ一枚のメモ
- インサイトごとに1枚のスライド＋最後にまとめスライド
- 比較表が上にあり短いナレーティブが下にあるMarkdownファイル
- 特定のフィールドを持つJSONオブジェクト
形式は重要だ。形式が思考を変えるからだ。「分析を書いて」と言われたエージェントは段落を書く。「推奨事項・支持する3つの理由・最も強い反論・考えを変えるもの、という一枚のメモを書いて」と言われたエージェントは、実際にそのように仕事を構造化しながら進める。
「何をすべきか？」と聞く代わりに、特定の形で答えを求める：
```
回答を以下の形式で：
- 私の推奨事項
- これが最良の選択肢である理由
- 最も強い反論
- 私の考えを変えるもの
```
---
## 再利用可能なテンプレート
ほぼすべてのエージェントタスクに応用できるテンプレート：
```
Context:
[状況・対象読者・背景]
[エージェントが使うファイル・リポジトリ・ドキュメント・データ]
[基準を定義するその他の情報]
Your task:
[生成・実行してほしい具体的な内容]
Constraints:
[ルール1]
[ルール2]
Verification（完了前に実施すること）:
[成果物を開いてXを確認する]
[チェックYを実行し、パスすることを確認する]
Output format:
[成果物の形]
[関連する場合は長さ・トーン・スタイル]
```
実際に記入した例：
```
Context:
ソースデータは /data/q3_metrics.csv にある。
前四半期のデッキは /decks/q2_board.pptx にある。その構造とスタイルに合わせること。
ブランドテンプレートは /templates/brand_deck.pptx にある。
対象は6名の取締役（主に投資家）。成長、バーンレート、軌跡の変化を重視する。
大きなストーリーは、売上は未達だが解約率が改善した点だ。デッキは両方に正直に向き合う必要がある。
Your task:
Q3取締役会デッキをエンドツーエンドで作成する。
Constraints:
1スライドにつき1つのヘッドライン数字。
12スライドを超えない。
文章では伝わらないものを伝えるときのみチャートを使う。
Verification（完了前に実施すること）:
すべてのスライドを開き、テンプレートからはみ出していないことを確認する。
すべてのスライドのすべての数字がソースデータと一致していることを確認する。
ストーリーが曖昧で私がフレーミングを確認すべきスライドにフラグを立てる。
Output format:
ブランドテンプレートを使用した完成 .pptx ファイル。
ナレーティブの流れと判断が必要だった箇所についての短いテキストサマリ（8〜10文）。
```
このブリーフは本物の取締役会デッキを生成する。「Q3のデッキを作って」という指示では、バラバラなチャートが並んだ12枚のスライドと、ミスを静かに回避するナレーティブが返ってくる。
---
## エージェントにとってこれが特に重要な理由
チャットボットは雑でも数秒で気づけた。エージェントは雑でも、デッキが送信されるまで、レポートが上司の前に置かれるまで、変更がマージされるまで気づかないかもしれない。エージェントは実際のアクションを取る。ミスには実際の影響がある。
だからプロンプトはより多くの仕事をしなければならない。エージェントが仕事をするのに十分なContextを与え、結果を信頼するのに十分な検証を与え、成果物があなたが実際に使える形で出てくるのに十分な構造を与える必要がある。
スキルは「プロンプトエンジニアリング」から「タスク仕様化」へ移行している。あなたはチームの基準も過去の決定も「完了」の意味も知らない、でも実際の仕事はできる誰かへのブリーフを書いているのだ。そのブリーフがレバーだ。
---
## 悪いプロンプト vs 良いプロンプト：具体例
**デッキの場合：**
- 悪い：「Q3の結果についてデッキを作って。」
- 良い：「来週火曜日の役員会議向けにQ3の結果のデッキを作ってください。ソースデータは /data/q3_metrics.csv にあります。前四半期のデッキは /decks/q2_review.pptx にあります。そのスタイルと構造に合わせてください。生成後、すべてのスライドを開いてスクリーンショットを撮り、レイアウトがクリーンか確認してください。データが曖昧だったりチャートが明確なストーリーを伝えていないスライドにはフラグを立ててください。」
**リサーチタスクの場合：**
- 悪い：「上位3社の競合が料金についてどうしているか調べて。」
- 良い：「[競合A]・[競合B]・[競合C]の現在の料金ページをリサーチしてください。各社について、ティア名・価格・含まれるシート数・注目すべきアドオンや制限を取得してください。各サイトに直接アクセスして料金ページのスクリーンショットを証拠として撮ってください。ライブページで確認できなかった情報は含めないでください。単一の比較表と、現在の弊社料金との違いについての短い段落を出力してください。」
**コンテンツドラフトの場合：**
- 悪い：「ローンチ告知を書いて。」
- 良い：「CSV書き出し機能の新しいエクスポート機能のローンチ告知をProプランの既存ユーザー向けに書いてください。トーンはブログの最近3つの投稿（リンク添付）に合わせてください。300語以内に収めてください。機能ではなくユーザーのメリットを先に述べてください。ドラフト後、読み直してマーケティング的な表現に聞こえるものはすべて削ってください。最終版と、何を削りなぜ削ったかの一行サマリを渡してください。」
**コード変更の場合：**
- 悪い：「チェックアウトフローのバグを修正して。」
- 良い：「クーポンを削除したときにカート合計が更新されないというチェックアウトフローのバグがあります。再現手順はチケット #4421 にあります。関連するコードは /src/cart にあります。既存のテストは /tests/cart にあります。バグを再現する失敗するテストを追加し、それを修正してください。カートのテストスイートが全部通るまで完了としないでください。テスト・修正・根本原因の1段落説明を含むPRを開いてください。」
---
## 最も重要なフレーズ
エージェントへのプロンプトで最もレバレッジの高い一文は **「〜するまで完了としない（don't finish until）」** だ。常に使え。
- ファイルを開いて正しく見えることを確認するまで完了としない。
- すべての引用ソースが確認されるまで完了としない。
- 確認しなかったことをリストアップするまで完了としない。
- テストが通るまで完了としない。
- リンターがグリーンになるまで完了としない。
これが機能する理由は、「完了」の意味を変えるからだ。このフレーズがない場合、エージェントは何かを生成したら完了だ。このフレーズがある場合、エージェントは何かを生成し、それが正しいことを確認したら完了だ。この2つの停止条件はまったく異なり、その差がほぼすべてのエージェント失敗の住む場所だ。
---
## まとめ
3つのCは公式ではない。具体的であるためのチェックリストだ。エージェントに状況と素材を与えたか？自分の仕事の検証方法と「完了」の定義を伝えたか？成果物の形を説明したか？Yesなら、たいていアウトプットは良い。Noなら、たいてい良くない。
エージェントと働くことは、チャットボットに入力するよりも、実際の仕事はできるが自分のチームの基準を知らない業者にブリーフするような感覚に近くなってきた。その価値を生み出すのは、ブリーフをうまく書ける能力だ——仕事が完了するほど明確で、結果を信頼できるほど具体的な。いまや「プロンプトエンジニアリング」と呼ばれているものの多くは、実際にはそういうことだ。
プロンプトエンジニアリングAIエージェントタスク設計claude-workflow
AIエージェントに優れた仕事をさせるプロンプトの極意：3つのC（文脈・制約・構成）フレームワーク
♥ 212↻ 21
原文を表示 / Show original
Matt Shumer
@mattshumer_
The Ultimate Guide to Prompting AI Agents
18
27
212
107K
I've spent the last seven years prompting AI systems, and I've tried just about every approach you can imagine.
Today, I'm sharing my framework for getting the most out of AI agents.
Prompting an AI agent isn't the same as prompting a chatbot. A chatbot answers. An agent works. It can read your files, write code, run tests, open a browser, take screenshots, and iterate on its own output until it's perfect. It can spend an hour on a task and come back with something real.
But only if you tell it what "real" means.
The biggest mistake I see is people prompting agents the way they used to prompt chatbots: they give it a sentence-long instruction, and out comes a generic answer. But agents don't need a sentence. They need a brief.
In this post I'll walk you through the framework I use to write briefs that actually get good work out of an agent. I call it the 3 C's: context, constraints, and composition.
1. Context
Context is everything the agent needs to know to do the job, plus everything it needs access to. That includes the situation, the goal, the audience, and what success looks like. But it also includes the actual materials. The deck. The data file. The brand guidelines. The previous version. The repo. The relevant documentation. Whatever the agent will be touching, it should know it exists and where to find it.
Most people dramatically under-context their agents. They'll ask one to "make a deck about Q3" without sharing last quarter's deck for reference. They'll ask it to "analyze the user feedback" without specifying which file, what segment, or what decision the analysis is supposed to inform. They'll ask it to "refactor the auth module" without pointing it at the existing tests, the team's style guide, or the design doc the module is supposed to follow.
So the agent guesses. And when an agent guesses, you usually don't notice until it's an hour deep into the wrong thing.
Compare these two prompts:
Bad: Analyze our customer feedback.
Better: Analyze the customer feedback in /data/feedback_q3.csv. The goal is to surface the top three reasons SMB customers churned this quarter, with representative quotes. We're trying to decide whether to invest in onboarding fixes or in pricing changes, so the analysis should help us pick. There's a previous version of this analysis at /docs/feedback_q2.md that you can use as a template for structure.
The second prompt does two things. It tells the agent what the job is, and it tells the agent where to find everything it needs to do the job. Both matter.
The intern test. I use a simple test to check whether I've given enough context. Imagine an intern shows up on their first day and you hand them this prompt as their assignment. Could they get to work without coming back to ask you anything? If yes, the brief is probably complete. If no, your agent has the same questions the intern would. The agent just won't ask them. It'll likely guess.
2. Constraints
This is where prompting agents diverges most from prompting chatbots. Constraints aren't just rules about the answer. They're the verification approach. They describe how the agent should check its own work as it goes, and what counts as actually being done.
Agents can run code. They can open files. They can take screenshots. They can re-read their own output and notice mistakes. So your constraints should make them do those things.
A weak constraint is "don't make things up." A real constraint says:
After generating the slides, open the file, screenshot every slide, and check that the layout actually looks polished. If anything is misaligned, off-template, or has overflowing text, fix it and re-check.
After drafting the report, open every cited URL and verify that the source actually says what you claim it says. Remove any claim you can't directly support.
Before writing any production code, build a test harness that exercises the public API. Don't claim you're finished until every test passes.
After refactoring, run the full test suite. If something that was passing now fails, you broke it. Don't stop until the suite is green again.
These aren't suggestions. They're stopping conditions. The agent is allowed to declare itself done when, and only when, those conditions are met.
This matters because of how agents tend to fail. They rarely produce obviously wrong work. They can produce plausible-looking work and confidently announce they're done (though this gets less and less likely every month as models improve). The slide deck opens to nine slides of overflowing text. The research summary has three citations that don't say what the agent claims they say. The refactor compiles and broke three tests the agent never re-ran. In every case the agent told you it was finished. It just hadn't actually verified anything.
You prevent that by making verification part of the work, not an optional afterthought.
A few patterns worth stealing:
After producing a file, open it and confirm it actually looks the way you described.
Before declaring done, list everything you didn't verify, and check those things.
If you're unsure about something, say so explicitly instead of picking the most plausible guess.
After making a change, re-run the checks that were passing before. Anything that broke should be fixed before returning to me.
Build the test harness before starting on the implementation. Don't finish until every test passes.
The shift here is from "follow these rules while you write" to "complete this work, including the verification, and then tell me what you did and didn't check."
3. Composition
Composition is how you want the deliverable structured, and it's the most underrated of the three. Agents can produce great work, but if you don't tell them what shape it should take, they'll usually default to whatever the model has seen most often. That's almost never what you actually want.
Specify the shape, for example:
A one-page memo with these specific sections.
A deck with one slide per insight, plus a summary slide at the end.
A markdown file with a comparison table on top and a short narrative below.
A JSON object with these exact fields.
Format matters because format changes thinking. An agent told to produce "an analysis" will write paragraphs. An agent told to produce "a one-page memo with a recommendation, three supporting reasons, and the strongest counterargument" will actually structure the work that way as it goes.
Instead of asking "what should I do?", ask for the answer in a specific shape, like:
Format the answer as:
- My recommendation
- Why this is the best option
- The strongest counterargument
- What would change my mind
A reusable template
Here's a template you can adapt to almost any agent task:
Context:
[the situation, audience, background]
[the files, repos, docs, or data the agent will work with]
[anything else that defines the standard]
Your task:
[the specific thing you want produced or done].
Constraints:
[rule 1]
[rule 2]
Verification (don't finish until):
[open the artifact and confirm X]
[run the check Y and confirm it passes]
Output format:
[shape of the deliverable]
[length, tone, style if relevant]
And here's a real version, filled in:
Context:
Source data is in /data/q3_metrics.csv.
Last quarter's deck is at /decks/q2_board.pptx. Match its structure and style.
Brand template is at /templates/brand_deck.pptx.
Audience is six board members, mostly investors. They care about growth, burn, and any change in trajectory.
The big story is that we missed revenue but improved retention. The deck needs to be honest about both.
Your task:
Build the Q3 board deck end-to-end.
Constraints:
One headline number per slide.
No more than 12 slides.
Use a chart only when a chart adds something a sentence can't.
Verification (don't finish until):
You've opened every slide and confirmed nothing overflows the template.
Every number on every slide reconciles to the source data.
You've flagged any slide where the story is ambiguous and I should sanity-check the framing.
Output format:
A finished .pptx using the brand template.
A short text summary (8-10 sentences) of the narrative arc and any judgment calls you had to make.
That brief will get you a real board deck. "Make me a Q3 deck" will get you twelve slides of disconnected charts and a narrative that quietly avoids the misses.
Why this matters more for agents
Chatbots could be sloppy and you'd notice in the answer, within a few seconds. Agents can be sloppy and you might not notice until the deck is sent, the report is in front of your boss, or the change is merged. They take real actions. Their mistakes have real surface area.
So the prompt has to do more work. It has to give the agent enough context to do the job, enough verification to trust the result, and enough structure that the deliverable comes out shaped the way you can actually use it.
The skill is shifting from "prompt engineering" to "task specification." You're writing a brief for someone who can do real work but doesn't know your team's standards, your previous decisions, or what "done" looks like to you. That brief is the lever.
Bad prompting vs. good prompting
A few side-by-side examples make it concrete.
For a deck, the bad version is "make me a deck about Q3 results." The good version is: "Build a deck on Q3 results for our exec team meeting next Tuesday. Source data is in /data/q3_metrics.csv. Last quarter's deck is at /decks/q2_review.pptx. Match its style and structure. After generating, open every slide, screenshot it, and confirm the layout looks clean. Flag any slide where the data is ambiguous or the chart doesn't tell a clear story."
For a research task, the bad version is "research what our top three competitors are doing on pricing." The good version is: "Research current pricing pages for [Competitor A], [Competitor B], and [Competitor C]. For each, capture the tier names, prices, included seats, and any notable add-ons or restrictions. Visit each site directly and screenshot the pricing page as evidence. Don't include anything you couldn't verify on the live page. Output a single comparison table plus a short paragraph on what's different from our current pricing."
For a content draft, the bad version is "write me a launch announcement." The good version is: "Draft a launch announcement for the new export-to-CSV feature, aimed at existing customers on the Pro plan. Tone should match the last three posts on our blog (linked). Keep it under 300 words. Lead with the user benefit, not the feature. After drafting, re-read it once and cut anything that sounds like marketing fluff. Give me the final version plus a one-line summary of what you cut and why."
For a code change, the bad version is "fix the bug in the checkout flow." The good version is: "There's a bug in the checkout flow where the cart total doesn't update when a coupon is removed. Repro is in ticket #4421. The relevant code is in /src/cart. Existing tests are in /tests/cart. Add a failing test that reproduces the bug, fix it, and don't finish until the full cart test suite passes. Open a PR with the test, the fix, and a one-paragraph explanation of the root cause."
The most important phrase
The single highest-leverage phrase in agent prompting is don't finish until. Use it constantly.
Don't finish until you've opened the file and confirmed it looks right. Don't finish until every cited source has been verified. Don't finish until you've listed what you didn't check. Don't finish until the tests pass. Don't finish until the linter is green.
It works because it changes what "done" means. Without it, the agent is done when it has produced a thing. With it, the agent is done when it has produced a thing and confirmed the thing is correct. Those are very different stopping conditions, and the gap between them is where almost all agent failure lives.
Pulling it together
The 3 C's aren't really a formula. They're a checklist for being specific. Have you given the agent the situation and the materials? Have you told it how to verify its own work and what counts as done? Have you described what the deliverable should look like? If yes, the output is usually good. If no, it usually isn't.
Working with agents has started to feel less like typing into a chatbot and more like briefing a contractor who can do the job but has never met you. The thing that pays off is being able to write that brief well: clear enough that the work gets done, specific enough that you can trust the result. Most of what people now call prompt engineering is really just that.
If you've made it this far, try https://agent-s.app, which does most of this automatically. It's the most powerful agent in the world, but it's so simple that my mom uses it daily.
And send this to a friend who might find it useful!
Want to publish your own Article?
Upgrade to Premium
8:51 AM · Apr 22, 2026
·
107.4K
Views
18
27
212
773
Read 18 replies