プロンプトファイル構造統一による保守性向上

AI でコンテンツの品質を管理するシステムでは、評価基準（何をどう採点するか）と評価ロジック（どう動作するか）を分離するのがベストプラクティスです。この分離が不十分だと、プロンプトの差し替えや保守で混乱が生じます。この記事では、ブログ評価とLP評価という2つの AI 評価システムで構造不一致が発生した事例をもとに、一貫した役割分離を実現する具体的な手順を解説します。このパターンは AI を使ったコンテンツ生成・評価システム全般に適用できます。

問題の特定：構造の不一致

発生していた構造差

LP側（正しい役割分離）:

prompts/
├── lp_scoring_criteria.md      # 採点基準のみ
└── lp_evaluator_prompt.md      # Evaluator指示（criteria参照）

ブログ側（統一前）:

prompts/
└── blog_scoring_criteria.md    # 採点基準 + Evaluator指示が同居

保守性への影響

この構造差により以下の問題が発生していました：

差し替えコスト増: Evaluatorプロンプトを変更したい場合、ファイル構成の理解が必要
一貫性の欠如: 同じ役割なのに異なるファイル構造
認知負荷: 開発者が「どこに何が書いてあるか」を都度確認する必要

解決策の設計

目標とする構造

LP側の設計を正として、ブログ側も以下に統一：

prompts/
├── blog_scoring_criteria.md    # 採点基準のみ
└── blog_evaluator_prompt.md    # Evaluator指示（criteria参照）

役割分離の原則

scoring_criteria.md: 評価項目・配点・採点ルールの定義（記事がどの基準で何点になるかを決めるデータ）
evaluator_prompt.md: AI評価エージェントへの具体的な指示・動作仕様（基準に基づいて記事を実際に採点するプロセスの定義）

実装手順

1. 現状ファイルの分析

blog_scoring_criteria.md から Evaluator 指示セクションを特定：

## Evaluator 指示

あなたは analytics-note.jp のブログ記事を評価するエージェントです。
上記の採点基準に従って、以下の形式で評価してください：

### 評価手順
1. 記事全体を通読
2. 各項目を個別に採点
3. 総合コメントを生成
...

2. 新ファイルの作成

apps/site/prompts/blog_evaluator_prompt.md を新規作成：

# Blog Evaluator Prompt

あなたは analytics-note.jp のブログ記事を評価する専門エージェントです。

## 評価基準

詳細な採点基準は `blog_scoring_criteria.md` を参照してください。

## 評価手順

1. **記事の通読**: 全体構成と内容を把握
2. **項目別採点**: 各基準に従って0-5点で評価
3. **総合判定**: 80点以上を合格ライン
4. **改善提案**: 低評価項目の具体的な改善案を提示

## 出力形式

\```json
{
  "overall_score": 85,
  "detailed_scores": {
    "reader_value": 4,
    "reproducibility": 5,
    "practical_application": 4,
    ...
  },
  "feedback": "具体的な改善提案",
  "recommendation": "APPROVE|REVISE|REJECT"
}
\```

## 注意事項

- 客観的な評価を心がける
- 改善提案は具体的で実行可能な内容にする
- コンセプト「実践ログ」からのズレを重点的にチェック

3. 元ファイルの修正

blog_scoring_criteria.md からEvaluator指示セクションを削除し、参照リンクに置換：

## Evaluator 運用

詳細なEvaluator指示は `blog_evaluator_prompt.md` を参照してください。

本ファイルは採点基準の定義に特化し、運用手順は分離しています。

4. 参照整合性の確認

両ファイル間での参照関係が正しく機能することを確認：

# blog_evaluator_prompt.md から criteria への参照確認
grep -n "blog_scoring_criteria.md" prompts/blog_evaluator_prompt.md

# 相互参照の整合性チェック
prompts/
├── blog_scoring_criteria.md    ← blog_evaluator_prompt.md が参照
└── blog_evaluator_prompt.md    ← blog_scoring_criteria.md が参照

検証プロセス

構造統一の確認

変更後の構造が LP 側と一致していることを確認：

# LP側構造
ls prompts/lp_*
# prompts/lp_scoring_criteria.md
# prompts/lp_evaluator_prompt.md

# ブログ側構造（統一後）
ls prompts/blog_*
# prompts/blog_scoring_criteria.md
# prompts/blog_evaluator_prompt.md

ファイル内容の整合性

重複排除: Evaluator指示が両ファイルに重複して残っていない
参照完全性: 相互参照が正しく機能する
役割明確性: 各ファイルの責務が明確に分離されている

運用メリット

1. 差し替え容易性

# Evaluatorロジックのみ変更したい場合
cp new_evaluator_prompt.md prompts/blog_evaluator_prompt.md
# ← scoring_criteria.md はそのまま

# 採点基準のみ変更したい場合  
cp new_scoring_criteria.md prompts/blog_scoring_criteria.md
# ← evaluator_prompt.md はそのまま

2. 認知負荷軽減

開発者が迷わない明確な役割分離：

採点ルールを確認したい → *_scoring_criteria.md
Evaluatorの動作を確認したい → *_evaluator_prompt.md

3. LP側との一貫性

同じパターンで運用されるため、LP評価の経験がそのまま活用可能。

技術的実装のポイント

ファイル分離のベストプラクティス

## Good: 明確な役割分離
scoring_criteria.md   # データ定義
evaluator_prompt.md   # プロセス定義

## Avoid: 役割の混在  
combined_prompt.md    # データ + プロセスが同居

参照設計のパターン

# 参照元ファイル（evaluator_prompt.md）
詳細な採点基準は `scoring_criteria.md` を参照

# 参照先ファイル（scoring_criteria.md）  
運用手順は `evaluator_prompt.md` を参照

結果と今後の展開

達成した状態

✅ LP側とブログ側のファイル構造統一
✅ 役割分離による保守性向上
✅ 将来の差し替えコスト削減

継続改善項目

テンプレート化: 新しい評価系追加時の標準パターン策定
自動チェック: 構造整合性を CI でチェックする仕組み
ドキュメント化: プロンプト設計ガイドラインの整備

この構造統一により、複数の評価システムを運用する際の保守性と一貫性が大幅に向上しました。

ブログ記事生成フローのコンセプト統合 — 評価基準に読者価値軸を統合したハーネス強化の実践
GitHub Issue を閉じるだけでブログ記事が自動生成される仕組みを作った — 記事生成パイプラインの全体アーキテクチャ
generate-blog を PR作成止まりから公開完了まで自動化した実装ログ — 記事生成から公開までの自動化フロー

プロンプトファイル構造統一による保守性向上：evaluator prompt の独立化実践