codebase-insights

name	codebase-insights
description	沉淀与查阅跨模块一致性问题：同一语义在多处被独立实现且实现之间已经漂移（列宽、魔法数字、按 DB 类型复制的组件家族、已有抽象覆盖不全等）。两个时机使用：任务收尾回顾本次读过或改过的代码并把够判据的发现记成篇目； 以及改表格、公共组件、按 DB 类型复制的代码前查阅已有篇目。当用户要求总结、复盘、沉淀经验， 或问「这类问题还有哪些」「以前记过什么」时也使用。
disable-model-invocation	true

codebase-insights

沉淀「同一语义在多处被独立实现、且实现之间已经漂移」这类问题。篇目存在本 skill 的 insights/ 下，一个主题一篇 .md，文件名即主题（kebab-case）。

全程只读代码，不改代码。 记录与修复是两件事，修不修由用户决定。

能力边界（先说清楚，避免过度承诺）

• 跨会话没有记忆，只有写进 insights/ 的文字才会传递到下一次
• 不做全库扫描，只覆盖本次任务实际读进上下文的代码。沉淀天生是增量的、有偏的、不完整的
• 因此每篇都要写「待查证」，标明这篇没覆盖到哪些范围，别让读者把局部结论当成全局结论

时机一：任务收尾回顾

每个任务收尾时回顾一次：本次读过或改过的代码里，有没有同一语义被多处独立实现、且取值或写法已经漂移的情况。

判据

满足其一才记：

• 同一语义在 ≥3 处独立实现，且取值已经不一致
• 已经存在正确抽象，但覆盖不全（部分调用方走抽象、部分自己实现）
• 同名不同义，或同义不同名

不记：单点 bug、个人风格偏好、以及 ESLint / Prettier / Stylelint 能自动修的问题。宁可不记，也不要记成流水账——清单一旦注水就没人看了。

流程

1. ls .agents/skills/codebase-insights/insights/ 看有没有同主题。有就往里补证据，不新开一篇
2. 核实证据。写进篇目的每个数字都要亲自读到，不能凭 grep 计数或印象推断。核实过程中经常会挖出比初始判断更强的证据
3. 按下面的格式写入
4. 在回复里跟用户提一句记了什么，不要顺手去改

时机二：改代码前查阅

动手改代码前先 ls 一下 insights/，文件名即主题，一眼能判断有没有相关篇目，有就读完再动手，避免在已知有漂移的地方再添一处新取值。

成本只有一次 ls，不要因为「这次改动看起来无关」而跳过——漂移正是从每次都觉得无关开始的。

篇目格式

# <主题>

状态：未处理 | 处理中 | 已修复

## 现象

一段话说清楚这是什么类型的漂移，以及它造成的实际后果（不是「不优雅」，是用户能看到或维护者会踩到的后果）。

## 证据

每条给 `文件:行` 与实际取值。多个来源的同类取值用表格汇总，再补几条最有说服力的具体出处。

## 项目里已有的正确做法

这个项目通常已经有做对的地方，写清是哪里、为什么它是对的、以及它没覆盖到哪。没有正确做法就写「暂无」，不要编。

## 建议方向（未采纳）

给方向和理由，同时写清哪些直觉做法不可行、为什么。标注「未采纳」，避免后来者误以为已成定论。

## 待查证

本篇没覆盖的范围、以及尚未验证的推断。推断不与已核实的证据混写。

纪律

• 已核实的证据与未验证的推断必须分开放，后者一律进「待查证」
• 证据要能被复现：给 文件:行 和实际取值，不写「很多地方都是这样」
• 建议方向要连同「不推荐的做法及原因」一起写。只写推荐方案的话，后来者会重新踩一遍被否掉的路
• 篇目不做索引文件，靠 ls 加自解释的文件名即可。多一层索引就多一处会腐烂的东西