Claude Code/Codexプロンプト入門: 初心者が成果を出す5つの型

はじめに: うまいプロンプトより、迷わせない依頼文が強い

Claude CodeやCodexで成果が出ないとき、原因は「AIの機嫌」ではなく、依頼文の情報不足であることが多いです。プロンプトは単なるお願い文ではありません。プロンプトとは、AIエージェントに渡す作業指示書です。人間の新人に仕事を頼むときと同じで、目的、触ってよい範囲、合格ライン、確認方法、次の人への引き継ぎが抜けると、出力はぶれます。

この記事では、Claude Code/Codex初心者が最初に覚えるべき5つのプロンプト型を、実務で使えるテンプレート中心にまとめます。対象は、バグ修正、機能追加、記事生成、リポジトリ調査のような日常タスクです。難しいプロンプトエンジニアリングではなく、コピペして少し書き換えれば使える「依頼の型」として読んでください。

公式仕様は変わるため、細かな設定や権限は原典も確認します。Claude Codeは Claude Code overview、記憶の扱いは Memory、設定は Settings が基準です。Codex側は OpenAIのcode generation guide を入口にすると、コード生成やエージェント利用の考え方を追いやすいです。

5つの型の全体像

初心者は、毎回すべてを長文で書く必要はありません。次の5つだけを順番に入れると、失敗の多くを避けられます。

型	平易な意味	入れないと起きること
スコープ	作業範囲。どこまで触ってよいか	関係ないファイルまで変わる
リポジトリ文脈	既存コードの前提	似ていない実装や古い書き方になる
完了条件	合格ライン。Acceptance criteria	「できた」の基準がずれる
検証証拠	実行した確認の記録	動いたつもりで終わる
引き継ぎ	次の人が読む要約	後で何をしたか分からない

「スコープ」は作業の境界線です。「完了条件」は受け入れテストのようなものです。「検証証拠」は、npm test や git diff --check の結果、画面確認のメモなど、作業が本当に確認されたことを示す証拠です。難しい言葉に見えますが、要するに「どこを直し、何を守り、どう確認したか」を先に書くということです。

型1: スコープを切る

悪い依頼は、最初から広すぎます。

このアプリをいい感じに改善して。

この依頼では、UI、API、テスト、文章、設定のどれを変えてよいのか分かりません。Claude CodeやCodexは推測で動けますが、推測が増えるほど差分は大きくなります。

site/src/content/blog/5-tips-for-better-prompts.mdx だけを編集してください。
目的は、Claude Code初心者向けにプロンプト例を実務的にすることです。

触ってよい範囲:
- frontmatterのtitle, description, updatedDate, tags
- 本文

触らない範囲:
- heroImage
- slug
- 他の記事
- ビルド設定

このように「触ってよいもの」と「触らないもの」を分けると、エージェントは安全に動きやすくなります。Masaが記事更新で一番手戻りを減らせたのも、このスコープ指定でした。多言語記事や収益リンクがあるサイトでは、広い修正よりも小さな修正の連続の方がレビューしやすいです。

落とし穴は、「調査だけ」のつもりで編集を許してしまうことです。調査フェーズでは次のように書きます。

まず関連ファイルを読んで変更方針だけ出してください。まだ編集しないでください。
編集が必要なファイル名、理由、検証コマンドを短く一覧にしてください。

型2: リポジトリ文脈を渡す

Claude Code/Codexはコードを読めますが、あなたの事業目的や過去の失敗までは自動では分かりません。リポジトリ文脈とは、既存の設計、守るべき導線、似た実装、記事品質ルールなどの前提です。

このサイトはAstroのcontent collectionで記事を管理しています。
既存の品質記事は site/src/content/blog/claude-code-productivity-tips.mdx を参考にしてください。

守る文脈:
- 日本語記事は4000-6000字を目安にする
- 3つ以上の実例を入れる
- 公式リンクと内部リンクを両方入れる
- 収益導線として /thanks/, /products/, /training/ を自然に案内する

文脈がないと、きれいだけれどこのサイトに合わない記事になります。たとえば、ClaudeCodeLabでは「単なるAI一般論」より、「初心者が実際にコピペできるプロンプト」「失敗例」「検証結果」「教材や研修への次の行動」が重要です。

リポジトリ文脈を毎回書くのが面倒なら、CLAUDE.mdのベストプラクティス にあるように、プロジェクト規約を CLAUDE.md に寄せます。日々の作業の型は Claude Code生産性Tips も合わせて読むとつながります。

