docs: generalize memory prompt record policy

This commit is contained in:
Keisuke Hirata 2026-05-10 14:40:52 +09:00
parent 75ade5750e
commit 20c82a4bf6
5 changed files with 49 additions and 11 deletions

View File

@ -17,7 +17,7 @@ memory 関連 prompt は種別を問わず、最低限以下を共有する:
- **単純 append を優先しない**。既存 record に統合できるなら update を優先する
- **session 固有の進行状態を書かない**。長期参照価値のある内容だけを memory に残す
- **既存 docs と重複保存しない**。`AGENTS.md`、`docs/plan/*`、固定運用文書に既にある内容を再保存しない
- **git で追える事実を memory に書かない**。ticket file の作成・編集、TODO 更新、branch / worktree 操作、commit / merge / push、「commit X で実装した」「ticket Y を作った」「worker Pod を spawn した」等は git diff / log が真実で、memory に写すと陳腐化する。commit ハッシュ・branch 名・worktree パス・ticket file 名・PR 番号と組み合わせないと意味を成さない記録は採用しな
- **特定の project-management 手法を前提にしない**。既定 prompt は issue tracker / task board / planning doc / changelog / version-control history / generated report などを「正確な内容の authoritative record」として一般化して扱う。memory はそれらの本文・status 変化・短命 identifier をそのまま複製する parallel ledger にはしない。一方で、今後の作業に役立つ持続的な project-management 事実、workflow 制約、優先度判断の根拠、複数 item にまたがる学びは採用してよ
- **空出力を許容**する。保存価値が無ければ「何も追加しない」を正当な結果として扱う
### Phase 1: 活動抽出 prompt
@ -32,10 +32,10 @@ Phase 1 は「派生物を作る」段階ではなく、「起きたことを抽
ノイズ防御として、抽出時点で以下を除外する:
- `attempts`: git で追える操作 (ticket file / TODO 編集、branch / worktree 作成、commit / merge / push、既知 ticket への worker Pod spawn) は除外。残すのは git からは復元できない情報 (ビルド/テスト結果、外部 API 応答、観測されたバグ再現、後段の判断材料となる設計実験結果) に限る
- `discussions`: 当日中に陳腐化する一過性 triage (「次に着手するチケットはどれか」「いま review すべきか後でか」など) は除外。session を越えて意味を持つ論点 (アーキテクチャの trade-off、恒常的な制約、再来する問い) のみ残す
- `decisions`: rationale が「この session で X をした」になるものは除外。設計 / 方針 / 取り組み方の根拠でない記録は decision ではなく作業ログ
- 本文中に commit ハッシュ・branch 名・worktree パス・ticket file 名・PR 番号など陳腐化する identifier を埋め込まない
- `attempts`: authoritative record の保守や外部 lifecycle の移動そのものだけを表す操作は除外。残すのはその record 自体からは復元できない情報 (ビルド/テスト結果、外部 API 応答、観測されたバグ再現、後段の判断材料となる設計実験結果、持続的な process lesson) に限る
- `discussions`: 当日中に陳腐化する一過性 triage (直近の scheduling、status 確認、短命な順序決めなど) は除外。session を越えて意味を持つ論点 (アーキテクチャの trade-off、恒常的な workflow 制約、再来する問い) のみ残す
- `decisions`: rationale が「この session で X をした」になるものは除外。設計 / 方針 / process / 取り組み方の根拠でない記録は decision ではなく作業ログ。ただし、作業管理上の持続的な方針や抽象化は decision として扱える
- authoritative project record の title / body / checklist / raw status / 短命 identifier を本文に複製しない。正確な status mirror や identifier と組み合わせないと意味を成さない記録は採用しない
### Phase 2: 統合 + 整理 prompt

View File

@ -19,7 +19,7 @@ Your initial user message contains the staging entries, the full memory records,
- **Update over create.** If an existing slug fits, edit it. Only create a new slug when no existing record fits and you can articulate why.
- **`replaced` over delete.** When a Decision is superseded by a different one, mark the old one `status: replaced` with `replaced_by: <new-slug>`. Do not silently drop it.
- **Don't duplicate static docs.** Skip content that already lives in `AGENTS.md`, `docs/plan/*`, or other fixed project documents.
- **git is authoritative.** Do not record facts that git already tracks: ticket-file creation / edit, TODO updates, branch / worktree operations, commit / merge / push events, "implementation landed as commit X", "ticket Y was created", "worker Pod was spawned for Z". Diff and commit log are the truth there; memory shadowing it just rots. If a candidate write only makes sense when paired with a commit hash, branch name, worktree path, or ticket filename, drop it.
- **Respect authoritative project records.** Issue trackers, task boards, planning documents, changelogs, version-control history, and generated reports are authoritative for their exact contents. Do not mirror them verbatim, preserve raw status churn, or maintain a parallel ledger in memory. Durable project-management facts and abstractions are valid when they help future work: recurring workflow constraints, prioritisation rationale, long-lived ownership / process decisions, and stable lessons that cut across individual items. If a candidate write only makes sense as an exact status mirror or when paired with a transient identifier, drop it.
- **Empty output is fine.** If a staging entry doesn't justify a memory write, skip it.
- **Slug rules.** Slugs are kebab-case, short, recognisable, and must be unique within their kind. Same-slug create is a linter error — use Edit instead.
- **Linter errors come back as tool errors.** When the memory linter rejects a write, read the error, fix the issue (missing frontmatter field, oversized body, unknown reference, etc.), and try again. Do not work around the rule.

View File

