prompt-improver

プロンプト改善ツール

概要

一般的な LLM／エージェントのベストプラクティスに基づいて、プロンプトを分析・改善するスキルです。検証可能性、明確なスコープ、明示的な制約、コンテキストの効率的な活用に重点を置き、エージェントが何度も確認を求めずに実行できるようにします。

Claude Code を使用している場合は、references/claude.md も読み、Claude 固有の追加テクニックを適用してください。 Codex CLI を使用している場合は、references/codex.md も読み、Codex 固有の追加テクニックを適用してください。

入力がエージェントに指示するドキュメント（例：計画ファイル、AGENTS.md、システム指示ドキュメント）の場合、そのドキュメントを改善対象として扱ってください。問題を特定し、具体的な改善案を提示し、必要に応じて改訂版のドラフトを含めてください。

ワークフロー

ステップ 0：タスクと複雑さを分類する

タスクを分類し、明示的な調査／計画フェーズを推奨すべきか判断してください。

• タスクの種類：バグ修正、機能追加、リファクタリング、調査、UI／ビジュアル、ドキュメント、運用
• 複雑さ：単一ファイル／小規模な変更か、複数ファイル／影響が不確かな変更か
• リスク：データの安全性、セキュリティ、互換性、パフォーマンス
• 入力の種類：プロンプトか、エージェント指示ドキュメント（計画ファイル、AGENTS.md、システム指示ドキュメント）か

タスクが複雑または曖昧な場合は、改善したプロンプトで、実装の前に調査／計画フェーズを明示的に依頼してください。

ステップ 1：プロンプトを分析する

ユーザーが提供したプロンプトを、次の観点から分析してください。

1. 検証可能性：Claude が自分の作業を検証する方法を含んでいますか？
2. 具体性：ファイル、シナリオ、制約が明確に指定されていますか？
3. コンテキスト：必要な背景情報が提供されていますか？
4. スコープ：タスクの範囲は適切に定義されていますか？
5. 期待する成果：成功基準は明確ですか？
6. 制約：言語／ランタイムのバージョン、依存関係、セキュリティ、互換性の要件が指定されていますか？
7. コンテキストの効率性：不要な情報がなく、簡潔で焦点が絞られていますか？
8. 実行方針：モデルが実装するのか、提案するのか、分析のみを行うのか明確ですか？

ステップ 2：問題を特定する

次のアンチパターンがないか確認してください。

アンチパターン	説明
曖昧な指示	「もっと良くする」「改善する」など、具体性に欠ける指示
検証方法がない	テスト、スクリーンショット、期待される出力がない
検証コマンドがない	テストの実行方法や出力の確認方法がない
範囲が広すぎる	一度に多くのことを求めている
コンテキスト不足	ファイルパス、エラーメッセージ、既存パターンへの参照がない
症状のみの説明	根本原因の調査を求めていない
制約の欠落	環境、依存関係、互換性に関する要件がない
調査／計画の指示がない	複雑なタスクなのに、先に調査／計画するよう求めていない
コンテキストの過剰な膨張	トークン使用量を増やす不要な詳細
成果物が曖昧	計画、実装、分析のみのどれを行うのか不明
回答形式が不明確	簡潔さや構成に関する要件がない

ステップ 3：改善したプロンプトを作成する

ベストプラクティスを適用し、改善版を作成してください。

検証可能性を加える

Before: "implement a function that validates email addresses"
After: "write a validateEmail function. test cases: [email protected] is true, invalid is false, [email protected] is false. run the tests after implementing"

具体的なコンテキストを加える

Before: "fix the login bug"
After: "users report that 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"

既存パターンへの参照を加える

Before: "add a calendar widget"
After: "look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget with month selection and pagination"

コンテキストを効率化する

Before: "here is a long unrelated history ... fix the dropdown"
After: "fix the dropdown in src/ui/Dropdown.tsx. issue: keyboard navigation skips items. keep the prompt focused; omit unrelated history"

豊富なコンテキスト入力を加える

Before: "build fails"
After: "build fails with this error: [paste error]. run the smallest relevant test command. if needed, read the build script and package config"

必要に応じて、明示的な調査／計画を加える

Before: "refactor auth to support OAuth"
After: "first explore src/auth and summarize current flow, then propose a plan. after approval, implement with tests"

情報が不足している場合は、改善版のプロンプトに明確な質問を含め、デフォルトを仮定しないでください。

例：バグ修正

Before: "search is broken"
After: "users report search returns empty results for queries with hyphens. reproduce in src/search/. paste the error log if any. write a failing test for 'foo-bar' returning results, fix the root cause, run: pnpm test --filter search"

例：UI／ビジュアル

Before: "make the dashboard look better"
After: "implement the attached screenshot for the dashboard header in src/ui/DashboardHeader.tsx. match spacing and typography. take a new screenshot and list any differences. run: pnpm lint"

例：リファクタリング

