ベストプラクティス — プロンプト変換ツール

Claude が成功するために必要なものを追加してプロンプトを変換します。

はじめに

ユーザーのリクエストに基づいて:

ユーザーが変換するプロンプトを提供: → AskUserQuestion を使用して質問します:

• 質問: 「このプロンプトをどのように改善すればよいですか?」
• ヘッダー: 「モード」
• オプション:
  1. 直接変換 — 「ベストプラクティスを適用して改善版を出力します」
  2. まずコンテキストを構築 — 「まずコードベースのコンテキストと意図分析を収集します」

ユーザーが学習・理解を求めている: → 「5つの変換原則」セクションを表示

ユーザーが例を求めている: → references/before-after-examples.md へリンク

ユーザーがプロンプトを評価するよう求めている: → このドキュメント最後の「成功基準」評価ルーブリックを使用

---

「直接変換」の場合

下記の5つの原則を適用し、改善されたプロンプトを直ちに出力します。

「まずコンテキストを構築」の場合

3つの並列エージェントを起動してコンテキストを収集します:

Task ツールを使用してこれらのエージェントを並列実行します:

- Task task-intent-analyzer("[ユーザーのプロンプト]")
- Task best-practices-referencer("[ユーザーのプロンプト]")
- Task codebase-context-builder("[ユーザーのプロンプト]")

各エージェントが返すもの

エージェント	ミッション	返すもの
task-intent-analyzer	ユーザーが何をしようとしているかを理解	タスクタイプ、ギャップ、エッジケース、変換ガイダンス
best-practices-referencer	references/ から関連パターンを検出	一致する例、避けるべきアンチパターン、変換ルール
codebase-context-builder	このコードベースを探索	特定ファイルパス、類似実装、規約

エージェントから結果が返された後

1. 結果を統合 — 意図 + ベストプラクティス + コードベースコンテキストを組み合わせ
2. マッチングパターンを適用 — best-practices-referencer の例をテンプレートとして使用
3. コードベースに根付かせ — codebase-context-builder の特定ファイルパスを追加
4. プロンプトを変換 — すべての収集コンテキストで5つの原則を適用
5. 出力 — 改善されたプロンプトと変更前後の比較を表示

エージェント定義

エージェントは agents/ で定義されています:

• agents/task-intent-analyzer.md — 意図、ギャップ、エッジケースを分析
• agents/best-practices-referencer.md — references/ から関連例とパターンを検出
• agents/codebase-context-builder.md — ファイルと規約についてコードベースを探索

---

変換ワークフロー

変換する場合 (モード選択後):

1. 欠落しているものを識別 — 下記5つの原則と照らし合わせ
2. 欠落要素を追加 — 検証、コンテキスト、制約、段階、豊富なコンテンツ
3. 改善されたプロンプトを出力 — コードブロック内、コピーペースト可能な形式で
4. 変更内容を表示 — 変更前後の簡潔な比較

---

5つの変換原則

優先順位の順に適用:

1. 検証を追加 (最高優先度)

最もレバレッジが効く改善。 Claude は自分の作業を検証できるときに劇的に良い結果を出します。

欠落している内容	追加するもの
成功基準がない	期待される入出力を持つテストケース
UI の変更	「スクリーンショットを撮影してデザインと比較」
バグ修正	「失敗するテストを書いてから修正」
ビルドの問題	「修正後、ビルドが成功することを確認」
リファクタリング	「各変更後にテストスイートを実行」
ルート原因の強制がない	「エラーを抑制せず、ルート原因に対応」
検証レポートがない	「実行したもの、合格したもの、検証内容をまとめる」

変更前: 「メール検証を実装」
変更後: 「validateEmail 関数を作成。テストケース: user@example.com → true,
         invalid → false, user@.com → false。実装後、テストを実行」

変更前: 「API エラーを修正」
変更後: 「/api/orders エンドポイントが大規模な注文で 500 を返す。
         OrderService.ts のエラーを確認。エラーを抑制せず、ルート原因に対応。
         修正後、テストスイートを実行して、合格したものと検証した内容を要約」

2. 具体的なコンテキストを提供

曖昧な参照を正確な位置と詳細で置き換えます。

曖昧	具体的
「コード」	src/auth/login.ts
「バグ」	「Y が起こるとき、ユーザーが X を報告」
「API」	「routes.ts の /api/users エンドポイント」
「その関数」	142 行目の processPayment()

