AI 2026年1月7日

【実践】AIエージェントでのコーディング指南書 - 4ヶ月の開発から学ぶプロンプト術

約25分で読めます

はじめに

「AIエージェントを使ってみたけど、うまく動かない」「何を指示すればいいかわからない」——そんな声をよく聞きます。

この記事は、約4ヶ月間AIエージェント（Claude Code、Codex CLIなど）を使って開発してきた経験から見つけた、効果的なパターンをまとめた指南書です。これまで各自が試行錯誤しながら使ってきましたが、知見が整理されないまま属人化していました。開発チームに新メンバーが加わったこのタイミングで、改めてノウハウを整理・共有することにしました。

Nano Banana Pro挿絵 - 先輩開発者と新人が一緒にターミナルを見ながら、AIエージェントと対話している様子。画面にはコードとチャットが表示され、先輩が「こうやってプロンプトを書くんだよ」と教えている雰囲気。「指南書」らしいメンタリングのイメージ。

1. 効果的なプロンプトの書き方

1.1 「@ファイルパス」でコンテキストを明示する

AIエージェントは賢いですが、読心術は使えません。どのファイルの話をしているのか、明示的に教えてあげましょう。

1
2
3
4
5
6
7
❌ 悪い例：
「このエラーを直して」

✅ 良い例：
「@src/components/user-profile/sections/department-info.tsx
について、部署名がIDのまま表示されてしまっています。
原因を調査して修正してください。」

Anthropic のベストプラクティスでも、「giving clear directions upfront reduces the need for course corrections later」（最初に明確な指示を与えることで、後から軌道修正する必要が減る）と述べられています¹。

@記法のポイント：

ポイント	良い例	悪い例
フルパスで指定	`@src/components/.../file.tsx`	`file.tsx を見て`（どこにあるか不明）
複数ファイル比較時	両方のパスを明示	「もう一つのファイルと比較して」

1.2 問題の背景・文脈を詳細に説明する

実際の開発で効果的だったプロンプトパターンを見てみましょう。

1
2
3
4
5
6
7
元請けベンダーから以下の質問が来ています。
コードベースやSalesforceの現在のライセンス構成での
ガバナ制限など、Context7やネット調査も含めて調査してください。

---

[質問内容をそのまま貼り付け]

このプロンプトには以下の要素が含まれています。

誰からの依頼か（元請けベンダー）
何を調べるか（ガバナ制限）
どのツールを使うか（Context7、ネット調査）
具体的な質問内容（区切り線の後に記載）

1.3 明確な指示動詞を使う

効果的なプロンプトには明確な指示動詞が使われています。

指示動詞	使用シーン
「調査して欲しい」	原因調査、情報収集
「確認して欲しい」	コードレビュー、設定チェック
「修正して欲しい」	バグ修正、リファクタリング
「レビューして」	コードの品質確認
「最新の情報を調査して」	Web検索を促す

基本方針: 明確な指示が望ましいですが、「〜をいい感じにして」が有効な場面もあります。

場面	「いい感じに」でOK	明確な指示が必要
技術選択で迷っている時	✅ まず提案を見る
ディレクトリ構成の整理	✅ ベストプラクティス活用
明確なゴールがある修正		✅ 期待を具体的に
UIの見た目調整		✅ 「いい感じ」の基準が人による

最近のモデルは文脈理解力が高いため、コードベースを把握した上での「いい感じに」は、プロジェクトの規約やパターンに沿った提案につながることも多いです。

1.4 日本語での明確な指示

日本語でプロンプトを書く際のポイントです。

ポイント	良い例	悪い例
主語を明確に	「このコンポーネントは〜」	「これは〜」（主語省略）
指示を具体的に	「コード表示を名称表示に変更して」	「直して」
期待を伝える	「モーダル側と同じ表示にして」	「いい感じにして」※

※ただし探索的タスク（技術選択、構成整理など）では「いい感じに」も有効（前述の表を参照）

1.5 仮説検証アプローチ — 「◯◯って△△だよね？」

Xで見かけたこちらの投稿が、私がAIエージェントを使う上で意識していることを上手く言語化してくれていました。

