Claude Code/Codex 高度プロンプト設計: 実務で崩れないタスクブリーフの作り方

Claude Code や Codex で成果が安定しないとき、原因はモデルの賢さより「仕事の渡し方」にあることが多いです。 高度なプロンプトエンジニアリングとは、かっこいい呪文を書くことではありません。タスク範囲、完了条件、読むべき文脈、確認方法、引き継ぎを一つの作業設計にまとめることです。

この記事では、Claude Code/Codex にそのまま渡せる「プロンプトパケット」を作る方法を解説します。初心者でも使えるように型から始めますが、狙いはチーム運用でも壊れない高度なワークフローです。基本の型をまだ固めていない場合は、先に Claude Code/Codexプロンプト入門 と CLAUDE.mdのベストプラクティス を読むとつながります。

公式仕様は変わるため、機能名や設定は必ず一次情報で確認してください。Claude Code は Claude Code overview、プロジェクト記憶は Memory、プロンプト改善の前提は Anthropic prompt engineering overview が入口です。Codex 側は OpenAI Codex docs と AGENTS.md guidance を確認します。

高度化の正体は「依頼文」ではなく「作業契約」

悪いプロンプトは短すぎるだけではありません。判断基準がない、触ってはいけない範囲がない、検証方法がない、最後に何を報告すべきかがない。この4つが欠けると、AIエージェントは推測で動きます。

実務で使うプロンプトは、次の6要素を含む作業契約にします。

要素	書くこと	欠けたときの失敗
Goal	何を達成するか	似ているが違う成果物になる
Scope	触ってよいファイル、触らないファイル	関係ないリファクタリングが混ざる
Context	先に読む資料、似た実装、公式リンク	古い実装や想像で書く
Constraints	守る制約、禁止事項	依存追加、API変更、文体崩れが起きる
Acceptance criteria	完了条件	「できた」の基準が曖昧になる
Verification	実行する確認と報告形式	動作確認なしで終わる

Anthropic のプロンプトエンジニアリング概要でも、成功条件と評価方法を先に持つことが前提として扱われています。Claude Code/Codex のようにファイル編集やコマンド実行まで行うエージェントでは、この前提がさらに重要です。

プロンプトパケットを1ファイルにする

チャット欄に長文を毎回打つより、prompt-packet.md のようなファイルにまとめるほうが再利用しやすく、レビューもしやすくなります。次の Bash は、最小限のパケットを作るコピペ可能な例です。

cat > prompt-packet.md <<'EOF'
# Goal
Improve one published article so it is practical, accurate, and ready for review.

# Scope
May edit:
- site/src/content/blog/example-article.mdx

Do not edit:
- heroImage
- slug
- unrelated articles
- package or deployment files

# Context to read
- AGENTS.md
- site/src/content/blog/claude-md-best-practices.mdx
- Official docs relevant to the article topic

# Constraints
- Preserve existing frontmatter keys unless this task explicitly changes them.
- Use copy-pasteable examples, not pseudocode.
- Avoid unsupported claims. Link to official docs for tool behavior.
- Keep paragraphs short enough for mobile reading.

# Acceptance criteria
- updatedDate is 2026-06-02.
- The article has at least three concrete use cases.
- The article names specific pitfalls and how to avoid them.
- The article includes an internal link, an official external link, and a natural CTA.
- The final section explains what was actually verified.

# Verification
- node scripts/check-code-fences.mjs
- node scripts/check-updated-article-quality.mjs
- Read the diff once as a critical reviewer.

# Return format
- Changed files
- Key improvements
- Checks run
- Residual risks
EOF

このファイルを Claude Code/Codex に渡すときは、「まず prompt-packet.md を読み、編集前に対象ファイルと関連資料を確認してください」と付けます。ポイントは、AIに考えさせる前に境界を固定することです。境界がないまま「品質を上げて」と頼むと、良かれと思って別ページ、設定、画像、リンク構造まで触ることがあります。

パケットを機械的に点検する

プロンプトは自然文なので、品質が気分に寄りやすいです。そこで最低限のチェックをスクリプト化します。次の Node.js スクリプトは、見出し、禁止範囲、検証コマンドが入っているかを確認します。

// save as check-prompt-packet.cjs
const fs = require("node:fs");

const file = process.argv[2] || "prompt-packet.md";
const text = fs.readFileSync(file, "utf8");

const required = [
  "# Goal",
  "# Scope",
  "# Context to read",
  "# Acceptance criteria",
  "# Verification",
  "# Return format",
];

