基礎知識 / FUNDAMENTALS

プロンプトエンジニアリング基礎

CLI型 AI エージェントを実用に使うための、プロンプトの書き方・前提情報の渡し方・失敗の見つけ方を整理。

公開 2026.05.17

「プロンプトエンジニアリング」と書くと大層に聞こえるが、CLI 型のエージェント（Claude Code、Codex、Gemini など）を使うときに意識する内容はかなり実用的。Webのチャットボットでよく語られる「役割を与える」「思考プロセスを明示する」とは少し別の話になる。

CLI エージェントへの指示の3層

CLI エージェントへの指示は、性質の違う3層に分かれる。

1. プロジェクト記憶（CLAUDE.md / GEMINI.md / config.toml）

毎セッションで読まれる「前提」。書くべきこと:

プロジェクトの技術スタック（TypeScript / Next.js App Router 等）
テスト実行コマンド
ビルド・デプロイの方法
触ってはいけないファイル
コーディング規約のうち、頻繁に違反されるもの

書かなくていいこと:

一度しか使わない情報
既に README に書いてあること（READMEは普通に読みに行く）
LLM が一般常識として知っていること

2. セッション冒頭の方針指定

セッションの最初に「今日はこのタスクをやる」と伝える。

今からSlack通知機能を追加します。
方針:
- src/notifications/ に新規モジュールを作る
- 既存のWebhook設定を読みに行く
- テストは tests/notifications/ に書く

エージェントは指示を額面通り解釈するので、判断の余地がある部分は最初に固めておくと後でブレない。

3. 個別のターン

具体的なリクエスト。「この関数の型をジェネリックに」「テストを追加して」など。

効くプロンプト・効かないプロンプト

効くもの

具体的な動詞 + 対象

src/auth.ts の signIn 関数に、Google OAuth を追加して

制約条件を明示

このリファクタは public API を変えずに行って

前提と goal の分離

前提: 既存テストは全部 pass している
goal: パフォーマンスを 30% 改善する
方法: 任せる

効かないもの

曖昧な形容詞

このコードをいい感じにして

→ 「いい感じ」が何かは LLM が解釈する。だいたい意図とずれる。

禁止だけの指示

hacky な書き方はしないで

→ 「何ならいいか」を併記しないと、結果がよくならない。

過剰な役割指定

あなたは20年経験のあるシニアエンジニアです...

→ Webチャット時代の名残。CLI エージェントには既に十分なコンテキストが渡っているので、ノイズになることが多い。

エージェントが詰まったときの言い回し

エージェントが繰り返し間違える、的外れな方向に進んでいるとき、こちらが介入する言い回しがいくつかある。

「やり直して、今回は X を満たすこと」

→ 完全リトライ。前回の出力は使わない。

「現状を把握して。次に何をすべきか提案だけして」

→ 実行を止めて状況整理させる。エージェントが暴走気味のときに効く。

「いったん仮説をリストアップして。確度の高い順に並べて」

→ デバッグで手詰まりのとき。LLM の思考を可視化させる。

「もう一度ファイルを読み直して、最新の状態を踏まえて判断して」

→ コンテキストが古くなっている疑いがあるとき。明示的に再読を促す。

CLI 特有の罠

1. プロンプトに長文を貼り付けすぎる

このログを分析して: [3000行のスタックトレース貼り付け]

→ コンテキストを食い、関係ない部分も解釈の対象になる。エラーの本質部分だけ抜き出すか、ファイルを指定して「logs/2026-05-17.log の最後の100行を見て」のように渡す。

2. ファイル指定が曖昧

あの関数を直して

→ どの関数か特定できない。src/auth.ts:signIn のように指定する。

3. エージェントの実行結果を確認しない

長時間タスクを --yolo 系で投げて放置すると、間違った方向に何時間も走っていることがある。エージェントを完全放置せず、節目で確認する習慣を持つ。

「いい指示」の特徴

経験的に、結果のいい指示はこんな特徴がある。

動詞が具体的: 「改善する」「追加する」「削除する」より「signIn 関数に Google OAuth ハンドラを追加する」
入力と出力が明確: 「何があれば start で、何ができたら done か」
制約と自由度を分けている: 「ここは変えるな、ここは任せる」
長さが短い: 長い指示は、自分が要件を整理できていないサイン

指示を書きながら「自分が何をしたいか分からない」と気づくことがある。これは LLM のせいではなく、人間側の整理不足。落ち着いて要件を整理してから出した方が結果的に早い。

LLM（大規模言語モデル）とは — プロンプトの届く先で動いているもの
AI エージェントとは — エージェント型の使い方