@ -24,11 +24,11 @@ Your single job: read the supplied conversation slice and emit a structured JSON
# Anti-noise rules
git is the source of truth for what happened to files, branches, commits, tickets, and worktrees. Memory must NOT shadow it.
Authoritative project records (issue trackers, task boards, planning documents, changelogs, version-control history, generated reports) are the source of truth for their exact contents. Memory must not mirror those records verbatim or maintain a parallel status ledger, but it may capture durable project-management facts, workflow constraints, recurring patterns, and abstractions when they will help future work.
- `attempts`: skip any action whose substance is a git-trackable operation — creating / editing a ticket file, adding a TODO entry, opening a branch / worktree, running `commit` / `merge` / `push`, spawning a worker Pod for a known ticket. The corresponding diff / commit log already records it. Keep `attempts` for things that are NOT recoverable from git: build / test outcomes, external API responses, observed bug reproductions, design experiments whose results inform later judgement.
- `discussions`: skip transient triage that goes stale within the day — "which ticket to start next", "should we review now or later", checklist-style status reads. Keep discussions whose points outlive the session (architectural trade-offs, durable constraints, recurring questions).
- `decisions`: the rationale must be a design / policy / approach reason, not "we did X in this session". Recording "a ticket was created for Y" or "implementation landed as commit Z" is NOT a decision — those belong to git, not memory.
- Do not embed identifiers that age out of relevance: commit hashes, branch names, worktree paths, ticket file names, PR numbers. If a record is only meaningful with such an identifier, the record itself is probably session-local and should be skipped.
- `attempts`: skip actions whose only substance is maintaining an authoritative record or moving an item through an external lifecycle. Keep attempts for outcomes that are not captured by that record itself: build / test outcomes, external API responses, observed bug reproductions, design experiments, and process lessons that inform later judgement.
- `discussions`: skip transient triage that goes stale within the day — immediate scheduling, checklist-style status reads, or short-lived sequencing choices. Keep discussions whose points outlive the session (architectural trade-offs, durable process constraints, recurring workflow questions).
- `decisions`: the rationale must be a design / policy / process / approach reason, not "we did X in this session". Recording that an item was filed, completed, or moved through a lifecycle is NOT a decision; recording the durable policy or abstraction behind that workflow can be.
- Avoid copying titles, bodies, checklists, raw statuses, or short-lived identifiers from authoritative project records. If a record is only meaningful as an exact status mirror or with a transient identifier, the record itself is probably session-local and should be skipped.
When you have produced the JSON, call `write_extracted` and end the turn. No follow-up text.

View File

@ -44,3 +44,8 @@
- `resources/prompts/internal/memory_consolidation_system.md`
- `docs/plan/memory-prompts.md`
- `docs/plan/memory.md`
## Review
- 状態: Approve
- レビュー詳細: [./memory-prompts-remove-ticket-policy.review.md](./memory-prompts-remove-ticket-policy.review.md)
- 日付: 2026-05-09

View File

@ -0,0 +1,33 @@
# Review: Memory prompts: project-specific ticket shadow policy を外す
## 前提・要件の確認
- bundled memory prompts から ticket / TODO 固有の shadow 禁止を削除: OK。Phase 1 prompt は ticket / TODO / worktree / branch / commit 等の列挙を消し、authoritative project records 一般へ置き換えている(`.worktree/memory-prompts-remove-ticket-policy/resources/prompts/internal/memory_extract_system.md:27-32`。Phase 2 prompt も `git is authoritative` と ticket/TODO 固有列挙を削除し、issue trackers / task boards / planning documents 等の一般表現へ置換している(`.worktree/memory-prompts-remove-ticket-policy/resources/prompts/internal/memory_consolidation_system.md:21-22`)。
- `git is authoritative` の扱いを一般ユーザー向けに弱める: OK。正確な内容の authoritative record を memory が mirror しないという原則は残しつつ、durable project-management facts / workflow constraints / prioritisation rationale / process decisions / cross-item lessons は保存可能と明示している(`memory_extract_system.md:27-32`, `memory_consolidation_system.md:22`)。
- Phase 1 / Phase 2 の整合: OK。Phase 1 の抽出除外条件と Phase 2 の統合時ルールがどちらも「raw status ledger は作らないが、持続的な抽象は採用可」という同じ方針になっている(`memory_extract_system.md:29-32`, `memory_consolidation_system.md:22`)。
- default prompt が特定 project-management 手法を前提にしないことの文書化: OK。`docs/plan/memory-prompts.md` の共通原則に「特定の project-management 手法を前提にしない」が追加され、ticket / TODO 固有の旧記述が一般化されている(`.worktree/memory-prompts-remove-ticket-policy/docs/plan/memory-prompts.md:19-20`)。
- 既存テスト / prompt catalog 検査: OK。`cargo test -p pod prompt::catalog` を実行し、11 tests passed。
## アーキテクチャ・スコープ
- 変更は bundled prompt 2 件と plan doc 1 件のみで、memory の file format / linter / Phase 1 / Phase 2 実行機構には触れていない。ticket の範囲外を守っている。
- prompt 文言の責務分離は妥当。INSOMNIA 固有の ticket shadow 回避を default prompt から外し、workspace / user prompt override 側へ逃がせる状態にしている。
- `docs/plan/memory-prompts.md` も同時に更新しており、実装 prompt と計画文書が乖離していない。
## 指摘事項
### Blocking
なし。
### Non-blocking / Follow-up
なし。
### Nits
- `docs/plan/memory-prompts.md:68` に「git で可逆」という表現が残っているが、これは tidy phase の drop 判断に関する一般的な VCS 可逆性の話で、ticket / TODO 固有の shadow policy ではないため本チケットの完了を妨げない。
## 判断
Approve — ticket / TODO 固有の bundled prompt 方針は削除され、一般的な authoritative record 非重複方針へ置き換わっている。変更範囲も prompt / plan に限定され、既存 prompt catalog tests も通っている。