型3: 完了条件を先に置く

完了条件は「この条件を満たしたら作業完了」と判断できるリストです。英語では acceptance criteria と呼ばれます。初心者ほど、ここを曖昧にしがちです。

完了条件:
- 対象ファイルだけが変更されている
- descriptionは120文字以内
- Before/After例が各パターンにある
- バグ修正、機能追加、記事生成のテンプレートがある
- 失敗例と避け方が具体的
- 最後に検証結果と残るリスクを報告する

悪い例はこうです。

読みやすくして。SEOも強くして。終わったら教えて。

「読みやすい」「SEOに強い」は大事ですが、判定できません。良い依頼では、タイトルにキーワードを入れる、descriptionを短くする、内部リンクを追加する、本文量を増やす、CTAを入れる、のように分解します。

機能追加なら、完了条件はもっと技術寄りにします。

完了条件:
- 既存UIの見た目を崩さない
- 型エラーがない
- バリデーションとエラー表示を追加する
- 関連する単体テストを1つ以上追加する
- npm test と npm run build の結果を報告する

型4: 検証証拠を求める

「実装しました」だけでは足りません。初心者がClaude Code/Codexを使うときほど、最後に証拠を求めます。

最後に verification receipt を出してください。

形式:
- 変更ファイル:
- 実行したコマンド:
- 結果:
- 手動確認:
- 確認できなかったこと:
- 残るリスク:

verification receipt は、検証の領収書のようなものです。難しい仕組みではなく、何を確認したかを短く残すだけです。詳しい考え方は Claude Code検証レシートワークフロー にもまとめています。

失敗例は、ログを要約しすぎることです。

ビルドが落ちたので直して。

これでは原因を追いにくいです。次のように、コマンド、エラー、期待結果をそのまま渡します。

実行コマンド:
npm run build

エラー:
Type error: Property 'name' does not exist on type 'User | undefined'.
File: src/components/Profile.tsx:15:22

期待:
型エラーを最小差分で修正し、npm run build を再実行してください。

型5: 引き継ぎまで頼む

AIエージェント作業は、1回の会話で完結しないことがあります。途中で別セッション、別担当者、翌日の自分に渡すなら、handoff、つまり引き継ぎメモが必要です。

最後に handoff note を書いてください。

含める内容:
- 目的
- 変更したこと
- 変更しなかったこと
- 検証結果
- 次に見るべきファイル
- 未解決の注意点

引き継ぎを頼まないと、後で差分だけを読んで意図を推測することになります。特に記事生成、SEO改善、CTA改善では、「なぜこのリンクを置いたのか」「なぜこの表現にしたのか」が差分だけでは見えません。

チームで使うなら、チーム引き継ぎルール を先に決めておくと、レビュー担当者が迷いません。

コピペ用テンプレート

バグ修正テンプレート

目的:
  発生中のバグを最小差分で直したい。

症状:
  何が起きているか:
  期待する動き:
  実際の動き:

再現手順:
  1.
  2.
  3.

スコープ:
  触ってよいファイル:
  触らないファイル:

文脈:
  参考にする既存実装:
  守る設計ルール:

完了条件:
  原因候補を説明してから修正する。
  関連テストを追加または更新する。
  検証コマンドと結果を報告する。

新機能テンプレート

目的:
  小さな機能を安全に追加したい。

追加する機能:
  ユーザーに見える変化:
  API/DB/設定の変更有無:

制約:
  既存UIを大きく変えない。
  既存の命名規則に合わせる。
  大きな設計変更が必要なら、実装前に理由を説明する。

完了条件:
  実装、型、エラー表示、テスト、検証結果をそろえる。

記事生成・リライトテンプレート

目的:
  初心者向けのevergreen記事として品質を上げたい。

読者:
  Claude Code/Codexを使い始めた個人開発者または小規模チーム。

必須要素:
  3つ以上の実例。
  Before/Afterのプロンプト例。
  失敗例と避け方。
  コピペできるテンプレート。
  公式リンク、内部リンク、CTA。

完了条件:
  descriptionは120文字以内。
  frontmatterを壊さない。
  コードフェンスが閉じている。
  最後にセルフレビューを報告する。

3つの実務ユースケース

1つ目は、ログイン後の白画面バグです。「白画面を直して」ではなく、再現手順、期待結果、コンソールエラー、触ってよいファイルを書きます。最後にテスト結果を求めることで、症状だけ消す修正を避けられます。