コンテキストを追加する 4 つの方法:

戦略	例
タスクをスコープ	「ユーザーがログアウトしている場合を除くエッジケースをカバーする foo.py のテストを書く。モックは避ける」
ソースを指す	「ExecutionFactory の Git 履歴を調べて、その API がどのように進化したかを要約」
パターンを参照	「HotDogWidget.php を見て、カレンダーウィジェット用にそのパターンに従う」
症状を説明	「ユーザーがセッションタイムアウト後にログインが失敗すると報告。src/auth/ を確認、特にトークン更新」

プロジェクト CLAUDE.md を尊重:

プロジェクトが CLAUDE.md を持っている場合、変換されたプロンプトは:

• プロジェクト規約に矛盾しない
• 関連する場合、プロジェクト固有のパターンを参照
• 適用されるプロジェクト制約を記述

変更前: 「新しい API エンドポイントを追加」
変更後: 「GET /api/products エンドポイントを追加。このプロジェクトの API 規約について
         CLAUDE.md を確認。routes/users.ts のパターンに従う。実装後、API
         テストを実行」

変更前: 「ログインバグを修正」
変更後: 「ユーザーがセッションタイムアウト後にログインが失敗すると報告。src/auth/
         の認証フロー、特にトークン更新を確認。問題を再現する失敗テストを
         作成して修正」

3. 制約を追加

Claude が何をするべきではないかを伝えます。過度なエンジニアリングと不要な変更を防ぎます。

制約タイプ	例
依存関係	「新しいライブラリなし」、「既存の依存関係のみを使用」
テスト	「モックを避ける」、「テストで実際のデータベースを使用」
スコープ	「無関係なコードをリファクタしない」、「認証モジュールのみをタッチ」
アプローチ	「ルート原因に対応、エラーを抑制しない」、「後方互換性を維持」
パターン	「既存のコードベース規約に従う」、「utils.ts のスタイルに合わせる」

変更前: 「カレンダーウィジェットを追加」
変更後: 「月選択と年ページネーション付きカレンダーウィジェットを実装。
         HotDogWidget.php のパターンに従う。コードベースで既に使用されている
         ライブラリ以外のライブラリなしで、ゼロから構築」

4. 複雑なタスクを段階で構造化

より大きなタスク場合、探索を実装から分離します。

4段階パターン:

段階 1: 探索
「src/auth/ を読んでセッションとログインの処理方法を理解。
 また、シークレットの環境変数の管理方法を見る」

段階 2: 計画
「Google OAuth を追加したい。どのファイルが変わる必要がある?
 セッションフローは? 計画を立てる」

段階 3: 実装
「計画から OAuth フローを実装。コールバックハンドラーのテストを
 書いて、テストスイートを実行して、失敗を修正」

段階 4: コミット
「わかりやすいメッセージでコミットして PR を開く」

段階を使う場合:

• アプローチが不明確
• 変更が複数ファイルを変更
• 変更されるコードに不慣れ

段階をスキップする場合:

• diff を 1 文で説明できる
• タイプミスを修正、ログ行を追加、変数をリネーム

変更前: 「OAuth を追加」
変更後: 「src/auth/ を読んで現在のセッション処理を理解。OAuth 追加の
         計画を作成。その後、計画に従って実装。テストを書いて合格を検証」

5. 豊富なコンテンツを含める

Claude が直接使用できるサポート資料を提供します。

コンテンツタイプ	提供方法
ファイル	@filename を使用して参照
画像	スクリーンショットを直接貼り付け
エラー	説明ではなく、実際のエラーメッセージを貼り付け
ログ	cat error.log | claude でパイプ
URL	関連ドキュメントへのリンク

変更前: 「ダッシュボードを見栄え良くする」
変更後: 「[スクリーンショットを貼り付け] ダッシュボード用にこのデザインを実装。
         結果のスクリーンショットを撮影して元のものと比較。
         すべての差異をリストして修正。768px と 1024px ブレークポイントで
         レスポンシブ動作を確認」

変更前: 「ビルドが失敗している」
変更後: 「ビルドがこのエラーで失敗: [実際のエラーを貼り付け]。修正して
         ビルドが成功することを検証。ルート原因に対応、エラーを抑制しない」

---

出力形式

プロンプトを変換するときに出力:

**元のプロンプト:** [ユーザーのプロンプト]

**改善版:**

[変換されたプロンプトをコードブロック内に]

**追加された内容:**
- [欠落していて追加されたもの]
- [別の改善点]
- [その他]

---

簡単な変換例

バグ修正

変更前: 「ログインバグを修正」

変更後: 「ユーザーがセッションタイムアウト後にログインが失敗すると報告。
src/auth/ の認証フロー、特にトークン更新を確認。問題を再現する失敗テスト
を作成して修正。認証テストスイートを実行して検証」

追加された内容: 症状、位置、検証 (失敗するテスト)、成功基準

機能実装

変更前: 「検索機能を追加」

変更後: 「製品ページ用に検索を実装。パターンについて ProductList.tsx の
フィルタリング処理を見る。検索は名前とカテゴリーでフィルタ。テスト:
空のクエリはすべてを返す、部分一致が機能、結果なしはメッセージを表示。
外部検索ライブラリなし」

追加された内容: 位置、参照パターン、具体的な動作、テストケース、制約

リファクタリング

変更前: 「コードを改善」

変更後: 「utils.js を ES2024 機能を使用しながら、同じ動作を維持するように
リファクタ。具体的に: コールバックを async/await に変換、オプショナル
チェーニングを使用、適切な TypeScript 型を追加。各変更後にテストスイート
を実行して、何も壊れていないことを確認」

追加された内容: 具体的な変更、制約 (同じ動作)、各ステップ後の検証

テスト

変更前: 「foo.py 用にテストを追加」

変更後: 「ユーザーがログアウトしている場合を除くエッジケースをカバーする
foo.py 用テストを作成。モックを避ける。tests/ の既存テストパターンを使用。
テストケース: logged_out_user は 401 を返す、expired_session はログインに
リダイレクト、invalid_token は AuthError を発生」

追加された内容: 具体的なエッジケース、制約 (モックなし)、パターン参照、テストケース

デバッグ

変更前: 「API が遅い」

変更後: 「/api/orders エンドポイントが 3 秒以上かかる。OrderService.ts の
データベースクエリをプロファイル。N+1 クエリや欠落インデックスを探す。
パフォーマンス問題を修正して、応答時間が 500ms 以下であることを検証」

追加された内容: 特定エンドポイント、位置、何を探すか、測定可能な成功基準

UI 変更

変更前: 「ボタンのスタイルを修正」

変更後: 「[デザインのスクリーンショットを貼り付け] プライマリボタンをこの
デザインに合わせて更新。Button.tsx と tailwind.config.js のテーマを確認。
変更後スクリーンショットを撮影してデザインと比較。すべての差異をリスト」

追加された内容: デザイン参照、ファイルの位置、ビジュアル検証

探索

変更前: 「認証はどのように機能している?」

変更後: 「src/auth/ を読んでこのコードベースの認証がどのように機能するか
を説明。カバー: セッションの作成方法、トークンの更新方法、シークレットの
保存場所。Markdown ドキュメントで要約」

追加された内容: 特定ファイル、回答すべき具体的な質問、出力形式

マイグレーション

変更前: 「React 18 にアップグレード」

変更後: 「React 17 から React 18 にマイグレーション。まず [URL] の
マイグレーションガイドを読む。次に、廃止された API を使用しているすべての
コンポーネントを特定。一度に 1 つのコンポーネントを更新して、各更新後に
テストを実行。無関係なコードは変更しない」

追加された内容: 段階的なアプローチ、参照ドキュメント、段階ごとの検証、スコープ制約

検証レポート付き

変更前: 「API エラーを修正」

変更後: 「/api/orders エンドポイントが大規模な注文で 500 を返す。
OrderService.ts のエラーを確認。エラーを抑制せず、ルート原因に対応。
修正後、テストスイートを実行して、合格したものと検証した内容を要約」

追加された内容: 症状、位置、ルート原因の強制、検証レポート

---

変換チェックリスト

出力する前に、改善されたプロンプトが次を持つことを確認:

• 検証 — それが機能したことを知る方法 (テスト、スクリーンショット、出力)
• 位置 — 特定ファイル、関数、またはエリア
• 制約 — 何をするべきではないか
• 単一タスク — 複合ではない (必要に応じて分割)
• 段階 — 複雑な場合、探索 → 計画 → 実装として構造化
• ルート原因 — バグの場合: 「ルート原因に対応、抑制しない」
• CLAUDE.md — 存在する場合、プロジェクト規約を尊重