const missing = required.filter((heading) => !text.includes(heading));
const hasDoNotTouch = /do not (edit|change|touch)/i.test(text);
const hasCommand = /npm run|npm test|pnpm |yarn |node scripts\//i.test(text);

if (missing.length || !hasDoNotTouch || !hasCommand) {
  console.error("Prompt packet is not ready.");
  if (missing.length) console.error("Missing headings: " + missing.join(", "));
  if (!hasDoNotTouch) console.error("Add an explicit do-not-touch boundary.");
  if (!hasCommand) console.error("Add at least one verification command.");
  process.exit(1);
}

console.log("Prompt packet looks actionable.");

実行方法は次の通りです。

node check-prompt-packet.cjs prompt-packet.md

この程度でも効果があります。Masa が記事更新で失敗したときは、たいてい「触らない範囲」か「最後に出す証拠」が抜けていました。人間のレビューでも同じで、依頼文に完了条件がなければ、レビュー担当者は好みで判断するしかありません。

完了条件は「良くして」から「判定できる」に変える

「読みやすくして」「SEOを強くして」「実務的にして」は方向性としては正しいですが、AIには判定できません。完了条件は、通るか落ちるかが分かる形にします。

悪い例:

記事をもっと良くしてください。SEOも意識してください。

実務で使う例:

記事をClaude Code初心者が実行できる実務ガイドにしてください。

完了条件:
- タイトルに「Claude Code」「プロンプト設計」を含める。
- descriptionは120文字以内。
- 本文に3つ以上のユースケースを入れる。
- 悪いプロンプト例と改善例をそれぞれ2つ以上入れる。
- 公式ドキュメントへの外部リンクと、関連する内部リンクを入れる。
- 最後に「実際に確認したこと」を1段落で書く。
- 変更後にコードフェンス検査を実行し、結果を報告する。

機能実装なら、さらに技術寄りにします。

完了条件:
- 既存の公開APIの型を変えない。
- 入力バリデーションとエラー表示を追加する。
- 失敗ケースのテストを1つ以上追加する。
- npm test と npm run build の結果を報告する。
- 変更したファイルと、変更しなかった理由のある関連ファイルを説明する。

完了条件は細かく縛るためではなく、レビュー基準を共有するためにあります。AIが迷う余地を減らし、人間も「この仕事は終わったか」を同じ基準で見られます。

文脈予算を決める

Claude Code の Memory ドキュメントでは、CLAUDE.md や自動メモリは文脈として読み込まれるが、強制設定ではないと説明されています。つまり、長く書けば守られるわけではありません。むしろ長すぎる文脈は、重要な指示を埋もれさせます。

文脈は3階層に分けます。

階層	例	入れ方
常時必要	ビルドコマンド、命名規則、禁止領域	CLAUDE.md や AGENTS.md
タスク固有	今回の対象ファイル、似た実装、品質基準	prompt-packet.md
必要になったら読む	長い仕様書、古い議事録、大量ログ	ファイル名だけ渡し、必要なら読む

よくある落とし穴は、参考資料を全部貼ることです。大量の議事録、古い設計メモ、未整理のログをまとめて渡すと、エージェントは何を優先すべきか分かりません。プロンプトには「読む順番」と「採用してよい基準」を書きます。

Context to read in order:
1. AGENTS.md for project rules.
2. The target article.
3. One similar high-quality article for tone and structure.
4. Official docs only for tool behavior.

Ignore:
- Old brainstorming notes unless they contradict the current implementation.
- Unrelated product pages.
- Generated files and build output.

この指定だけで、探索時間と不要な編集が減ります。特に並列作業中は、他の人が触っているファイルを読ませすぎないことも安全性につながります。

例と制約を混ぜない

プロンプトに例を入れるのは有効ですが、例は「真似してほしい形」であり、制約は「守るべき境界」です。ここを混ぜると失敗します。

失敗例:

このページみたいにしてください。

この依頼だと、構成を真似するのか、文体を真似するのか、CTA位置を真似するのか、すべて曖昧です。改善例はこうです。

Reference style:
- Use site/src/content/blog/claude-code-productivity-tips.mdx only for section density and CTA placement.
- Do not copy its examples or claims.

Constraints:
- Keep this article focused on prompt engineering.
- Do not introduce pricing claims.
- Preserve heroImage and slug.

制約はなるべく否定形だけで終わらせません。「外部ライブラリを追加しない」だけでなく、「既存の依存だけを使う」と書くほうが実装に落ちます。「大きく変えない」ではなく、「公開APIの型は変えない」「対象ファイル以外は編集しない」と書きます。