2つ目は、問い合わせフォームに「相談種別」を追加する小さな機能です。training, consulting, other の選択肢、バリデーション、送信API、計測イベントまで書けば、収益導線を壊しにくくなります。

3つ目は、記事生成です。ClaudeCodeLabの記事なら、本文量、実例、失敗例、公式リンク、内部リンク、CTA、実際に試した結果の段落まで完了条件に入れます。これにより、薄いまとめ記事ではなく、読者が次の行動を取れる記事になります。

初心者がよく落ちる3つの罠

一つ目は、最初から「全部やって」と頼むことです。AIエージェントは広い作業も進められますが、広いほど判断が増えます。判断が増えると、使っていないライブラリを追加する、既存の命名規則を外す、別の修正まで混ぜる、といった事故が起きます。最初の依頼は、1ファイル、1画面、1関数、1記事のように小さく切る方が結果的に早いです。

二つ目は、良い例だけを渡して失敗例を渡さないことです。「この実装に合わせて」と言うだけでは、避けたい書き方が伝わりません。たとえば「疑似コードで済ませない」「テスト未実行で完了と言わない」「収益リンクを消さない」「ユーザーの変更を勝手に戻さない」のように、嫌な結果を短く書くと精度が上がります。これは命令を細かく縛るためではなく、レビュー基準を先に共有するためです。

三つ目は、最後の確認を人間の記憶に任せることです。作業中は順調に見えても、コードフェンスの閉じ忘れ、descriptionの文字数超過、不要なファイル変更、リンク切れは後から見つかります。検証証拠と引き継ぎを必ず求めると、作業の最後に「何を確認し、何を確認できなかったか」が残ります。Claude Code/Codexを信頼することと、証拠を残すことは矛盾しません。むしろ、証拠があるから安心して任せられます。

実務では、この最後の一手が収益にも影響します。教材リンク、相談導線、無料チートシートへの誘導は、記事の末尾だけでなく本文中の文脈にも支えられます。検証メモに「CTAを確認した」「内部リンクを確認した」と残しておけば、公開後に売上導線が消えていた、という事故を防ぎやすくなります。小さな記録が、次の改善の土台になります。

小さなプロンプトQAルーブリック

送信前に、次の5点を1つずつ確認します。

点数	観点	自問
0-2	スコープ	触るファイルと触らないファイルが分かるか
0-2	文脈	参考実装、読者、事業目的があるか
0-2	完了条件	合格ラインが判定可能か
0-2	検証	実行コマンドや手動確認が指定されているか
0-2	引き継ぎ	最後に何を報告すべきか明確か

8点以上なら、そのまま依頼してよいことが多いです。5点以下なら、Claude Code/Codexの能力ではなく、依頼文の材料が足りません。

実行して使うプロンプト依頼書

「いい感じに直して」ではなく、毎回同じ形の依頼書を作ると失敗が減ります。次のスクリプトは prompt-brief.md を生成します。対象ファイルと完了条件を書き換えてから Claude Code や Codex に渡すと、スコープ、制約、検証方法が最初から揃います。

cat > prompt-brief.md <<'EOF'
# Task brief for Claude Code / Codex

Goal:
- Improve one article or feature without changing unrelated files.

Scope:
- May edit: site/src/content/blog/example.mdx
- Do not edit: hero images, routes, unrelated articles, billing code.

Context to read first:
- AGENTS.md
- A similar high-quality article
- The target file

Acceptance criteria:
- The intro explains who the reader is and why this matters.
- The draft includes at least three concrete examples.
- Code or prompt templates are copy-pasteable.
- Pitfalls and verification steps are explicit.
- Internal links and a natural CTA are included.

Verification:
- npm run build
- node scripts/check-code-fences.mjs
- Read the changed file once as a reviewer.

Return:
- What changed
- Checks run
- Remaining risks
EOF

CTA: テンプレートを自分用に固定する

この型を毎回ゼロから書く必要はありません。まずは 無料チートシート で日常コマンドと安全な進め方を確認してください。繰り返し使うなら 商品一覧 のプロンプトテンプレートやセットアップ教材で、バグ修正、レビュー、記事生成の型を手元に置くのが早いです。チーム導入、CLAUDE.md整備、権限設計、レビュー運用までまとめて整えたい場合は Claude Code研修・導入相談 が向いています。

この記事で紹介した内容を実際に試した結果、Masaの運用では「スコープ」「完了条件」「検証証拠」を先に書いた依頼が最も安定しました。特に多言語記事と収益CTAを含む作業では、引き継ぎメモまで求めるだけで、翌日のレビュー時間が短くなりました。