185 lines
11 KiB
Markdown
185 lines
11 KiB
Markdown
# instruction のファイル参照化と system prompt 末尾の固定セクション
|
||
|
||
## 背景
|
||
|
||
pod-factory で `worker.system_prompt` を minijinja 文字列として扱う形にしたが、その後の運用方針の整理で以下のズレが見えてきた:
|
||
|
||
- **manifest を手で触らない前提**なので、`system_prompt` に minijinja 文字列をインラインで書く設計そのものが過剰。人間が書くのはプロンプトの**中身ファイル**だけで十分
|
||
- **AGENTS.md を `files.agents_md` として user template に露出**しているが、ユーザー領域のテンプレートに AGENTS.md 埋め込みを任せると、guard 忘れで静かに消えたり、preset を差し替えるたびに AGENTS.md の扱いが破綻する
|
||
- **scope はセキュリティ境界**なので、user の template が覚えていてくれる前提にすべきでない
|
||
- **prompt loader が by-name fallthrough**（project → user → builtin を順に探索）になっており、「同名上書き」と「偶然同名」が区別できない曖昧さがある
|
||
- 現在バイナリに同梱されている `coder` / `reviewer` / `planner` / `common/tool-usage` は AI 任せで書いた placeholder で、設計者の意図が乗っていない
|
||
- 既存の `Scope::summary()` は許可されたパスを列挙するだけで、**`recursive = false` の情報が失われて**おり、非再帰ルールの意味が LLM に伝わらない
|
||
|
||
## ゴール
|
||
|
||
1. `worker.system_prompt` を**ファイル参照フィールド** (`worker.instruction`) に置き換える
|
||
2. `$insomnia` / `$user` / `$workspace` の **import-map 形式の prefix** でプロンプト資産を addressing
|
||
3. scope と AGENTS.md を **コード側で system prompt 末尾に付加する固定セクション**として注入し、user template が触れない領域にする
|
||
4. 組み込みプロンプトを `$insomnia/default` の 1 本に整理
|
||
5. `Scope::summary()` のフォーマットを改善し、`recursive = false` を明示する
|
||
|
||
## 方針
|
||
|
||
### instruction フィールド
|
||
|
||
- manifest schema: `worker.system_prompt: Option<String>` を **`worker.instruction: Option<String>`** に置き換える（minijinja 文字列を持つフィールドを消し、ファイル参照だけを受ける）
|
||
- 値は import-map 記法のファイル参照: `$insomnia/default` / `$user/my-style` / `$workspace/custom`
|
||
- `.md` 拡張子は省略する
|
||
- **デフォルト値**は `$insomnia/default`。manifest で `instruction` を書かなければこれが使われる（`defaults.rs` に `DEFAULT_INSTRUCTION: &str = "$insomnia/default"` を追加）
|
||
- サブディレクトリ許容: `$insomnia/common/header` は `resources/prompts/common/header.md` を指す
|
||
|
||
### Prefix 解決
|
||
|
||
| prefix | 解決先 |
|
||
|---|---|
|
||
| `$insomnia` | バイナリ同梱の `resources/prompts/`（`include_dir!`） |
|
||
| `$user` | `$XDG_CONFIG_HOME/insomnia/prompts/`（factory が設定した user prompts dir） |
|
||
| `$workspace` | `<project>/.insomnia/prompts/`（factory が設定した project prompts dir） |
|
||
|
||
- 指定した prefix の dir に該当ファイルが無ければ **hard error**（fallthrough しない）
|
||
- 現在の「by-name で層を fallthrough して探す」ロジックは撤廃
|
||
|
||
### Unqualified include の相対解決
|
||
|
||
`{% include "name" %}` のように prefix 無しで書かれた場合は、**include を書いたファイル自身の prefix + ディレクトリからの相対**で解決する:
|
||
|
||
- `$insomnia/default.md` 内の `{% include "sub" %}` → `$insomnia/sub`
|
||
- `$insomnia/common/header.md` 内の `{% include "nested/foo" %}` → `$insomnia/common/nested/foo`
|
||
- `$user/custom.md` 内の `{% include "$insomnia/default" %}` → 明示的 prefix が優先
|
||
|
||
これにより「同じディレクトリ内でかたまって動くプロンプト集」を自然に書ける。
|
||
|
||
### system prompt 末尾の固定セクション
|
||
|
||
`SystemPromptTemplate` のレンダリング後に、Rust 側で以下の構造を**必ず**付加する（user template からは触れない）:
|
||
|
||
```
|
||
<instruction file のレンダ結果>
|
||
|
||
---
|
||
## Working boundaries
|
||
|
||
{scope.summary()}
|
||
{% if agents_md %}
|
||
---
|
||
## Project instructions (AGENTS.md)
|
||
|
||
{agents_md 本文}
|
||
{% endif %}
|
||
```
|
||
|
||
- 付加部分は Rust の `const` またはハードコードされたフォーマット文字列として実装し、`resources/` には置かない（user が触れる場所に置くと、触らないでほしいものが触れる場所に置かれる矛盾になる）
|
||
- scope セクションは **必ず** 出力される
|
||
- AGENTS.md セクションは不在時に省略（区切り `---` ごと省略）
|
||
|
||
### `SystemPromptContext.files` の削除
|
||
|
||
- `files` フィールドごと撤廃（元々 AGENTS.md 専用の予約席）
|
||
- user template から AGENTS.md を参照する手段は無くなる（末尾セクションが面倒を見る）
|
||
|
||
### `Scope::summary()` フォーマットの改善
|
||
|
||
`crates/manifest/src/scope.rs` の `Scope::summary()` を以下の方針で書き直す:
|
||
|
||
- **非再帰ルールを `[non-recursive]` でマークする**。例:
|
||
```
|
||
Readable:
|
||
- <local-path> [non-recursive]
|
||
Writable:
|
||
- <repo>
|
||
```
|
||
- マーカーの位置はパスの末尾（パースしやすさより人間可読性を優先）
|
||
- recursive = true の場合は何も足さない（デフォルトなので無印）
|
||
- deny ルールは現行どおり summary には出さない（`from_config` の時点で effective permission に焼き込まれるため）
|
||
- `Readable` / `Writable` のセクション分けは現行どおり
|
||
|
||
この変更により、最終セクションが出力する scope 情報が LLM にとって正確になる。
|
||
|
||
### 組み込みプロンプトの整理
|
||
|
||
- **削除**: `resources/prompts/coder.md` / `reviewer.md` / `planner.md` / `common/tool-usage.md`
|
||
- **新規**: `resources/prompts/default.md` 1 本のみ（内容は本チケットの実装時に author が記述）
|
||
- 将来、役割ごとの preset を復活させたくなったら別チケットで追加する（preset 概念そのものが pod-factory の範囲外だった経緯もあり、安易に戻さない）
|
||
|
||
## 要件
|
||
|
||
### Schema
|
||
|
||
- `manifest::WorkerManifest` と `manifest::WorkerManifestConfig` から `system_prompt` を削除、`instruction: Option<String>` を追加（部分形は Option、resolve 時に `defaults::DEFAULT_INSTRUCTION` で埋める）
|
||
- `manifest::defaults` に `DEFAULT_INSTRUCTION: &str = "$insomnia/default"` を追加
|
||
|
||
### Loader
|
||
|
||
- `PromptLoader` を prefix addressing 版に書き換える
|
||
- API: `PromptLoader::resolve(ref: &str, current: Option<&PromptRef>) -> Result<String, Error>`
|
||
- `ref` が `$prefix/path` 形式なら該当 dir を引く
|
||
- 素の `name` なら `current` の prefix + dir を前置して再帰 resolve
|
||
- `current` が無い状態で素の `name` が来たら **error**
|
||
- minijinja の `Environment::set_loader` 内で `current` を追跡する
|
||
|
||
### 末尾セクションの組み立て
|
||
|
||
- `SystemPromptTemplate::render` 相当の経路で、**user template 出力 + 固定末尾セクション**を連結する
|
||
- scope / AGENTS.md を formatter に渡す
|
||
- `Pod::ensure_system_prompt_materialized` の既存フローを素直に置き換える
|
||
|
||
### `Scope::summary()`
|
||
|
||
- `recursive = false` のルールに `[non-recursive]` マーカーを付ける
|
||
- 既存の `summary` 形式は維持（`Readable:` / `Writable:` のセクション + インデントのフォーマット）
|
||
- `crates/manifest/src/scope.rs` の既存テスト `summary_lists_readable_and_writable` / `summary_excludes_deny_rules` を更新または補完
|
||
|
||
### テスト
|
||
|
||
- 既存: `include_resolves_builtin_prompt` / `agents_md_is_injected_when_present` / `files_reserved_namespace_is_empty` / `files_map_*` 系を書き換えまたは削除
|
||
- 新規:
|
||
- `instruction_default_resolves_to_insomnia_default`
|
||
- `instruction_prefix_addressing_{insomnia,user,workspace}`
|
||
- `include_unqualified_resolves_relative_to_current_prefix`
|
||
- `include_explicit_prefix_overrides_relative`
|
||
- `prefix_with_missing_file_is_hard_error`
|
||
- `trailing_section_always_contains_scope_summary`
|
||
- `trailing_section_contains_agents_md_when_present`
|
||
- `trailing_section_omits_agents_md_when_absent`
|
||
- `scope_summary_marks_non_recursive_rules`
|
||
|
||
### ドキュメント
|
||
|
||
- `docs/pod-factory.md` を更新:
|
||
- `files.agents_md` の記述を削除
|
||
- loader の by-name fallthrough 説明を prefix addressing に置き換え
|
||
- `instruction` フィールドと `$insomnia/default` デフォルトの記述を追加
|
||
- system prompt 末尾の固定セクション構造を図示
|
||
- 必要なら `docs/system-prompt-template.md` も追随
|
||
|
||
## 他チケットとの関係
|
||
|
||
- **pod-factory (完了済み)**: 本チケットは pod-factory で実装した `PromptLoader` の**一部書き換え**になる。特に「3 層 by-name fallthrough」は撤廃される。pod-factory 自体をロールバックしない
|
||
- **tickets/native-gui-mvp.md**: 直接の交差なし。GUI が instruction を差し替えたいときは同じ prefix 形式で渡せば良い
|
||
- **tickets/protocol-design.md**: protocol 非依存
|
||
- **tickets/agents-md-ingestion.md (完了済み)**: AGENTS.md 読み取り経路は維持。表面の user template 経路だけが消える
|
||
|
||
## 完了条件
|
||
|
||
- manifest `[worker]` から `system_prompt` が消え、`instruction` でファイル参照を渡す形になっている
|
||
- `instruction` を省略すれば `$insomnia/default` が使われる
|
||
- `$insomnia` / `$user` / `$workspace` の 3 種の prefix でプロンプト資産を参照できる
|
||
- prefix 無しの `{% include %}` が include 元ファイルの prefix に相対解決される
|
||
- 未知の prefix や不在ファイルは hard error になる
|
||
- Pod の system prompt は常に「instruction の render 結果 + scope 要約 + (AGENTS.md があれば)」の構造で組み立てられる
|
||
- `SystemPromptContext` から `files` が削除され、user template から AGENTS.md を参照する手段は残っていない
|
||
- `Scope::summary()` が `recursive = false` ルールに `[non-recursive]` マーカーを付ける
|
||
- `resources/prompts/` は `default.md` 1 本のみ
|
||
- 上記挙動がすべて単体テストで担保されている
|
||
- `docs/pod-factory.md` が新方針に追随している
|
||
|
||
## 範囲外
|
||
|
||
- **preset 概念の復活**: 削除した `coder` / `reviewer` / `planner` を preset として体系化する議論は別チケット
|
||
- **instruction をファイル参照以外にする拡張**: インライン minijinja、TOML 配列、等は入れない
|
||
- **CLI 変更**: `pod` バイナリの flag は `--overlay` で instruction を上書きできる（`--overlay 'worker.instruction = "$user/foo"'`）形でそのまま使える。新規 flag は追加しない
|
||
- **テンプレートエンジンの差し替え**: minijinja を維持
|
||
- **`default.md` 本文の著者判断**: ticket の範囲は枠組み。本文は実装者が書く
|
||
- **scope summary に deny ルールを出す改善**: 現行どおり deny は effective permission に焼き込むだけで、summary には出さない
|