安全な反復ループを指定する

高度なプロンプトほど、一発で全部やらせるより、反復ループを明示したほうが安定します。おすすめは次の順番です。

1. 読む: 対象ファイル、規約、似た実装を確認する。
2. 計画する: 変更するファイルと理由を短く出す。
3. 編集する: スコープ内だけを変更する。
4. 検証する: コマンド、差分確認、目視確認を行う。
5. 報告する: 変更点、証拠、残リスクを返す。

プロンプトではこう書けます。

Workflow:
- First inspect the target file and the nearest quality reference.
- If the change is larger than two files, explain the plan before editing.
- Edit only the files listed in Scope.
- After editing, run the Verification commands if feasible.
- End with a verification receipt, not a general summary.

「検証レシート」は、作業の領収書です。詳しい型は Claude Code検証レシートワークフロー にまとめていますが、最小形は次で十分です。

Verification receipt:
- Changed files:
- Commands run:
- Results:
- Manual checks:
- Could not verify:
- Residual risks:

3つ以上の実務ユースケース

1つ目は、バグ修正です。症状、再現手順、期待結果、ログ、触ってよい範囲を渡します。「直して」ではなく、「原因候補を説明してから最小差分で直し、失敗テストを追加して」と書きます。これにより、たまたま見た目だけ直す修正を避けやすくなります。

2つ目は、小さな機能追加です。ユーザーに見える変化、APIやDB変更の有無、既存UIのどれに合わせるか、テスト対象を渡します。たとえば問い合わせフォームに分類項目を追加するなら、選択肢、バリデーション、送信ペイロード、分析イベント、翻訳の扱いまで完了条件に入れます。

3つ目は、記事リライトです。対象読者、検索意図、文字量、必須の実例、失敗例、内部リンク、CTA、確認した公式資料を渡します。ClaudeCodeLab ではこの用途が多く、薄い記事を直すときほど「Masaが実際に試した結果」まで指定すると、単なる要約記事になりにくくなります。

4つ目を挙げるならコードレビューです。レビューは修正よりも出力形式が大事です。致命度、ファイル名、行番号、再現条件、修正案、テスト不足を指定します。「全体的に見て」ではなく、「セキュリティ、データ破壊、公開API変更、テスト不足を優先して」と書くと実務のレビューに近づきます。

よくある失敗と回避策

失敗1: 目的と手段が混ざる。 「リファクタリングして高速化してSEOも直して」のような依頼は、複数の仕事を一つに詰めています。回避策は、最初のパケットでは目的を一つにすることです。

失敗2: 禁止事項だけを書く。 「絶対に壊さないで」「余計なことをしないで」だけでは、何が余計か分かりません。回避策は、許可範囲も同時に書くことです。

失敗3: 公式情報と推測を混ぜる。 Claude Code/Codex の機能は変わります。エージェントのツール挙動、設定、メモリ、AGENTS.md などは公式リンクを基準にし、記事内で断定しすぎないようにします。

失敗4: 検証を「できれば」で済ませる。 時間がないときほど、最低限の検証を指定します。実行できなかった場合も「何を実行できなかったか」を報告させると、次の人が判断できます。

失敗5: プロンプトを毎回チャットに閉じ込める。 うまくいった依頼はファイル化します。prompt-packet.md、CLAUDE.md、チームのレビュー規約に分けると、翌週も同じ品質で再利用できます。チーム導入では Claude Codeチーム引き継ぎルール も役に立ちます。

CTA: テンプレート化してからチームに広げる

この型を毎回ゼロから書く必要はありません。まずは 無料チートシート で日常の確認項目を手元に置き、繰り返し使うプロンプトは 商品・テンプレート一覧 で比較してください。チームで CLAUDE.md、権限、レビュー、検証レシート、記事品質チェックまでそろえるなら、Claude Code研修・相談 で実際のリポジトリに合わせて設計するのが近道です。

この記事で実際に確認したこと

この記事では、Claude Code がコードベースを読み、ファイル編集やコマンド実行を行うという説明を公式 overview で確認し、CLAUDE.md と auto memory が強制設定ではなく文脈として扱われる点を Memory ドキュメントで確認しました。さらに、プロンプト改善の前に成功条件と評価方法を持つべきという前提を Anthropic の prompt engineering overview で確認し、Codex 側のプロジェクト指示は OpenAI の Codex docs と AGENTS.md guidance に合わせました。実務上の結論は、プロンプトを「依頼文」ではなく、検証可能な作業契約としてファイル化することです。