agentleFS
vibevalleyhqvibevalleyhq/vibevalley/.agents/skills/vv-governance/SKILL.md

vv-governance

Skill12 starsChanged yesterdayApache-2.0View on GitHub

在 VibeValley 里管住 agent 写的代码不变坏:加规矩、lint、检查或棘轮时选最便宜的手段;评审一块代码有没有在变坏(抄第二份、旧的没删、as/空 catch/改断言、N+1、乱引依赖);写计划前问清边界;做纯重构或跨很多文件的机械改动;用户问白皮书(五层金字塔、十条铁律)的某一条在这里做不做(契约墙、骨架、处方式报错、3+1、合并队列……);用户说「怎么防止 agent 把代码写烂」「这个检查该怎么加」「这块是不是越改越乱」时也用。

The file

Files
SKILL.md

管住 agent 写的代码不变坏

白皮书的判断:代码由 agent 写以后,写代码不再稀缺,稀缺的是架构的一致、契约的完备和用户的注意力;挡问题要按成本从低到高,能用编译器和检查挡的不花模型和人。这和根目录 AGENTS.md 的四层手段是同一个原则,本 skill 把白皮书的每个要点对到这个仓库上。

规矩的家不在这里。 规矩在 AGENTS.md、docs/ 和各包的 README,和白皮书说法不同时照它们。白皮书是为一个通用的、多人的仓库写的(src/contracts、src/features、bun、ast-grep、300 行上限),不少条和这里的规矩相反(禁用 default、契约目录只读、存档快照升级);照原样做会把仓库往别的方向拉。所以先查一条要点在这里的处境,再动手。

先读哪里

  • 要回答「白皮书的某一条在这里怎么样」,或者下面任何一步碰到具体的一条:读 references/whitepaper.md 里对应的一行。每条写了处境:已有(在哪)、已做(吸收白皮书时加的,在哪)、改写(思路留下、换成这里的做法)、以后做(什么条件下做,挂在提案)、不做(为什么)。
  • 回答这类问题时,先给处境的结论,再给在哪、为什么;以后做的说出触发条件;不做的说出它和哪条规矩冲突。不要把白皮书的原文当成这里的做法讲。

1. 加一条规矩或一个检查