Before: "clean up the auth code"
After: "inspect src/auth and list duplication hotspots. propose a refactor plan scoped to one module. after approval, remove duplication without changing behavior. add a targeted test if coverage is missing. run the smallest relevant test command"

例：調査

Before: "why is this API slow?"
After: "explore request flow around src/api/. summarize likely bottlenecks with evidence (logs, timings). propose 2-3 hypotheses and what data is needed to confirm. do not implement yet. if needed, ask for access to profiling output"

例：運用

Before: "deployment failed"
After: "deploy fails with error: [paste log]. identify the failing step in scripts/deploy.sh and related CI config. suggest a fix and a rollback plan. run: ./scripts/deploy.sh --dry-run (if available)"

例：ドキュメント

Before: "update the README"
After: "update README.md to include install + dev steps based on existing scripts. keep it concise. confirm commands exist and match actual scripts"

ステップ 4：出力形式

次の形式で出力してください。

## Prompt Analysis

### Original Prompt
[User-provided prompt]

### Issues
- [Issue 1 and its impact]
- [Issue 2 and its impact]
...

### Missing Information (Questions to Ask)
The following questions should be answered to make the prompt more effective:
- [Question 1] (Why it is needed)
- [Question 2] (Why it is needed)
...

### Verification Plan
- Commands to run (tests, build, lint, screenshots)
- Expected results or acceptance criteria

### Exploration/Planning Recommendation
- Recommend exploration/planning first? [Yes/No] and why

### Execution Preference
- Implement now / propose plan only / analyze only
- Any constraints on response length or format

### Improved Prompt
[The improved prompt]

### Document Improvement Suggestions (if applicable)
- [Issue and concrete improvement for the instruction document]
- [Issue and concrete improvement for the instruction document]

### Revised Document (optional)
[A revised draft of the instruction document when helpful]

### Improved Prompt Template (optional)
Use this as a fill-in template if the user wants a reusable prompt format:

[タスク]

• 目標：
• 対象ファイル／パス（@...）：
• 制約（ランタイム／バージョン／依存関係／セキュリティ／互換性）：
• コンテキスト（症状、ログ、再現手順、リンク）：

[検証]

• コマンド：
• 期待される結果：
• UI チェック（スクリーンショット／視覚的な差分）：

[調査／計画]

• 先に調査／計画を行いますか？（はい／いいえ）＋理由：

[実行方針]

• 今すぐ実装／計画のみ／分析のみ
• 出力形式（簡潔な報告、パッチの概要、チェックリストなど）

### Short Prompt Template (optional)
Use this when the user wants the shortest effective prompt:

目標：... 対象：path1/path2 コンテキスト：症状＋再現手順＋ログ 制約：ランタイム／依存関係／互換性 検証：コマンド＋期待される結果 調査／計画：はい／いいえ（理由） 実行：実装／計画のみ／分析のみ 出力：簡潔な形式

### Improvement Points
1. [Explanation of improvement 1]
2. [Explanation of improvement 2]
...

### Additional Recommendations (optional)
- [Whether to do exploration/planning first]
- [Whether to parallelize or delegate investigation]
- [Whether preliminary research is needed]
- [Ways to reduce context usage]

参考：ベストプラクティスのチェックリスト

プロンプトを改善する際に参考にするベストプラクティス：

検証方法を提示する

• テストケースを含める
• 期待される出力を指定する
• UI の変更では、スクリーンショットの比較を依頼する
• 「テストを実行する」または「ビルドが成功することを確認する」と記載する
• 実行するコマンドを明記する

調査 → 計画 → 実装の順に進める

• 複雑なタスクでは、まず調査／計画の段階を設ける
• 実装前に計画を作成する
• 小規模な修正には正式な計画は不要
• 不明点がある場合は、コーディングの前に確認を求める

具体的なコンテキストを含める

• エラーメッセージを貼り付ける
• 既存のパターンを指定する
• エッジケースを明確にする
• 環境の制約（ランタイム、言語のバージョン、依存関係）を伝える

豊富な入力を活用する

• ログやスタックトレースを貼り付ける
• ドキュメントや API リファレンスの URL を提示する
• 必要に応じて、大量のテキスト出力を添付または貼り付ける

コンテキストウィンドウを管理する

• プロンプトを簡潔で焦点の定まったものにする
• 無関係な履歴や推測を削除する
• 推測するのではなく、不足している情報を尋ねる

並列処理／委任を活用する

• 調査タスクでは、並行して調査するか、要約を依頼する
• コードレビューでは、独立したレビューも依頼する
• メインのタスクに集中しやすくなる

避けるべきパターン

• 「もっと良くして」「改善して」のような曖昧な指示
• 検証方法を指定しない実装依頼
• 関連のない複数のタスクを一度に依頼すること
• まだ読んでいないファイルの変更を依頼すること
• 明確な目的のない大量のコンテキストの貼り付け