拙くてもいい、見当違いでもいいから「◯◯って、△△ってことだよね？」って、自分の認識や理解を検証する使い方をしたほうがいいよ。
わりと一般的な社会人のマナーとして、上司や先輩に訊く時に、ただ訊くんじゃなくて自分なりの考えを元に「って理解なんですけど、合ってますかね？」ってやるほうがいいと思ってるんだけど、それと一緒だね。ただAIの場合はそのまま相手の負荷を考える必要も無く正解するまで無限にラリーできるんだから徹底的にやればいいよ。
自分の言葉を使って、恥をかかずに仮説を検証できる最高の時代だよ。

私もこの考え方に近く、実際の開発でも「〜だと思うので確認して」「〜の可能性があるので調査して」という形でプロンプトを書くことが多いです。

1
2
3
4
5
6
7
❌ 悪い例（丸投げ）：
「このエラーの原因を教えて」

✅ 良い例（仮説検証）：
「500エラーが出ています。ファイルを開けない
（対応していないバージョンとか、壊れている、など）
のかもしれないと思うのですが、確認してもらえますか？」

実際の開発でも、このパターンは頻繁に使われていました。

仮説表現	実際の使用例
「〜と思います」	「OKsampleのpdfはiTextで作成されたものと思います」
「〜かもしれない」	「500のシステムエラーは、ファイルを開けないのかもしれないですね」
「〜な気がします」	「V1.7は、単にファイル先頭のバージョン表示を確認してエラーにしているような気がします」
「〜の可能性」	「コンポーネントのアンマウントが発生し、ルーターコンテキストが不安定になる可能性があります」

なぜ仮説検証が効果的なのか？

仮説を立てることで、AIの調査ポイントが明確になります。そして、たとえ仮説が間違っていても、AIが「いえ、実際は〜」と訂正してくれるため、正しい理解に効率よく近づけます。

これは業務実装において特に重要です。AIはコードベースを読めますが、コードベース上にないコンテキストは知りません。

なぜこの設計になったのか（過去の意思決定）
外部システム（Salesforce、AWS等）の制約
プロジェクト固有のビジネスロジック
組織的な制約（「元請けベンダー側の管轄なので触れない」等）

これらは開発者の頭の中にしかない情報です。仮説として伝えることで、AIの調査方向が定まり、精度が格段に上がります。

1
2
3
4
5
6
7
❌ 悪い例（コンテキスト不足）：
「このAPIがエラーになる原因を調べて」

✅ 良い例（開発者のコンテキストを仮説として伝える）：
「このAPIがエラーになっています。
外部の電子署名サービスがPDF/A-1a準拠を前提として
設計されている可能性があると思うのですが、確認してもらえますか？」

AIは批判しません。気軽に仮説をぶつけてみてください。

Nano Banana Pro挿絵 - 開発者が「◯◯って△△だよね？」と仮説を伝える吹き出しと、AIが「はい、その通りです」または「いえ、実際は〜」と応答する吹き出しの対話図。仮説検証の往復を視覚化し、「プロンプトの書き方」セクション全体のまとめとして機能させる。

2. 設定済みのツール連携

AIの回答精度を高めるために複数のMCPツールを設定済みです。これらは自動的に動作するので、特に意識する必要はありませんが、何が起きているかを理解しておくと便利です。

2.1 Sequential Thinking MCP（思考整理）

複雑な問題に取り組む際、AIは順序立てて考えるようになっています。

1
2
3
4
5
6
7
8
9
sequential-thinking - sequentialthinking (MCP)
  thought: "ユーザーの要求: T_Sendmail__c レコードで
           メールテンプレートが展開できない問題の調査

           調査アプローチ:
           1. まずT_Sendmail__cレコードを取得して内容を確認
           2. メールテンプレート関連のフィールドを確認
           3. 関連するApexクラスを確認
           4. 問題の原因を特定"

人間がホワイトボードに書きながら考えるのと同じで、AIも「考えを整理する場所」があると、より良い回答ができます。

