Vv Simplify

---
name: vv-simplify
description: 在 VibeValley 里找可以简化的地方：删掉以后什么都不少的代码、只是转手的一层、几份重复的帮手、只给测试开的选项、兼容旧数据的兜底、手写的 Effect 已经有的东西、多余的注释；每一处核实过、带证据，排好序列给用户，用户点了哪几处再改。用在：用户说「看看哪里能简化」「找找冗余」「这块是不是写复杂了」「simplify」；做完一块功能想收一收；评审时觉得一块代码比它做的事复杂。默认只列清单，不动代码。
---

# 找可以简化的地方

简化是让同样的行为用更少的概念和代码做到：调用的人要知道的少了，改一处不用跟着改好几处。只是换种写法、挪个文件、改名、格式，不算。

## 1. 定范围

- 用户说了一块（一个模块、一个目录、一个流程），就看那块，连同调用它的地方。
- 没说，就看当前分支相对 `origin/main` 的改动：`git diff origin/main...HEAD --stat`，再读改到的文件和它们的调用方。
- 也没有改动，问用户看哪块，不要一口气扫整个仓库。

先读那块的子系统文档（[docs/subsystems](docs/subsystems/README.md)），特别是「为什么这样」：那里记着有意的取舍，不要把它们当成冗余再提一遍。写 Effect 的，先读 `node_modules/effect/AGENTS.md`。

## 2. 找什么

按删得多、风险小排，前面的优先：

1. **兼容和兜底**：读旧格式、旧名字、旧环境变量的分支，给旧数据的默认值，数据搬运。仓库的规矩是内部不留兼容（AGENTS.md「内部不留兼容」），这些直接删。
2. **死的东西**：没人调的导出、函数、参数、选项、字段，永远走不到的分支。用 `git grep -n '<名字>'` 数调用方，别只信编辑器。
3. **只转手的一层**：一个函数或模块只是把参数原样递给另一个。删掉它试试，复杂度是消失了，还是挪到了每个调用方？消失了才算。
4. **重复的帮手**：几个模块各写一份做同一件事的（以前的十份 `db` 帮手就是这样收成一个 `Db` 服务的）。收到拥有它的那个模块，别的用它的。
5. **只给测试开的口子**：服务的 `options` 里只有测试才传的选项（以前的 `now`、`patrolNow`），换成测试已经有的接缝（`testing/world.ts` 的选项、`Clock`、layer）。
6. **手写了 Effect 已经有的**：`forever` 加 `sleep`（用 `Schedule`）、自己管 fiber 的集合（`FiberSet`、`FiberMap`）、手写解析 JSON 再 `as`（`Schema`）、自己数时间（`Clock`）。照仓库里已有的写法，不引进新的。
7. **状态多存了一份**：页面或服务端在核心状态以外另存了帮工、工单的状态（AGENTS.md「核心状态只有一份」）。
8. **封闭联合的长 `if`/`else`**：换成穷尽的 `switch` 或 `Record<X, …>`，加新成员时编不过。
9. **多余的注释**：复述代码、写历史、写概述的（[docs/style/code.md](docs/style/code.md)「不建议写」）；整块清的话交给 [vv-comments](.agents/skills/vv-comments/SKILL.md)。

不算简化，不要提：

- 为了少几行把清楚的代码写成难读的。
- 新造一个通用的框架、基类、配置项，只为把两处相似的代码合起来（两处不一样的理由可能就在明天）。
- 子系统文档「为什么这样」里已经否决过的（比如 foundation.md 记着不把 `ApiError` 换成 `TaggedError`、`repo/git.ts` 的子进程留在 `Effect.callback`、外面的库的一次调用留在 Promise）。
- 只是个人口味的写法。

## 3. 核实每一处

每一处都在代码上核实了才列，不凭印象：

- 找全调用方（`git grep`），确认删掉或合并以后它们都还对。
- 想一想有没有测试或检查能证明简化以后行为没变：已有的测试覆盖到了，写出是哪个；没有，写出要补哪个测试。
- 拿不准的（可能有外部的调用方、可能是有意的），标「待确认」并写出要问用户什么，不当成结论。

## 4. 列给用户

列在回复里；超过十处的，写进 scratchpad 的一个 Markdown 文件，回复里只放前五处和文件路径。每一处一段：

- **在哪**：`文件:行`，和调用方的位置。
- **是什么**：一句话，属于第 2 节的哪一类。
- **删掉什么**：大约多少行、哪个概念、哪个选项；调用的人以后不用知道什么。
- **怎么证明没变坏**：哪个测试或检查，或要补的测试。
- **风险**：小、中、大，一句理由。

最后一段写建议先做哪几处、合成几个 PR（照 [vv-pr](.agents/skills/vv-pr/SKILL.md) 第 1 节：同一块的几处小简化放一个 PR，大的机械改动单独一个）。然后停下，问用户做哪几处。

## 5. 用户点了以后

- 只做点了的那几处，不顺手扩大范围；做的时候发现新的，记下来，下一轮再列。
- 先跑相关的测试，确认改之前是绿的；改完再跑，行为没变。要补测试的先补。
- 照 [vv-pr](.agents/skills/vv-pr/SKILL.md) 开 PR：标题说简化以后代码是什么样（`One Db service runs every module's queries`），正文每处一条，写删掉了什么、靠哪个测试证明没变。