agent 照着已有的代码抄、走最短的路,写在文字里的规矩会被漏读、读偏;写成检查的,问题在落地前就被拦下,还不花 token。

  1. 说清它挡的是哪一类问题,对上六种病里的哪一种(六种病)。说不出一类、只是一次的事,不立规矩:规矩越多越容易漏读。
  2. 按顺序选手段,能用前面的就不用后面的:代码(类型、结构、边界,把这一类整个消掉)→ 检查(lint、测试、CI、棘轮)→ 文字(规矩、skill)→ 人看。
  3. 写成检查时,失败的话写三样:错在哪和为什么、Fix: 能照抄的改法、See 仓库里一个文件(写法)。agent 读到的只有这句话,只说「不许」它就猜,猜的常常是绕过去。lint 规则用 scripts/audit/oxlint-plugin.ts 的 says,no-restricted-imports 的话写进 vite.config.ts 的 refused;规则算得出改法的就算出来(parent-import 给出 #/…),能机械改对的给自动修复。
  4. 只许减不许增、数得清、又没有动机去刷的,做成棘轮(packages/health 的逃生口,escapeAdvice 写每种该怎么改);会被刷的读数(行数、测试数、覆盖率)只出报告,不做门槛,否则 agent 学会的是凑数。
  5. 给检查写测试:一个该拦的、一个不该拦的,加上报错的格式。
  6. 写不成检查的才进文字:一句规矩放进 AGENTS.md 并链到它的家,理由写进对应子系统的「为什么这样」。

2. 评审一块代码有没有在变坏

六种病都是 agent 的工作方式带来的,单个 PR 里不显眼,攒起来才坏事。逐条问,每条都有现成的办法查:

病问怎么查
局部缝合同一段逻辑是不是抄了第二份?加一个渠道、工具、runtime 时,有没有把超时、重试、清理又写一遍?搜这段逻辑的关键调用;看扩展点(apps/server/src/gateway/connector/ 下各聊天软件的 adapter、apps/server/src/gateway/tool/)有没有自己的 AbortSignal.timeout、sleep、重试循环
只加不删换了新写法,旧的删了没有?vp run deadcode;搜旧函数名;内部不留兼容:不留旧路、不写兜底
绕开约束有没有 as、as unknown as、!、关 lint 的注释、空的 catch、.catch(() => undefined)?测试的断言是不是改松了?vp run health:verify(逃生口的棘轮);diff 里的测试改动;regression: 开头的测试被动了要在 ## Regression 里点名
温室假设循环里有没有逐个查库、逐个起 git?流是不是假设一次到一整行?写盘是不是每来一点就写一次?读循环体;docs/subsystems/foundation.md「贵的东西归拥有它的模块管」;测试里有没有大一点的数据
架构漂移有没有新加依赖?有没有跨层、跨模块、穿过别人 index.ts 的 import?pnpm-workspace.yaml 的 catalog 的 diff;vp check(page-layers、import/no-cycle、no-restricted-imports);apps/server/src/modules.test.ts
看不过来用户要读哪几行才能放心合?契约(packages/protocol、db/、服务接口)改了什么?把契约的 diff 单独列在 PR 正文最前;一批工作一个 PR,不同的事分成不同的提交(vv-pr 第 1 节)

查到的照 vv-simplify 的格式列给用户:每处带证据(文件和行号、命令的输出)、怎么改、靠哪个测试证明没变坏。只列不改,用户点了再改。

3. 写计划前问清边界

带着猜测写下去的代码,猜错了要整块返工;问一句只花用户几秒。写计划 Note 或开工前,下面四类有一类说不清,就问用户,不猜:

  • 失败和边界:外面的接口超时或失败时,是忽略、重试几次,还是停下回滚?
  • 并发和重复:同一张工单、同一个人重复触发时,是排队、丢掉新的,还是取消旧的?
  • 规模:列表会不会超过一百条?要不要分页或上限?
  • 存量数据:这一类不用问,答案固定是不兼容:表结构直接改,旧库挪开(地基);只有对外 HTTP 的 v1 例外。

问的时候用选择题,一题一个决定,推荐项放第一个并说为什么。

4. 做一张纯重构的单

agent 加功能时只在局部补,不会顺手提炼;提炼要单独一道工序,而且这道工序不改行为,用户才能只看「行为没变」的证据就合。

  1. 靶子来自读数,不来自印象:vp run health 的热点、vp run deadcode、vv-simplify 找到的重复。凭印象挑的常常不是最该清的。
  2. 分开不变的和变的:几处一样的控制流(截断、退避、重试、失败时发什么)收进一个地方(拥有它的模块的服务,或一个骨架函数),各处只留自己不同的那一点(报文怎么拼、怎么签名),作为参数或窄接口传进去。
  3. 重构自成一个或几个提交,不和功能的改动混在同一个提交里;单独做的重构分支用 refactor/,和同一批的功能一起交时放在同一个 PR,用户要求才拆(vv-pr 第 1 节)。行为不变:测试只因改名、挪地方而变,断言不减;regression: 开头的测试不动。
  4. 结果要可量:删了多少行、调用方少知道了什么、哪个测试证明行为没变,写进那个提交的说明和 PR 的 ## What changed。行数不设门槛(会被刷),但一张重构单没有让代码变少或变简单,就不该合。

5. 一次改很多文件

逐个文件手改,改到后面容易漏、容易改歪;同一种改动交给确定的工具一次做完。

  • 改名用 TypeScript 的语言服务(编辑器的重命名);去掉没人用的 export 用 vpx knip --fix --fix-type exports,types;结构性的改写用 ast-grep 或 ts-morph 写一次性的脚本,脚本放在临时目录,不进仓库(进了仓库会被当成代码检查、格式化)。
  • 先在一个文件上跑,看 diff 对了再全量跑;全量跑完立刻 vp check。脚本出过错的,把它碰过的文件从 origin/main 恢复,重新来,不在坏的结果上修补:坏在哪不一定看得出。
  • 每处不一样、要逐处判断的(删死代码、改调用方的逻辑),即使文件多也逐处看过再改。
  • 漏改由 vp check(类型)和 scripts/docs/stale-names.ts 兜底:改名是一个决定时,把旧名写进 stale-names.ts,旧名就回不来。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.