通常のThinkingはモデル内部で完結しますが、このMCPでは思考が外部に書き出され、履歴として残ります。「ステップ3の仮説は間違いだった」と気づいたら、そこに立ち戻って修正したり、別の推論パスに分岐したりできます。推論プロセスが可視化されるため、チームでの共有や後からの検証にも役立ちます。

2.2 Serena MCP（シンボルベースのコード調査）

ファイル全体を読み込むのではなく、必要なシンボル（関数、クラス）だけを取得するように設定されています。

通常のAI検索はキーワード検索やGrepに依存するため、たまたま同じ単語が含まれる無関係なコードも拾ってしまいます。一方、SerenaはLSP（Language Server Protocol）を使ってコードの構造を理解するため、「この関数を呼び出している箇所」「このクラスを継承している箇所」といった意味的な関連性で検索できます。

💡 LSPとは、IDEでCtrl+クリックすると定義元にジャンプしたり、使用箇所が一覧表示される機能を実現しているプロトコルです。

1
2
3
4
serena - find_symbol (MCP)
  name_path_pattern: "CLS_SendMail"
  include_body: false
  depth: 1

このアプローチのメリットは以下の通りです。

トークン消費を抑制 - 必要な部分だけ読み込む
処理速度向上 - 無駄な情報を排除
精度向上 - 関連コードに集中できる

2.3 Context7（最新ドキュメント取得）

ライブラリのAPIは頻繁に変わります。AIの学習データは古い可能性があるため、Context7 MCP で最新のドキュメントを自動取得します。

1
2
3
context7 - get-library-docs (MCP)
  context7CompatibleLibraryID: "/tanstack/router"
  topic: "navigate useNavigate modal context"

実際の開発では、TanStack Router の useNavigate でエラーが発生した際、Context7 で最新ドキュメントを取得し、from オプションの指定が必要だと特定できた事例がありました。

2.4 Web Search（最新情報の調査）

「最新の情報を調査して」と一言添えるだけで、AIはWeb検索を実行します。

1
2
3
4
5
6
codexを立ち上げると下記の警告が表示されてしまいます。
どのような意味か、対処法など最新の情報を調査してください。

---

⚠ MCP client for `sequential-thinking` failed to start...

ポイント: LLMの知識にはカットオフ日があります²。最新のエラーメッセージや新機能については、Web検索を組み合わせましょう。

これは「1.5 仮説検証」とも密接に関係しています。私は道を知っていてもカーナビをつけるようにしています。その時の混雑状況で最適ルートが変わるからです。技術の世界も同じで、1ヶ月前のベストプラクティスが今日は変わっているかもしれません。持っている知識を仮説として伝えつつ、最新情報を調査させる——この組み合わせがAIの回答精度を高めます。

Nano Banana Pro挿絵 - AIエージェントがオーケストラの指揮者のように、4つのツールを適切なタイミングで使い分けている様子。📋Sequential Thinking（思考整理）、🔍Serena（コード検索）、📚Context7（ドキュメント）、🌐Web Search（最新情報）が楽器のように配置され、中央のAIが指揮棒を振っているイメージ。

3. 対話的なワークフロー

3.1 調査 → 分析 → 提案 → 承認 → 実装の流れ

効果的なやりとりには明確なフェーズがあります。

flowchart LR
    A[調査] --> B[分析]
    B --> C[提案]
    C --> D[承認]
    D --> E[実装]
    E --> F[確認]
    F -->|フィードバック| B

各フェーズの典型的なやりとり：

フェーズ	ユーザーの発言例	AIの動作
調査	「原因を調査して欲しい」	コード読み込み、検索実行
分析	「どうでしょう？」	発見内容の報告、選択肢の提示
提案	「いいと思います」	具体的な修正案を提示
承認	「お願いします」	実装開始
実装	（待機）	コード修正、テスト実行
確認	「レビューして」	変更内容の検証

3.2 「どうでしょう？」で確認を求める

AIに判断を任せきりにせず、節目で確認を求めるのが効果的です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
ユーザー: useのプレフィックスの形式にしてしまうと
         リンターに引っかかってしまい、呼び出し箇所が
         コンポーネントの先頭の方に限定されてしまいます。
         ユーティリティ的な構成になれば、呼び出し元も
         if文の中で直接使用できたりと、扱いやすくなりそう
         なのですがどうでしょう？

