enhance-prompts

enhance-prompts

明確さ、構成、例、出力の信頼性についてプロンプトを分析します。

引数の解析

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

enhance-agent-prompts との違い

スキル	焦点	使用する場面
enhance-prompts	プロンプトの品質（明確さ、構成、例）	一般的なプロンプト、システムプロンプト、テンプレート
enhance-agent-prompts	エージェント設定（フロントマター、ツール、モデル）	YAML フロントマターを含むエージェントファイル

ワークフロー

1. アナライザーの実行 - JavaScript アナライザーを実行して検出結果を取得します：

   node -e "const a = require('./lib/enhance/prompt-analyzer.js'); console.log(JSON.stringify(a.analyzeAllPrompts('.'), null, 2));"
   

   特定のパスの場合：a.analyzeAllPrompts('./plugins/enhance') 単一ファイルの場合：a.analyzePrompt('./path/to/file.md')

2. 結果の解析 - アナライザーは summary と findings を含む JSON を返します

3. フィルタリング - --verbose フラグに基づいて確度をフィルタリングします

4. 報告 - 検出結果を Markdown 形式で出力します

5. 修正 - --fix フラグが指定されている場合、検出結果に基づいて自動修正を適用します

JavaScript アナライザー（lib/enhance/prompt-analyzer.js）は、AST ベースのコード検証を含むすべての検出パターンを実装しています。以下のパターンは参考ドキュメントです。

---

プロンプトエンジニアリングの知識リファレンス

システムプロンプトの構成

効果的なシステムプロンプトには、役割／アイデンティティ、機能と制約、指示の優先順位、出力形式、動作指針、例、エラー処理が含まれます。

最小限のテンプレート：

<system>
You are [ROLE]. [PURPOSE].
Key constraints: [CONSTRAINTS]
Output format: [FORMAT]
When uncertain: [HANDLING]
</system>

XML タグ（Claude 固有）

Claude は XML タグ向けにファインチューニングされています。次を使用します：<role>、<constraints>、<output_format>、<examples>、<instructions>、<context>

<constraints>
- Maximum response length: 500 words
- Use only Python 3.10+ syntax
</constraints>

少数ショットの例

• 2～5 個の例が最適です（研究に裏付けられています）
• エッジケースを含め、形式の一貫性を確保します
• まずはゼロショットで始め、必要な場合にのみ例を追加します
• 該当する場合は、良い例と悪い例の両方を示します

思考の連鎖（CoT）

CoT を使う場合	CoT を使わない場合
複雑な複数ステップの推論	簡単な事実に関する質問
数学や論理の問題	分類タスク
コードのデバッグ	モデルに組み込みの推論機能がある場合

ポイント： 最新のモデル（Claude 4.x、o1/o3）は内部で CoT を実行します。「ステップごとに考えてください」という指示は冗長です。

役割のプロンプト指定

効果があるもの： 創作タスク、トーン／スタイル、ロールプレイ 効果がないもの： 正確性が求められるタスク、事実の検索、複雑な推論

より良い例：「専門家です」より「作業内容を示しながら、体系的に取り組んでください」

指示の階層

優先順位：システム > 開発者 > ユーザー > 取得したコンテンツ

複数の制約ソースがあるプロンプトには、明示的な優先順位を含めます。

否定形のプロンプト

否定表現より、肯定的な代替案のほうが効果的です。

効果が低い	効果が高い
「Markdown を使わないでください」	「散文の段落を使ってください」
「曖昧にしないでください」	「具体的な表現を使ってください」

構造化出力

• プロンプトベース：約 35.9% の信頼性
• スキーマによる強制：100% の信頼性
• 常にスキーマの例を提示し、出力を検証します

コンテキストウィンドウの最適化

中間部の埋没： モデルは冒頭と末尾をより重視します。

重要な制約は冒頭に、例は中間に、エラー処理は末尾に配置します。

拡張思考

「深く考えてください」のような高レベルの指示は、段階的な指示よりも効果的です。「ステップごとに考えてください」は、最新のモデルでは冗長です。

アンチパターンのクイックリファレンス

アンチパターン	問題	修正方法
曖昧な参照	「上記のコード」ではコンテキストが失われる	具体的に引用する
否定のみ	代替案なしに「X をしない」と指示する	代わりに何をすべきかを伝える
過剰な強調	「重要：必ず」	通常の表現を使う
冗長な CoT	トークンを無駄にする	モデルに任せる
重要情報の埋没	中間部で見落とされる	冒頭または末尾に配置する

