efoo-team エージェント・プロンプト設計原則
AIエージェントに与える文面 — サービスの agent instructions、システムプロンプト、サブエージェントへの委譲文、Agent Skills の本文、指示ファイル（CLAUDE.md / AGENTS.md）の条項 — を書く・直す・レビューするときの、ランタイム非依存の執筆原則である。
エージェントの成果はモデルと文面の積で決まる。本スキルは「モデルの知性を信頼して最大限引き出す記述」と「工程とメンタルモデルの明示的な運転」の2本柱で文面の品質を上げる。
0. 適用範囲と判断軸
判断軸: モデル進化の享受。 記述・機構の選択に迷ったら「モデルの世代が進んだとき、これは勝手に良くなるか、今日のモデルの限界をシステムに固定するか」を問い、勝手に良くなる側を選ぶこと。既習概念の指名（§2）は前者の典型であり、弱点補正のための機構・制限・過剰な手順指定は後者になりやすい。これはコア公理4（最小構成から始める）・公理5（コンテキストは有限資源。ただし削減は品質確認の後）・公理9（モデルが賢くなるたびに剪定する）の執筆場面への適用である（公理の正本は agent-harness-engineering / agent-native-project-design。本スキルへは複製しない）。
隣接スキルとの分担:
| 主題 | 参照先 |
|---|---|
| SKILL.md の機械規約（description 予算・3階層・発火設計・スクリプト同梱） | agent-native-project-design（references/skill-authoring.md が正本） |
| コンテキスト機構（compaction・JIT 取得・キャッシュ・サブエージェント隔離） | agent-harness-engineering |
| Mastra 上の責務分離（agent / workflow / tool / state） | mastra-ai-architecture-rules |
| UI 設計におけるレンズの実体 | ui-ux-design |
eval・検証基盤などの機構を導入するかどうかは本スキルの範囲外であり、プロジェクト側で判断する。本スキルが与えるのは文面の原則だけである。
1. 記述高度と簡潔さ
- 適切な高度（right altitude）で書くこと。 脆い if-else の台本（全分岐の手順指定）でも、曖昧な標語（「良い感じに」「適切に」）でもなく、判断のヒューリスティクスと成功条件を示す。minimal は short と同義ではない — 期待挙動を完全に規定する最小の情報集合を目指す。
- 文脈を持たない同僚テストを通すこと。 その文面だけを渡された同僚が意図どおり動けるかを想像する。同僚が迷うならモデルも迷う。
- 簡潔化の第一手は短縮ではなく、矛盾と重複の除去であること。 矛盾・曖昧を含む指示は、モデルが賢いほど調停に推論を浪費して有害になる。改訂時はまず矛盾を検出し、全面書き直しではなく外科的に直す。
- 指示の総数自体が予算であること。 個々に明確な指示でも、数が増えるだけで全体の遵守率が下がる。1指示ごとに「消すと実際にミスが起きるか」を問い、No なら削る（指示ファイルの刈り込み手順は agent-native-project-design §1）。
- 肯定形を既定とすること。 「〜するな」だけの禁止は、出力の形を正す用途では逆効果になりうる。正しい形をテンプレート・具体的代替で示す。禁止形は圧力下のルール違反を防ぐ場面に限り、理由（なぜ重要か）とセットで使う（形式の使い分けの詳細は agent-native-project-design references/authoring-insights.md §4）。
- 長い文面では、重要指示を冒頭と末尾の両方に置くこと。 中間に置かれた情報の想起は構造的に弱い（lost in the middle）。
2. 既習概念の指名
モデルが学習済みの概念・理論・フレームワークは、再解説せずに正式名称で指名すること。 名前はモデル内部の知識体系を丸ごと呼び出すため、長い説明より少ないトークンで、意図をより正確に伝える。文面に書くのはモデルが知らない差分 — チーム固有の値・境界条件・例外 — だけでよい。モデルの世代が進むほど名前から引き出せる知識は深まり、文面を変えずに品質が上がる（§0 の判断軸）。
成立条件は3つ。満たさない場合は名前に頼らず展開して書くこと:
- 正名を使うこと。 俗称・誤名は別の（または存在しない）知識を呼び出す。名称の確度に不安がある概念は、正式名を確認するか展開記述に切り替える。
- チームの意図が正準的な定義と一致していること。 自チーム流の意味で使う語は、名前だけで済ませず定義を書く。モデルの学習済みデフォルトと戦う短い指示は、毎ターン摩擦を生む。
- 十分に有名な概念に限ること。 ニッチな理論・社内用語は圧縮にならない。
適用実例は ui-ux-design である。同スキルは決定領域ごとにレンズ（Progressive Disclosure、OOUI、Fitts's Law 等）を正式名で指名し、理論は再解説せず、モデルが知らない境界条件だけを足す。この「レンズ＝学習済みの知識を呼び出す名前」方式を、UI に限らずあらゆる文面で使うこと。
3. 工程の分離と計画の可視化
- 非自明なタスクは、調査 → 情報の整理 → 計画 → 実装の工程を既定とすること。 工程ごとに必要な思考の性質が異なり、混ぜると互いを劣化させる（計画しながら実装すると、実装の慣性が計画を歪める）。一文で説明できる小変更には課さない — 工程分離は品質装置であり、儀式ではない。
- 計画は頭の中に置かず、可視の一級成果物にすること。 明示的に書き出させ、作業中も参照・更新させる。長いタスクでは計画を直近のコンテキストへ復唱させると目標ドリフトを防げる（recitation。機構側の詳細は agent-harness-engineering references/context-engineering.md）。
- 分けるのは工程であって、情報ではないこと。 要件・前提は最初に一括で渡す（要件の分割提示は精度を大きく下げる）。工程分離を「計画だけ別エージェントへ渡す」形で実装すると、コンテキスト分断により暗黙の決定が衝突する。分離は同一コンテキスト内の規律として行うか、状態を完全に共有した handoff で行う。
- モデルの内的思考にまで台本を強制しないこと。 工程分離はタスクの進め方の構造であり、推論の手順書ではない。「深く考えてから進める」程度の一般指示が、手書きの思考ステップ指定に勝る。ワークフローコードで思考を模倣しないこと（mastra-ai-architecture-rules §4.2 と同旨）。
- 検証だけは fresh context で分離すること。 実装した本人のコンテキストは自分の実装にバイアスされる。レビュー・採点は文脈を持たない別インスタンスへ、成果物と判定基準だけを渡して行わせる。
4. メンタルモデルの明示的スイッチ
作業単位・工程の開始時に、「今どの工程で、どのメンタルモデル（レンズ）で挑むか」を明示的に指名してから着手すること・させること。 工程の境界（§3）はメンタルモデルの切替点である。品質劣化の多くは能力の不足ではなく、前工程のメンタルモデルを引きずったまま次工程に入ることから起きる。
代表的な失敗が実装モデルの漏出である: データモデルの単位（テーブル構造）をそのまま管理画面の単位へ投影する設計案は、実装のメンタルモデルのまま UI 設計の工程に入った結果であり、Cooper の3モデル論（実装モデル / ユーザーのメンタルモデル / 表現モデル。表現モデルはメンタルモデルに近づける）で棄却される。この種の失敗は「設計案が出てから直す」のではなく「工程に入る前のモデル指名」で防ぐ。本原則はこの実インシデントから抽出したチーム経験則である。
red flags（前工程のモデルを引きずっている兆候）:
- データ構造・実装の単位が、そのまま画面・API・文書の単位になっている
- 調査の途中で編集・実装を始めている
- レビュー・計画の途中で手が実装に伸びている
- 工程が変わったのに、直前の工程と同じ種類の成果物を出し続けている
書き分け:
- Claude Code / Codex 等のスキル環境では、メンタルモデルの指名は該当する設計判断スキル（ui-ux-design、module-boundary-design、database-design、refactor-mindset 等）を引くことと同型である。「この工程に対応するスキル・レンズはどれか」を自問してから着手する。
- スキル機構を持たないサービス側（Mastra の instructions 等）では、工程とモデルの宣言ステップを instructions に直接書く（例: 「各工程の開始時に、工程名と採用する観点を1行で宣言してから作業する」）。
5. 停止条件と eagerness
「いつまで続けるか」と「いつ止まるか」の両方を文面に明示すること。 どちらも書かれていない文面は、途中で止まる・過剰に続けるの両方向へ振れる。
- 続行側: 完了の定義（何が満たされたら終わりか）と、分析だけ返して途中で止まらないことを書く。
- 停止側: 探索・検証の上限（試行回数・収束条件）と、上限到達時のふるまい（結果と未解決点を報告して止まる）を書く。
- 不確実時の既定動作を書く: 推測で埋めるのか、確認を求めるのか、要確認マーカーを残して続行するのか。書かなければモデルごとの既定に振れる。
上限・予算をハーネス機構として持つ場合の設計は agent-harness-engineering §2 を参照する（文面はその値の意味を説明する側に回る）。
6. モデル世代とプロンプトの保守
モデルの世代交代は、文面を足すきっかけではなく削るきっかけとして扱うこと（公理9の執筆場面での実務形）。旧世代の弱点を補うために書いた文言は、新世代では過剰指示となり品質を下げうる。
世代交代時に棚卸す典型:
- 強調の積み上げ（CRITICAL / MUST の連打、怠慢対策の念押し）— 新世代では過剰発火・過剰遵守に振れる
- 思考手順の強制（step-by-step の台本）— §3 のとおり一般指示へ置き換える
- 自己検証の指示 — 既定で検証する世代には冗長になり、過剰検証を生む
- 弱点補正のための前処理・制限機構 — §0 の判断軸で再評価する
改訂は全面書き直しではなく、挙動の変化が観察された箇所だけを外科的に直すこと。検証手段（eval 等）を持つかどうかはプロジェクト側の判断であり、本スキルは要求しない。
7. コンテキストの渡し方
迷ったら渡すこと。 根拠は失敗モードの非対称性にある:
- 渡さなかったことによる劣化は、出力がもっともらしいまま静かに起きるため検知しづらく、モデルがどれだけ進化しても直らない（コンテキストに無いものは推論できない）。
- 渡しすぎによる劣化は、課題として観測してから対処でき、長コンテキスト性能の世代改善で自然に軽減しうる。
したがって、プロンプト長の一律上限・無差別な切り詰め・強制要約・エラー痕跡の消去を、先回りで文面や機構に入れないこと。圧縮・省略・compaction の導入は、コンテキスト量が課題として顕在化してからでよい（正本はコア公理5と agent-harness-engineering §3。導入すると決めた後の設計もそちらへ従う）。
出典
一次情報のみ。本文の原則は以下と、チーム内インシデント（§4 の実装モデル漏出）から抽出した。
- Anthropic: Effective context engineering for AI agents / Claude prompting best practices / Prompting Claude Fable 5 / Claude Code Best practices / Skill authoring best practices
- OpenAI: GPT-5 / GPT-5.1 / GPT-5.2 / GPT-4.1 prompting guides
- Cognition "Don't Build Multi-Agents" / Manus "Context Engineering for AI Agents"
- 研究: Plan-and-Solve (arXiv:2305.04091) / ReAct (arXiv:2210.03629) / Lost in the Middle (arXiv:2307.03172) / RULER (arXiv:2404.06654) / NoLiMa (arXiv:2502.05167) / When Instructions Multiply (arXiv:2509.21051) / Chroma "Context Rot"
- Alan Cooper『About Face』（3モデル論。§4 の棄却根拠）