---

クイック プロンプト品質チェック

プロンプトをこれらの側面で評価:

側面	0 (欠落)	1 (部分的)	2 (完全)
検証	なし	「テストして」	具体的なテストケース + レポート
位置	「コード」	「認証モジュール」	src/auth/login.ts:42
制約	なし	暗黙的	「X を避ける、Y なし、ルート原因のみ」
スコープ	曖昧	部分的	単一で明確なタスク

クイック評価:

• 0-3: 大幅な改善が必要
• 4-5: 改善が必要
• 6-8: 良好、マイナーな調整

---

フォールバック: それでも曖昧な場合

ユーザーが「直接変換」を選択したが、プロンプトに十分なコンテキストが欠落している場合、1 つの自然な質問をする:

「Claude がこれをうまくやるために何を知る必要がありますか?」

尋問しないでください — 1 つの質問で十分です。学んだことで変換します。

---

修正する一般的なアンチパターン

アンチパターン	問題	修正
「バグを修正」	症状なし、位置なし	ユーザーが報告したもの + どこを見るかを追加
「テストを追加」	スコープなし、ケースなし	具体的なエッジケース + テストパターンを指定
「改善する」	「改善」の基準なし	具体的な改善を定義
「X を実装」	検証なし	テストケースまたは成功基準を追加
「コードを更新」	制約なし	何を保持するか、何を避けるかを追加

---

成功基準 — プロンプト品質評価

適切に変換されたプロンプトは次のチェックを通過:

原則 1: 検証 ✅

チェック	合格	不合格
成功基準がある	「テストを実行」、「スクリーンショットが一致」	なし
測定可能な結果	「応答 < 500ms」	「速くする」
自己検証可能	Claude は自分の作業を確認できる	人間の判断が必要
ルート原因が強制	「エラーを抑制しない」	アプローチについて沈黙

原則 2: 具体性 ✅

チェック	合格	不合格
ファイル位置	src/auth/login.ts	「認証コード」
関数/クラス名	processPayment()	「その関数」
行番号 (関連の場合)	:42	「どこかにある」
CLAUDE.md 尊重	「プロジェクト規約を確認」	プロジェクトルールを無視

原則 3: 制約 ✅

チェック	合格	不合格
何をしないか	「モック回避」、「新しい依存なし」	オープンエンド
スコープ境界	「認証モジュールのみをタッチ」	無制限スコープ
従うパターン	「UserService.ts スタイルを一致」	参照なし

原則 4: 構造 ✅

チェック	合格	不合格
単一タスク	1 つの明確な目的	複数の目標
段階化 (複雑な場合)	「探索 → 計画 → 実装」	コードに直進
適切な深さ	タスクの複雑さに合わせる	過度/過度ではない

原則 5: 豊富なコンテンツ ✅

チェック	合格	不合格
実際のエラー	エラーメッセージを貼り付け	「壊れている」
スクリーンショット (UI)	イメージを添付	「ボタンがおかしく見える」
ファイル参照	@filename またはパス	「そのファイル」

全体的な品質スコア

スコア	意味	合格原則
⭐⭐⭐⭐⭐	優秀	すべて 5 つ
⭐⭐⭐⭐	良好	5 つ中 4 つ
⭐⭐⭐	許容	5 つ中 3 つ
⭐⭐	改善が必要	5 つ中 2 つ
⭐	不十分	1 つ以下

目標: 変換されたすべてのプロンプトが ⭐⭐⭐⭐ または ⭐⭐⭐⭐⭐ をスコア

---

参照ファイル

さらに多くの例とパターン:

• 50 以上の例: references/before-after-examples.md を参照
• プロンプトテンプレート: references/prompt-patterns.md を参照
• タスクワークフロー: references/common-workflows.md を参照
• 避けるべきこと: references/anti-patterns.md を参照
• 公式ガイド: references/best-practices-guide.md を参照

---

ソース

• Claude Code のベストプラクティス — 公式ドキュメント
• Claude Code スキル — スキル作成ガイド
• Anthropic プロンプトエンジニアリング — 一般的なプロンプティングパターン
• Dicklesworthstone meta_skill — 「THE EXACT PROMPT」パターン