AI: おっしゃる通りです。useState や useQuery が
    使用されておらず実質は純粋関数になっているので、
    use- プレフィックスを外してユーティリティ関数化
    するのが適切です...

「どうでしょう？」は、AIに「あなたの意見も聞かせて」というシグナルを送ります。これにより、AIは単なる実行者ではなく、相談相手として機能します。

3.3 フィードバックを与えながら段階的に進める

一発で完璧な結果を求めるのではなく、段階的に改善していくのが現実的です。

1
2
3
4
5
6
7
ユーザー: デザインが少し変わりすぎな気がします。
         `<div className="p-4">`などをしてしまうと
         見た目が変わってしまうので元に戻して欲しいです。
         ひとまず、元々のReadonlyFormSectionのrenderに
         カンマ区切りで並べるなどのシンプルな対応で問題ないです。

AI: 承知しました。シンプルな対応に修正します...

Tips: AIは過剰に気を利かせることがあります（over-engineering）。Anthropic も「add explicit prompting to keep solutions minimal」（最小限の解決策に留めるよう明示的に指示する）ことを推奨しています³。

3.4 段階的なタスク分解

一度に多くの指示を出しすぎると、AIは混乱したり、途中で方向性を見失うことがあります。1つのタスクが完了してから次の指示を出すのがコツです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
❌ 悪い例（一気に指示を出しすぎ）：
「認証機能を実装して。ログイン画面を作って、
 APIと連携して、エラーハンドリングも追加して」

✅ 良い例（完了を確認しながら順序立てて進める）：
「まず既存の認証コードを調査して」
  → 完了後
「ログイン画面のコンポーネントを作成して」
  → 完了後
「認証APIとの連携を実装して」
  → 完了後
「エラーハンドリングを追加して」

「終わったら〇〇を実施してください」のように、完了を確認してから次に進むことで、各ステップの品質を担保できます。

Nano Banana Pro挿絵 - ユーザーとAIがピンポンのようにやりとりしながら、徐々にコードが完成していく様子。

4. 具体的なユースケース例

4.1 バグ調査・修正

Salesforceメールテンプレート展開問題

1
2
3
4
5
6
7
8
9
ユーザー: T_Sendmail__cのa0YXXXXXXXXXXXX（サンプルID）で
         メールテンプレートが展開できていません。
         レコードを取得して原因を調査して欲しいです。

AI: [Sequential Thinking で調査計画を立案]
    [Salesforce CLI でレコード取得]
    [問題発見: %mitsumori_uketsuke_shuuryou% が展開されていない]
    [Serena MCP でApexコードを調査]
    [原因特定: mitsumori_juryou_end_at__c が null]

この事例では、AIが以下の手順で問題を特定しました。

レコードデータの取得・確認
未展開のプレースホルダーを発見
関連するApexコードの調査
null値が原因であることを特定

4.2 コードレビュー

gitコミットの差分確認

1
2
3
4
ユーザー: abc1234def5678... と
         fed8765cba4321... の
         gitのコミットについて、diffを見比べて
         既存の処理が壊れていないかレビューをして欲しいです。

AIは以下の観点でレビューを実施しました。

ファイルダウンロード・アップロードロジックの保全
重複コードの共通化による影響
既存の振る舞いが維持されているか

4.3 仕様書作成（複数往復パターン）

案件タグ機能の仕様書 — 3回のやりとりで仕様を固めた例

仕様書作成は一発で完成させるのではなく、複数回のやりとりで段階的に固めるのが効果的です。

1
2
3
4
5
6
【1回目】資料の読み取り確認
ユーザー: @docs/keyword-search.pdf について読み取れますか？

AI: [PDF読み取り・内容要約]
    「検索キーワード登録及びメール通知機能 v0.4」という仕様書で、
    元請けベンダーが作成したものです...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