---

検出パターン

1. 明確さの問題（確度：高）

曖昧な指示： 「通常は」「場合によっては」「試してみて」「可能なら」「かもしれない」「できるかもしれない」

否定のみの制約： 何をすべきかを示さずに「しない」「決して～しない」「避ける」

過剰な強調： 過剰な大文字（CRITICAL、IMPORTANT）、複数の !!

2. 構造上の問題（確信度：高／中）

XML 構造の欠如： XML タグを使わず、複雑なプロンプト（800 トークン超）

セクションの不統一： 見出しのスタイルが混在している、レベルが飛んでいる（H1→H3）

重要情報が埋もれている： 重要な指示が中盤の 40％にある、制約が例の後にある

3. 例に関する問題（確信度：高／中）

例の欠如： few-shot のない複雑なタスク、例のない形式指定

数が最適でない： 例が 1 つだけ（最適数：2～5 個）、7 個を超える（過剰）

対比の欠如： 良い／悪いのラベル付けがない、エッジケースがない

4. コンテキストに関する問題（確信度：中）

理由の欠如： 説明のないルール

優先順位の欠如： 複数の制約セクションがあるが、競合時の解決方法がない

5. 出力形式に関する問題（確信度：高／中）

形式の欠如： 形式指定のない、実質的なプロンプト

スキーマのない JSON： JSON を要求しているが、構造の例がない

6. アンチパターン（確信度：高／中／低）

冗長な CoT（高）： 最新のモデルに対する「段階的に考えてください」

過度な規定（中）： 10 個以上の番号付きステップで、推論を細かく管理する

プロンプトの肥大化（低）： 2500 トークン超、指示の重複

曖昧な参照（高）： 「上記のコード」、「前述のとおり」

---

自動修正の実装

1. 強調の緩和

CRITICAL→critical、!!→! に置換し、過剰な大文字を削除

2. 否定のみの表現を肯定表現に変更

「するな」という指示に対して、肯定的な代替案を提案

---

出力形式

## Prompt Analysis: {prompt-name}

**File**: {path}
**Type**: {system|agent|skill|template}
**Token Count**: ~{tokens}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Clarity Issues ({n})
| Issue | Location | Fix | Certainty |

### Structure Issues ({n})
| Issue | Location | Fix | Certainty |

### Example Issues ({n})
| Issue | Location | Fix | Certainty |

---

パターン統計

カテゴリ	パターン数	自動修正可能
明瞭さ	4	1
構造	4	0
例	4	0
コンテキスト	2	0
出力形式	3	0
アンチパターン	4	0
合計	21	1

---

### 例：曖昧な指示

<bad_example>

You should usually follow best practices when possible.

悪い理由：曖昧な限定表現は決定性を低下させます。 </bad_example>

<good_example>

Follow these practices:
1. Validate input before processing
2. Handle null/undefined explicitly

良い理由：具体的で、実行可能な指示です。 </good_example>

例：否定のみの制約

<bad_example>

- Don't use vague language
- Never skip validation

悪い理由：してはいけないことだけを述べています。 </bad_example>

<good_example>

- Use specific, deterministic language
- Always validate input; return structured errors

良い理由：それぞれの制約に、肯定的な行動が含まれています。 </good_example>

例：冗長な Chain-of-Thought

<bad_example>

Think through this step by step:
1. First, analyze the input
2. Then, identify the key elements

悪い理由：最新のモデルは内部でこれを行います。トークンの無駄です。 </bad_example>

<good_example>

Analyze the input carefully before responding.

良い理由：細かく管理することなく、大まかな指針を示しています。 </good_example>

例：出力形式の欠如

<bad_example>

Respond with a JSON object containing the analysis results.

悪い理由：スキーマも例もありません。 </bad_example>

<good_example>

## Output Format
{"status": "success|error", "findings": [{"severity": "HIGH"}]}

良い理由：具体的なスキーマで、正確な構造を示しています。 </good_example>

例：重要情報が埋もれている

<bad_example>

# Task
[task]
## Background
[500 words...]
## Important Constraints  <- buried at end

悪い理由：中間情報の見落とし効果が生じます。 </bad_example>

<good_example>

# Task
## Critical Constraints  <- at start
[constraints]
## Background

良い理由：注意が最も向けられる冒頭に、重要情報があります。 </good_example>

---

制約

• 確信度が高い問題に対してのみ自動修正を適用してください
• 元の構造と書式を維持してください
• 上記に埋め込まれたナレッジリファレンスに照らして検証してください