best-practices

ベストプラクティス — プロンプトトランスフォーマー

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

まずはこちら

ユーザーのリクエストに基づいて対応します。

ユーザーが変換するプロンプトを提示した場合： → AskUserQuestion を使って質問します。

• 質問： "このプロンプトをどのように改善しますか？"
• ヘッダー： "モード"
• 選択肢：
  1. そのまま変換する — "ベストプラクティスを適用し、改善版を出力します"
  2. まずコンテキストを集める — "まずコードベースのコンテキストと意図の分析を行います"

ユーザーが学習や理解を求めている場合： →「5 つの変換原則」セクションを表示します。

ユーザーが例を求めている場合： → references/before-after-examples.md へのリンクを表示します。

ユーザーがプロンプトの評価を求めている場合： → このドキュメント末尾の成功基準評価ルーブリックを使います。

---

「そのまま変換する」の場合

以下の 5 つの原則を適用し、改善したプロンプトをすぐに出力します。

「まずコンテキストを集める」の場合

コンテキストを集めるため、3 つのエージェントを並行して起動します。

Run these agents IN PARALLEL using the Task tool:

- Task task-intent-analyzer("[user's prompt]")
- Task best-practices-referencer("[user's prompt]")
- Task codebase-context-builder("[user's prompt]")

各エージェントから返される内容

エージェント	ミッション	返される内容
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 の変更	「スクリーンショットを撮り、デザインと比較する」
バグ修正	「失敗するテストを書いてから修正する」
ビルドの問題	「修正後にビルドが成功することを検証する」
リファクタリング	「変更のたびにテストスイートを実行する」
根本原因への対処が求められていない	「エラーを抑制せず、根本原因に対処する」
検証レポートがない	「実行した内容と成功した項目を要約する」

BEFORE: "implement email validation"
AFTER:  "write a validateEmail function. test cases: [email protected] → true,
         invalid → false, [email protected] → false. run the tests after implementing"

BEFORE: "fix the API error"
AFTER:  "the /api/orders endpoint returns 500 for large orders. check
         OrderService.ts for the error. address the root cause, don't suppress
         the error. after fixing, run the test suite and summarize what passed
         and what you verified."

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 がある場合、変換後のプロンプトでは次の点に従う必要があります。

• プロジェクトの規約に反しない
• 関連する場合はプロジェクト固有のパターンを参照する
• 該当するプロジェクトの制約に留意する

BEFORE: "add a new API endpoint"
AFTER:  "add a GET /api/products endpoint. check CLAUDE.md for API conventions
         in this project. follow the pattern in routes/users.ts. run the API
         tests after implementing."

BEFORE: "fix the login bug"
AFTER:  "users report login fails after session timeout. check the auth flow
         in src/auth/, especially token refresh. write a failing test that
         reproduces the issue, then fix it"

3. 制約を追加する

Claude にしてほしくないことを伝えます。過剰な設計や望ましくない変更を防ぎます。

制約の種類	例
依存関係	「新しいライブラリは追加しない」、「既存の依存関係のみを使う」
テスト	「モックは使わない」、「テストでは実際のデータベースを使う」
範囲	「関係のないコードはリファクタリングしない」、「認証モジュールだけを変更する」
アプローチ	「エラーを抑制せず、根本原因に対処する」、「後方互換性を維持する」
パターン	「既存のコードベースの規約に従う」、「utils.ts のスタイルに合わせる」

BEFORE: "add a calendar widget"
AFTER:  "implement a calendar widget with month selection and year pagination.
         follow the pattern in HotDogWidget.php. build from scratch without
         libraries other than the ones already used in the codebase"

4. 複雑なタスクをフェーズに分ける

規模の大きなタスクでは、調査と実装を分けます。

4 フェーズのパターン：

Phase 1: EXPLORE
"read src/auth/ and understand how we handle sessions and login.
 also look at how we manage environment variables for secrets."

Phase 2: PLAN
"I want to add Google OAuth. What files need to change?
 What's the session flow? Create a plan."

Phase 3: IMPLEMENT
"implement the OAuth flow from your plan. write tests for the
 callback handler, run the test suite and fix any failures."

Phase 4: COMMIT
"commit with a descriptive message and open a PR"

フェーズを使う場合：

• アプローチが不確かな場合
• 変更によって複数のファイルが対象になる場合
• 変更対象のコードに詳しくない場合

フェーズを省略する場合：

• 差分を一文で説明できる場合
• 誤字の修正、ログ行の追加、変数名の変更の場合

BEFORE: "add OAuth"
AFTER:  "read src/auth/ and understand current session handling. create a plan
         for adding OAuth. then implement following the plan. write tests and
         verify they pass"

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