【2回目】仕様書作成 + 実装候補の依頼
ユーザー: @docs/specs/ に仕様を起こしたいです。
         特にタグづけ部分で、案件にどうやってタグを持たせるか
         についての候補を出して欲しいです。

AI: [既存のデータモデルを調査]
    [実装候補の比較表を作成]

    | 候補 | 方式 | プロジェクト整合性 |
    |-----|------|------------------|
    | A1  | カスタムメタデータ型 | ◎ |
    | A2  | カスタムオブジェクト | ○ |

    内容を確認いただき、方針を決定したらお知らせください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
【3回目】追加の制約情報を伝える
ユーザー: 少し情報を付け加えます。
         - 今後はメール送信部分は、AWS SESで構築予定だが
           一旦スケジュール優先でSalesforceのメール送信を利用する
         - メール送信数のガバナ制限にかからないために、
           setTargetObjectIdを使用する想定

AI: 重要な制約情報ですね。既存のメール送信アーキテクチャも
    確認して、仕様書を更新します。
    [既存パターンを調査]
    [制約を反映した仕様に更新]

ポイント: 最初から全ての情報を伝えなくても、後から制約や追加情報を伝えることで仕様を精緻化できます。AIは以前のやりとりを覚えているので、差分だけ伝えれば十分です。

4.4 ツールセットアップ

Knipの導入

1
2
3
4
5
6
7
8
9
ユーザー: 不要ソースを洗い出して削除したいので、Knipを導入したいです。
         context7やネット検索で最新の情報を調査して
         このリポジトリにセットアップしたいです。

AI: [Context7 で Knip ドキュメント取得]
    [プロジェクト構造の探索]
    [設定ファイル案の作成]
    [package.json へのスクリプト追加]
    [VSCode tasks.json へのタスク追加]

4.5 UI/UX修正

表示ラベルの統一

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
ユーザー: @src/pages/order-detail/sections/basic-info/
         について、
         @src/components/order-form-modal/
         と項目の表示ラベルが違うところがあります。
         モーダル側のラベルを正とし、ラベル表示の仕組みはなるべく揃えて
         詳細表示の方を修正して下さい。

AI: [両方のファイルを読み込み]
    [差分を特定]
    [モーダル側に合わせて修正]

4.6 外部サービス変更の影響調査

外部認証サービスの仕様変更調査 — 仮説を持って調査を依頼

外部サービスの仕様変更が来たときも、「影響がないと思うが確認して」という仮説付きで依頼すると効率的です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
ユーザー: 外部認証サービスから仕様変更に係る調査票が来ておりました。
         基本的に影響がないと思っておりますが、
         念のためご確認いただけますでしょうか？
         影響があるとしたら2番目かなと思っています。

         調査項目１ 改ざん防止のための仕組みの強化への対応
         調査項目２ フィッシング防止のための仕組みの正常化
         調査項目３ 認証後にやり取りされる情報の安全性向上
         調査項目４ 認証後の情報取得のためのコードの文字長変更

AI: [プロジェクトの認証実装状況を確認]
    [OAuth/OIDC関連コードを検索]
    [認証ハンドラークラスを調査]

    調査結果:
    - 調査項目１: 影響なし（証明書はIdP側で管理）
    - 調査項目２: 要確認（state値のデコード処理を確認中）
    - 調査項目３: 影響なし（追加項目は使用していない）
    - 調査項目４: 影響なし（認証コードの文字長は可変対応済み）

ポイント: 「影響があるとしたら2番目かな」という仮説を伝えることで、AIは優先的にその部分を詳しく調査できます。また、元請けベンダーへの回答文章もAIに作成させることで、調査から報告までを効率化できます。

Nano Banana Pro挿絵 - 6つのユースケースがアイコンとキーワード付きで並んでいる図。🐛バグ調査→「原因特定」、📝コードレビュー→「差分確認」、📋仕様書作成→「段階的精緻化」、🔧ツールセットアップ→「最新情報」、🎨UI修正→「ラベル統一」、🔍影響調査→「仮説検証」。読者が自分のユースケースをすぐに見つけられる視覚的インデックス。

5. よくある失敗パターンと対策

5.1 コンテキストの肥大化

