Vv Comments

---
name: vv-comments
description: 去掉 VibeValley 代码里没价值的注释：用 scripts/comment-review.ts 让模型照 docs/style/code.md 初审，再逐条对着代码核实，能删的删、能让名字说的改名、只剩一句有用的改短。用在：写完代码、提 PR 前审这个分支新加的注释；用户说「清理注释」「注释太多」「去掉废话注释」「这块的注释看看」时清一块已有的注释；评审时看到复述代码、分节标题、测试旁白、文件开头的概述。
---

# 去掉没价值的注释

注释只留不看它就会写错或改错的东西，规矩和例子在 [docs/style/code.md](docs/style/code.md#注释)，本文不复述。分隔线和给一段代码起的标题 `vp check` 已经挡了（`vibevalley/no-comment-divider`）；剩下的要读懂才判断得了，模型先审一遍，你对着代码定每一条。偏向删：留一条废话的代价是每个读的人都读一遍，删错一条的代价是下一个改它的人可能写错；拿不准的那一条就去问「删掉它，改这段的人会写错什么」，说不出具体会错什么的，删。

## 1. 定范围

- **提 PR 前**（默认）：这个分支比 `origin/main` 新加的注释，包括没提交的。
- **用户点了一块**：那个模块或目录里已有的全部注释，一次一块，不扫整个仓库。
- **用户没点、分支也没有新注释**：问用户清哪块。

先 `--dry-run` 数一数，不调模型：

```bash
vpx scripts/comment-review.ts --dry-run                          # 这个分支新加的
vpx scripts/comment-review.ts --all apps/server/src/issue --dry-run   # 一块已有的
```

花钱的量级：一个模块一两百条注释、十次以内的请求，一分钱上下。新加的直接跑；`--all` 超过 500 条，先把条数告诉用户再跑。

## 2. 跑

```bash
vpx scripts/comment-review.ts                                    # 要 DEEPSEEK_API_KEY
vpx scripts/comment-review.ts --all apps/server/src/issue
```

每条不该留的打三行：`文件:行  delete|rewrite  <对上的规矩那一行>: <理由>`、注释原文、`rewrite` 的话 `→ 改好的写法`。判 `keep` 的不打。有不该留的退出码 1；模型漏答或答得不成格式，脚本报错退出，重跑一次，还错就看报错。

## 3. 逐条核实

模型只读了注释附近的十几行，会判错。每一条打开文件、读它说的那段代码，按顺序问：

1. **删掉它，改这段的人会写错什么？** 说不出来就删。复述名字和签名、讲这段代码在做什么、测试里讲每一步、写这段从哪来的、文件开头概述这个文件有什么的，都在这里删掉。
2. **说得出，能不能让代码自己说？** 局部变量、参数、私有函数的名字说不清的，改名字；「`""` 表示没有」这类取值，能用类型（联合、`undefined`）说的改类型；然后删注释。导出的名字、接口、表的字段改名牵连大，不在这里改，记下来告诉用户。
3. **代码说不了，注释里还夹着别的？** 只留那一句（为什么、顺序和锁、安全边界、单位和取值、要和哪里一起改），别的删掉。模型给的 `rewrite` 是参考，常常还能更短；留下的照周围的口吻，英文，从这件事本身说起。
4. **模型判错了**（它就是 [建议写](docs/style/code.md#建议写) 那几类，删了真会写错）：留着，记下文件、行和理由，汇报时列出来。

删的时候连带收拾：注释删掉后留下的连着两个空行合成一个；整段 JSDoc 一起删；行尾的 `// …` 连前面的空格一起删。工具的指令（`@ts-expect-error`、`oxlint-disable`、`@internal`）脚本不审，也别删。

只动模型报出来的和你核实时顺带看到的同一类；模型判 `keep` 的不逐条重审，模块里别的问题（死代码、能简化的）记下来，交给 [vv-simplify](.agents/skills/vv-simplify/SKILL.md)。

## 4. 改完

- `vp check --fix`，再 `vp check`。只删、改了注释，不用跑测试；改了名字或类型，跑和那块有关的最窄的检查（`vp run server:check`、`vp run web:check`）。
- 再跑一次第 2 节的命令：改写的注释是新加的，会再审一遍；模型每次判的不一样，`--all` 的第二轮还会在第一轮留下的里报出新的，照第 3 节核实。第二轮还报的、你已经判过要留的，不再改，不来回拉锯。
- 清一块已有的注释是机械改动，单独一个 PR（[vv-pr](.agents/skills/vv-pr/SKILL.md) 第 1 节），一块一个；标题说改完以后的样子（`Issue module comments say only what the code cannot`）。

## 5. 汇报

- 审了多少条，删了几条、改短了几条、改名或改类型替掉了几条。
- 模型判了不该留、你留下的：每条 `文件:行` 和一句理由。
- 看到了没改的：导出的名字说不清的、别的该简化的地方。