Claude が直接利用できる参考資料を提供します。

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

BEFORE: "make the dashboard look better"
AFTER:  "[paste screenshot] implement this design for the dashboard.
         take a screenshot of the result and compare it to the original.
         list any differences and fix them. ensure responsive behavior
         at 768px and 1024px breakpoints"

BEFORE: "the build is failing"
AFTER:  "the build fails with this error: [paste actual error]. fix it
         and verify the build succeeds. address the root cause, don't
         suppress the error"

---

出力形式

プロンプトを変換する際は、次の形式で出力します。

**Original:** [their prompt]

**Improved:**

[変換後のプロンプトをコードブロックで記載]

**Added:**
- [what was missing and added]
- [another improvement]
- [etc.]

---

変換の簡単な例

バグ修正

BEFORE: "fix the login bug"

AFTER: "users report login fails after session timeout. check the auth flow
in src/auth/, especially token refresh. write a failing test that reproduces
the issue, then fix it. verify by running the auth test suite."

ADDED: symptom, location, verification (failing test), success criteria

機能の実装

BEFORE: "add a search feature"

AFTER: "implement search for the products page. look at how filtering works
in ProductList.tsx for the pattern. search should filter by name and category.
add tests for: empty query returns all, partial match works, no results shows
message. no external search libraries."

ADDED: location, reference pattern, specific behavior, test cases, constraint

リファクタリング

BEFORE: "make the code better"

AFTER: "refactor utils.js to use ES2024 features while maintaining the same
behavior. specifically: convert callbacks to async/await, use optional
chaining, add proper TypeScript types. run the existing test suite after
each change to ensure nothing breaks."

ADDED: specific changes, constraint (same behavior), verification after each step

テスト

BEFORE: "add tests for foo.py"

AFTER: "write tests for foo.py covering the edge case where the user is
logged out. avoid mocks. use the existing test patterns in tests/. test
cases: logged_out_user returns 401, expired_session redirects to login,
invalid_token raises AuthError."

ADDED: specific edge case, constraint (no mocks), pattern reference, test cases

デバッグ

BEFORE: "the API is slow"

AFTER: "the /api/orders endpoint takes 3+ seconds. profile the database
queries in OrderService.ts. look for N+1 queries or missing indexes.
fix the performance issue and verify response time is under 500ms."

ADDED: specific endpoint, location, what to look for, measurable success criteria

UI の変更

BEFORE: "fix the button styling"

AFTER: "[paste screenshot of design] update the primary button to match this
design. check Button.tsx and the theme in tailwind.config.js. take a
screenshot after changes and compare to the design. list any differences."

ADDED: design reference, file locations, visual verification

調査

BEFORE: "how does auth work?"

AFTER: "read src/auth/ and explain how authentication works in this codebase.
cover: how sessions are created, how tokens are refreshed, where secrets
are stored. summarize in a markdown doc."

ADDED: specific files, specific questions to answer, output format

移行

BEFORE: "upgrade to React 18"

AFTER: "migrate from React 17 to React 18. first, read the migration guide
at [URL]. then identify all components using deprecated APIs. update one
component at a time, running tests after each. don't change unrelated code."

ADDED: phased approach, reference docs, incremental verification, scope constraint

検証レポート付き

BEFORE: "fix the API error"

AFTER: "the /api/orders endpoint returns 500 for large orders. check
OrderService.ts for the error. address the root cause, don't suppress
the error. after fixing, run the test suite and summarize what passed
and what you verified."

ADDED: symptom, location, root cause enforcement, verification report

---

変換チェックリスト

出力する前に、改善されたプロンプトに次の項目が含まれていることを確認します。

• 検証 — 成功したと判断する方法（テスト、スクリーンショット、出力）
• 場所 — 具体的なファイル、関数、領域
• 制約 — してはいけないこと
• 単一のタスク — 複合タスクではないこと（必要であれば分割する）
• フェーズ — 複雑な場合は、調査 → 計画 → 実装の順に構成する
• 根本原因 — バグの場合：「問題を抑制せず、根本原因に対処する」
• 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つまたは0

目標： 変換後のすべてのプロンプトが、⭐⭐⭐⭐または⭐⭐⭐⭐⭐の評価を得ること。

---

参考ファイル

その他の例やパターンについては、以下を参照してください。

• 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 Skills — スキル作成ガイド
• Anthropicのプロンプトエンジニアリング — 一般的なプロンプトのパターン
• Dicklesworthstone meta_skill — 「THE EXACT PROMPT」パターン