問題: 長時間の作業でコンテキストがいっぱいになり、AIの精度が落ちる

対策:

タスク完了ごとに /clear でコンテキストをリセット
関連性の低い情報は外部ドキュメントに退避

5.2 over-engineering（過剰設計）

問題: AIが不要な抽象化やファイルを追加してしまう

対策:

「シンプルな対応で問題ないです」と明示
「最小限の変更で」と指示
追加されたファイルは本当に必要か確認

5.3 古い情報に基づく回答

問題: AIが学習データのカットオフ以前の情報で回答

対策:

「最新の情報を調査して」と指示
回答の日付・バージョンを確認

5.4 意図と違う方向への進行

問題: AIが思わぬ方向に作業を進めてしまう

対策:

節目で「どうでしょう？」と確認
Plan モードで計画を立ててから実装
こまめにgit commitしておく（ロールバック可能に）

5.5 フィードバックの不足

問題: AIの回答をそのまま受け入れてしまい、意図と違う結果になる

対策:

積極的にフィードバックを与える
「違います」「そうではなく〜」と明確に伝える

1
2
「違います、円が追加されているのは取り除くのです。
 モーダル側は `円` を表示していないはずです。」

このフィードバックにより、AIは期待を再認識し、正しい方向に修正できます。

Nano Banana Pro挿絵 - 開発者がコンパスを持ち、AIエージェントの進行方向を正しくガイドしている様子。「軌道修正」「フィードバック」をイメージ。道に迷いそうなAIを開発者が正しい方向に導いている。

6. Codex CLIクイックリファレンス

開発メンバーからよく質問される基本操作をまとめました。困ったときにすぐ参照できるチートシートです。

6.1 モデルの変え方

1
/model

対話中に /model と入力すると、モデル選択メニューが表示されます。gpt-5.1-mini（軽量・高速）や gpt-5.2（高精度）などを切り替えられます。

6.2 質問中の止め方

操作	効果
`Esc`	現在のリクエストをキャンセル（最もよく使う）
`Ctrl+C`	現在の操作をキャンセル
`Ctrl+C` を2回 / `/quit` / `/exit`	セッションを完全に終了

💡 実行中のコマンド（npm scriptなど）を止めたい場合も Esc が有効です。Codexプロセス自体は維持されるので、そのまま会話を続けられます。

6.3 会話のやり直し方

方法1: /undo コマンド

1
/undo

直前のターンの変更を元に戻します（ファイル変更も含む）。確認プロンプトが表示されるので、承認すればロールバックされます。

⚠️ 一部バージョンで「No ghost snapshot available to undo」エラーが報告されています。その場合は方法2を使用してください。

方法2: Esc×2 で過去のメッセージを編集

コンポーザー（入力欄）が空の状態で Esc を2回押すと、直前のユーザーメッセージを編集できます。さらに Esc を押し続けると、より過去のメッセージに遡れます。

編集後に Enter を押すと、その時点から会話を分岐（fork） できます。「あの時点からやり直したい」という場合に非常に便利です。

方法3: /new で新しい会話を開始

1
/new

CLIを終了せずに、新しい会話をゼロから始められます。タスクが完了して次のタスクに移る際に便利です。

6.4 セッションの再開（Resume）

CLIがちらついたり表示が不安定な時は、Ctrl+C で一旦閉じて再開するのがよくあるパターンです。

1
2
3
4
5
6
7
8
# 最新のセッションをすぐに再開（最もよく使う）
codex resume --last

# セッション選択画面を表示（複数セッションから選ぶ）
codex resume

# 特定のセッションIDを指定して再開
codex resume <SESSION_ID>

再開すると、元のトランスクリプト・計画履歴・承認履歴がすべて保持されているため、中断したところからシームレスに作業を続けられます。

💡 非対話的な再開: codex exec resume --last で、スクリプトやCI/CDパイプラインからセッションを継続することも可能です。

6.5 その他の便利な操作

