capturing-proposals

捕获优化提案

干活中发现可改进处时,顺手记一条提案,不打断当前任务。只记,不在此动手实现。

门槛(防淹)

只记两类:

• 会重复的坑:这次你解决了,但以后还会再撞上的。
• 具体的优化:能让以后的运行更顺/更省的、可固化的改进。

不要记:一次性且已彻底修好的、纯口味偏好、空泛的「以后也许可以」。不够格就一句话说明,不写文件。

归属(双轨)

• 项目特有(只对这个 repo 成立)→ 写到 <repo>/.agent_kaizen/inbox/。repo 根:git rev-parse --show-toplevel。
• 通用工作习惯(跨项目都成立)→ 写到全局 ${AGENT_KAIZEN_HOME:-$HOME/.agent_kaizen}/inbox/。

写前 mkdir -p 目标四态目录(inbox/accepted/rejected/watching)。

去重

写前扫目标 inbox 和同级 rejected/:

• 命中 inbox 近似项 → 给它 occurrences + 1 并在正文加一句新场景,不新建。
• 命中 rejected/ 近似项 → 已被否过,不重复提,一句话说明即可。
• 都没命中 → 新建。 近似判定:scope+kind 相同且 title/tags 高度重合。

文件

文件名 <YYYY-MM-DD>-<slug>.md(当天日期用 date +%F)。内容:

---
id: 2026-06-03-flaky-contract-test
created: 2026-06-03T14:22:00+08:00
scope: project            # project | global
kind: recurring-problem   # recurring-problem | optimization
title: 一句话标题
project: <repo 名或路径>   # 全局 inbox 尤其要,保留来源上下文
status: new               # new | accepted | rejected | watching
occurrences: 1
tags: [test, ci]
---
## 现象 / 触发场景
（当时在干什么、撞到了什么）
## 为什么值得优化
（重复频率 / 浪费的时间 / 风险）
## 建议方向（可选）
（建议落哪种家:instructions / hook / runbook / skill / 代码任务）
## 证据指针
（file:line、命令、报错片段——给指针不要贴大段）

写完告诉用户:记到哪了、是不是去重命中。然后回到原任务,不展开实现。