| name | codebase-insights |
| description | 沉淀与查阅跨模块一致性问题:同一语义在多处被独立实现且实现之间已经漂移(列宽、魔法数字、按 DB 类型复制的组件家族、已有抽象覆盖不全等)。两个时机使用:任务收尾回顾本次读过或改过的代码并把够判据的发现记成篇目; 以及改表格、公共组件、按 DB 类型复制的代码前查阅已有篇目。当用户要求总结、复盘、沉淀经验, 或问「这类问题还有哪些」「以前记过什么」时也使用。 |
| disable-model-invocation | true |
codebase-insights
沉淀「同一语义在多处被独立实现、且实现之间已经漂移」这类问题。篇目存在本 skill 的 insights/ 下,一个主题一篇
.md,文件名即主题(kebab-case)。
全程只读代码,不改代码。 记录与修复是两件事,修不修由用户决定。
能力边界(先说清楚,避免过度承诺)
- 跨会话没有记忆,只有写进
insights/ 的文字才会传递到下一次
- 不做全库扫描,只覆盖本次任务实际读进上下文的代码。沉淀天生是增量的、有偏的、不完整的
- 因此每篇都要写「待查证」,标明这篇没覆盖到哪些范围,别让读者把局部结论当成全局结论
时机一:任务收尾回顾
每个任务收尾时回顾一次:本次读过或改过的代码里,有没有同一语义被多处独立实现、且取值或写法已经漂移的情况。
判据
满足其一才记:
- 同一语义在 ≥3 处独立实现,且取值已经不一致
- 已经存在正确抽象,但覆盖不全(部分调用方走抽象、部分自己实现)
- 同名不同义,或同义不同名
不记:单点 bug、个人风格偏好、以及 ESLint / Prettier /
Stylelint 能自动修的问题。宁可不记,也不要记成流水账——清单一旦注水就没人看了。
流程
ls .agents/skills/codebase-insights/insights/ 看有没有同主题。有就往里补证据,不新开一篇
- 核实证据。写进篇目的每个数字都要亲自读到,不能凭 grep 计数或印象推断。核实过程中经常会挖出比初始判断更强的证据
- 按下面的格式写入
- 在回复里跟用户提一句记了什么,不要顺手去改
时机二:改代码前查阅
动手改代码前先 ls 一下 insights/,文件名即主题,一眼能判断有没有相关篇目,有就读完再动手,避免在已知有漂移的地方再添一处新取值。
成本只有一次 ls,不要因为「这次改动看起来无关」而跳过——漂移正是从每次都觉得无关开始的。
篇目格式
# <主题>
状态:未处理 | 处理中 | 已修复
## 现象
一段话说清楚这是什么类型的漂移,以及它造成的实际后果(不是「不优雅」,是用户能看到或维护者会踩到的后果)。
## 证据
每条给 `文件:行` 与实际取值。多个来源的同类取值用表格汇总,再补几条最有说服力的具体出处。
## 项目里已有的正确做法
这个项目通常已经有做对的地方,写清是哪里、为什么它是对的、以及它没覆盖到哪。没有正确做法就写「暂无」,不要编。
## 建议方向(未采纳)
给方向和理由,同时写清哪些直觉做法不可行、为什么。标注「未采纳」,避免后来者误以为已成定论。
## 待查证
本篇没覆盖的范围、以及尚未验证的推断。推断不与已核实的证据混写。
纪律
- 已核实的证据与未验证的推断必须分开放,后者一律进「待查证」
- 证据要能被复现:给
文件:行 和实际取值,不写「很多地方都是这样」
- 建议方向要连同「不推荐的做法及原因」一起写。只写推荐方案的话,后来者会重新踩一遍被否掉的路
- 篇目不做索引文件,靠
ls 加自解释的文件名即可。多一层索引就多一处会腐烂的东西