コマンド/ショートカット	説明
`/compact`	会話を要約してコンテキストを節約（長時間作業時に必須）
`/status`	現在のモデル、承認ポリシー、トークン使用量を表示
`/diff`	git差分を表示（コミット前の確認に便利）
`/approvals`	承認レベルを変更（Auto/Read-only/Full Access）
`@`	ファイル検索（ファジー検索でパスを補完）
`Ctrl+G`	外部エディタでプロンプトを編集（長文入力時に便利）
`↑` / `↓`	コマンド履歴を参照
`Option+Enter`（macOS） `Ctrl+J`（Windows/Linux）	改行を追加（送信せずに複数行入力）

7. 最後に — プロンプトエンジニアリングは要らない

ここまで読んで、「結局プロンプトの書き方を覚えなきゃいけないのか」と思った方もいるかもしれません。

Claude Code の使用量トラッキングツール「ccusage」の作者である ryoppippi さんは、こう述べています。

人間と喋るのにプロンプトエンジニアリングが要らないのと同じように、ccと話すのにプロンプトエンジニアリングなんか何も必要ない
適当にやりたいことだらっと音声入力すれば後は勝手にやってくれるので、大事なのはそれが正しいかどうかを見極める能力…
— ryoppippi (@ryoppippi) January 6, 2026

この意見には深く共感します。

この記事で紹介したことは「プロンプトエンジニアリング」ではなく、効果的なコミュニケーションです。人間の同僚に依頼するときも、「このファイルを直して」ではなく「@path/to/file.tsx の23行目あたり、nullチェックが抜けてる気がするんだけど見てくれる？」と言いますよね。

AIエージェントとの対話は、優秀な同僚との会話と同じです。特別な呪文は要りません。

俺たちがやるのはモデルの前で駄々をこねるだけ — ryoppippi

大事なのは、AIの出力が正しいかを判断する能力——つまり、鍛えるべきは「プロンプトの書き方」ではなく自分自身です。

Nano Banana Pro挿絵 - 開発者が自信を持ってAIの出力をレビューしている様子。「判断力」「あなた自身を鍛える」をイメージ。AIが出力したコードを、開発者が「よし、これでOK」とチェックしている図。

まとめ

4ヶ月間の開発経験から見えてきた、AIエージェント活用のポイントです。

プロンプトの書き方

@ファイルパス でコンテキストを明示
問題の背景・文脈を詳細に説明
明確な指示動詞（調査して、確認して、修正して）を使用
日本語でも主語を省略せず具体的に
仮説検証アプローチ — 「◯◯って△△だよね？」と自分の理解を検証する形で質問

設定済みツールの理解

Sequential Thinking MCP - 思考整理（自動）
Serena MCP - シンボルベースのコード調査（自動）
Context7 - 最新ドキュメント取得（自動）
Web Search - 「最新の情報を調査して」で発動

対話のコツ

調査 → 分析 → 提案 → 承認 → 実装の流れを意識
「どうでしょう？」で確認、「お願いします」で承認
フィードバックを与えながら段階的に進める
大きなタスクは小さく分解

Codex CLI基本操作

/model でモデル切り替え
Esc で質問中のリクエストをキャンセル
/undo または Esc×2 で会話をやり直し
codex resume --last でセッション再開
/compact でコンテキスト節約

AIエージェントは「魔法の杖」ではありませんが、適切に使えば強力なパートナーになります。この指南書が、皆さんのAIエージェント活用の一助になれば幸いです。

Nano Banana Pro挿絵 - 開発者とAIエージェントが握手している様子。「効果的な協働」「強力なパートナー」をイメージ。記事全体の締めくくりとして、人間とAIの協力関係を象徴する温かみのある図。

参考文献

“Claude Code: Best practices for agentic coding”, Anthropic Engineering Blog, https://www.anthropic.com/engineering/claude-code-best-practices ↩︎
“Knowledge cutoff”, Wikipedia, https://en.wikipedia.org/wiki/Knowledge_cutoff ↩︎
“Prompting best practices for Claude 4”, Anthropic Documentation, https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices ↩︎

#AIエージェント #Claude Code #プロンプトエンジニアリング #開発効率化 #MCP

Feature Branch Tech Team

Feature Branchの社内IT勉強会の内容を公開する技術ブログです