| 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 加自解释的文件名即可。多一层索引就多一处会腐烂的东西
