# Codebase Insights

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

- Skill: `tencentblueking/codebase-insights` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add tencentblueking/codebase-insights`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencentblueking/codebase-insights/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tencentblueking (https://skillmd.com/u/tencentblueking)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencentblueking/codebase-insights

---


# 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`，不要因为「这次改动看起来无关」而跳过——漂移正是从每次都觉得无关开始的。

## 篇目格式

```markdown
# <主题>

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

## 现象

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

## 证据

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

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

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

## 建议方向（未采纳）

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

## 待查证

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

## 纪律

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