Optimize AI Context
AIコーディング支援向けコンテキストファイルを、対象製品とプロジェクトの実態に合わせて改善する。
ゴール
エージェントが必要な指示を正しいスコープで読み取り、リポジトリに即した作業を安全かつ一貫して実行できる状態にする。 一般論を追加するのではなく、誤動作の原因となる不足・曖昧さ・矛盾・陳腐化を解消する。
スコープ
対象
- CLAUDE.md、AGENTS.md、AGENTS.override.md、.cursorrules、.cursor/rules/ 等
- プロジェクト固有のAI向け指示ファイル
対象外
- 通常のユーザープロンプトやコーディング依頼文の添削
- AI向け指示ファイルを伴わないCLI・モデル・権限設定の診断
- READMEや設計書そのものの一般的な校正
モードを選択する
依頼内容から次のモードを決定する。
- レビュー — 「レビュー」「問題点を教えて」等の依頼では、評価と改善案のみを提示し、ファイルを編集しない
- 最適化 — 「改善して」「最適化して」「書き換えて」等の依頼では、編集許可が含まれるものとして評価から適用・再検証まで実行する
- 新規作成 — 「作成して」「用意して」等の依頼では、プロジェクトを調査して適切な場所へ作成し、検証する
依頼が曖昧で編集の有無によって結果が大きく変わる場合のみ確認する。明示された編集依頼に対して重ねて承認を求めない。
Degrees of Freedom
- 評価基準の適用: Low freedom —
references/evaluation-criteria.mdを全文読み、該当項目を評価する。対象製品に適用できない項目は N/A とする - 改善内容の判断: High freedom — 対象製品の仕様、プロジェクト構成、既存規約に合わせて必要な改善だけを選ぶ
- ファイル編集: Low freedom — 編集直前に対象を読み、既存の有効な指示とユーザー変更を維持する
ワークフロー
1. 対象と適用範囲を特定する
- 指定されたファイルと対象製品を特定する
- パスが未指定なら、リポジトリ内の候補を探索して対象を推定する
- 複数候補があり、選択によって結果が大きく変わる場合のみユーザーへ確認する
- ルートから対象まで適用される上位・下位の指示ファイルも確認する
2. 事実を収集する
- 対象ファイルと
references/evaluation-criteria.mdを全文読む - リポジトリのマニフェスト、スクリプト、CI設定、主要ドキュメントからコマンドと規約を確認する
- 対象製品の探索・継承・構文が判断に影響し、仕様が不明または変わり得る場合は公式資料を確認する
- 推測で不足情報を補わず、確認できない内容を明示する
3. 評価する
- 評価基準の3カテゴリを ✅ Pass / ⚠️ Warn / ❌ Fail / N/A で判定する
- 問題を影響度順に並べ、根拠となるファイルまたは仕様を示す
- 既存の良い指示と、削除・追加・移動すべき内容を区別する
4. モードに応じて実行する
- レビュー: 評価レポートと具体的な改善案を返して終了する
- 最適化: 依頼範囲の問題を最小差分で修正する
- 新規作成: 対象製品の探索規則とプロジェクト構成に合う場所へ必要最小限のファイルを作成する
5. 再検証する
- 変更後のファイルを読み直す
- 記載したパス、コマンド、規約をリポジトリの事実と照合する
- 同じ評価基準で再採点し、Failが解消されたことを確認する
- 差分を確認し、依頼範囲外の変更や重複がないことを確認する
- descriptionまたは責務境界を変更した場合は、
evals/evals.jsonの正例・負例との整合性を確認する
出力形式
レビュー
- 対象、モード、総合判定
- カテゴリ別の ✅ / ⚠️ / ❌ / N/A
- 問題、根拠、具体的な改善案
- 未確認事項と残存リスク
編集後
- 変更したファイル
- 変更内容と理由
- 再検証結果
- 実行していない検証とその理由
エラーハンドリング
- 対象が見つからない: 探索した場所を示し、新規作成するか確認する
- 対象が空: 新規作成モードとして扱えるか確認する
- 公式仕様を確認できない: ローカルで確認できた事実だけで続行し、未確認部分を報告する
- 既存指示が競合する: 適用範囲と優先順位を示し、意図を判断できない場合のみ確認する