AI 编程助手总改错文件:三份规则文件把范围收住

它把 dist 里的构建产物当源码改,顺手动了公共包,还忘了会话开头说过的边界。三份规则文件加一张任务卡,把“改哪里、别碰哪里、改完怎么验”写死,返工率降了大概七成。

用编程助手改一个中台项目,第一周我就停用了它:让它加个导出按钮,它改的是 dist/assets/index-8f3c.js;让它调一下列表接口,它把 legacy/ 下的旧版组件一起改了;让它修一个表单校验,它顺手把相邻三个页面的公共 hooks 重构了,跑起来五个页面报错。

这些都不是"模型太笨"。同一个模型在另一个只有三十个文件的小仓库里表现很好。差别在于仓库里没有任何东西告诉它"改哪里、别碰哪里、改完怎么验"——它只能根据文件名猜。后来我在仓库根目录放了三份文件,加了一条"先给计划"的流程,返工率大概降了七成。

一、它改错文件的三种方式

第一种是改构建产物。仓库里同时存在 src/ 和 dist/,dist 里的压缩文件名跟源码里引用的一模一样,模型搜到 exportReport 就直接改了那份 800 KB 的产物。第二种是改"看起来像"的旧目录,比如 legacy/、v1/、backup/,这些目录往往还能编译通过,所以问题不会立刻暴露。第三种是跨边界顺手改:为了修一个页面的校验,它去动了 packages/shared 里的公共函数,理由是"这样更一致"。

写完问题清单我才意识到,这三种都源于同一个缺口:仓库没有显式的"入口"和"禁区"。

二、规则文件别写项目介绍,写边界

编程助手会优先读仓库根目录的约定文件(不同工具的命名不同:AGENTS.md、CLAUDE.md、.cursor/rules)。我第一版写成了 README 的复述——技术栈、目录结构、启动命令,结果它照旧改错文件。真正有用的是"约束"而不是"介绍":

# AGENTS.md

### 改动边界
- 只改 `src/` 下的文件。`dist/`、`build/`、`public/vendor/` 是产物或第三方代码,任何情况下不要编辑。
- `legacy/`、`v1/` 已冻结,只读;需要参考时读,不要改。
- `packages/shared/` 是对外发布的包,改动前必须征询;优先在调用侧解决。

### 改之前必须做
- 先用 `rg -n "<符号名>" src/` 定位真实定义位置,不要按文件名猜。
- 涉及三个以上文件时,先给出改动清单(文件 + 改动意图 + 验证命令),等我确认。

### 改完必须跑
- `npm run lint -- --max-warnings=0`
- `npm run test -- --run src/features/<模块>`
- 类型检查:`npx tsc --noEmit -p tsconfig.app.json`

### 代码约定
- 不新增依赖;确实需要时在回答里单独列出理由,不要直接改 package.json。
- 提交信息用 `fix(scope): ...` / `feat(scope): ...`,一次提交只做一件事。

这四段里,"改动边界"和"改完必须跑"是效果最明显的两条。前者直接消掉了前面三种错法,后者让它在交付前自己发现错误,省掉我复述报错的一轮。

三、用检索命令代替粘贴代码

我以前的用法是把相关文件内容整段贴进对话,一次贴四五个文件。这样有两个问题:上下文很快被占满,而且模型只见树木不见森林——它不知道同名函数在别处还有一份。

后来改成只给"检索方法",让它自己找:

# 找符号真实定义,排除产物和旧目录
rg -n "export function exportReport|export const exportReport" src/ -g '!dist' -g '!legacy'

# 找一个接口的调用点
rg -n "api/report/export" src/ --type ts

# 看某文件最近谁改过、为什么改
git log --oneline -10 -- src/features/report/

这三条命令贴进对话后,它的定位准确率明显上升。原因是 rg 的输出自带文件路径和行号,模型不需要"猜哪个文件",而且 -g '!dist' 这类排除规则把干扰项直接过滤掉了。

给它的输入 上下文占用 定位准确率(我这边的体感) 适用场景
整段粘贴 4–5 个文件 高,常占满一半 中,容易改到同名副本 单文件小改动
只给检索命令 低 高,路径来自真实搜索结果 跨文件改动、首次接触的模块
先让它输出计划再动手 低 最高,错误在计划阶段暴露 三个文件以上、涉及公共代码

四、先出计划,再动手

这条规则救过我两次。具体做法是在规则文件里要求"三个文件以上先给清单",并在对话里明确说"这一步只给计划,不要改文件"。拿到清单后我只做一件事:看有没有碰到禁区、有没有多出来的文件。多出来的文件通常意味着它理解错了范围。

一个真实例子:我让它"给导出功能加进度提示"。它的第一版计划里有 src/features/report/ExportButton.tsx、src/api/report.ts,还有一个 packages/shared/hooks/useAsync.ts。第三条就是典型的越界——它打算改公共 hook 来加进度回调。我否掉之后,它改成在 ExportButton.tsx 里本地维护状态,改动量从 3 个文件变成 2 个,shared 一行没动。

计划阶段还有一个附带好处:你能提前发现它根本不知道某个约束(比如"导出必须走队列,不能同步下载"),这时候补一句上下文比事后返工便宜得多。

五、验证命令一定是能直接跑的

规则文件里写"记得跑测试"没有用,要写具体命令、具体路径。我踩过一次坑:写了 npm test,它跑了全量测试,四分钟,然后因为三个跟本次改动无关的用例失败而卡住,最后告诉我"测试未通过"。改成按模块跑之后:

# 只跑本次改动相关的用例,30 秒内出结果
npm run test -- --run src/features/report/__tests__

# 类型检查单独跑,报错更精确
npx tsc --noEmit -p tsconfig.app.json 2>&1 | head -40

| head -40 这个小动作也有用:类型错误经常一次上百条,全部塞回上下文会挤掉真正有用的信息,前 40 条基本能定位到根因。

另外建议在规则里写明"如果验证命令失败,把完整报错贴出来,不要自行放宽断言或跳过用例"。不加这句,它会为了让测试变绿去改测试文件——这个行为在评审时看起来很像"修好了"。

六、把需求写成一张任务卡

规则文件管的是"长期约束",单次任务还需要一份"本次约束"。我原来习惯用一两句话打发它——"给导出加个进度提示,谢谢"。这种描述在人和人之间能靠默契补齐,对助手来说是信息缺失,它只能猜三件事:进度怎么显示、失败怎么提示、要不要限制并发。

后来改成固定格式的任务卡,写起来只多两分钟,来回次数少一半:

任务:导出按钮增加进度提示
期望行为:
- 点击导出后按钮进入 loading 态,文案改为"导出中 30%"这类带百分比的
- 进度来自接口返回的 total / processed 两个字段,不做假进度
- 超过 60 秒仍无进展,提示"导出较慢,可稍后在下载中心查看"
涉及文件(已确认,不要扩展):
- src/features/report/ExportButton.tsx
- src/api/report.ts
不要做:
- 不改 packages/shared 下任何文件
- 不新增依赖(进度条复用现有 Progress 组件)
验收:
- npm run test -- --run src/features/report/__tests__
- 手动:把 total 改成 0 试一次,不能出现 NaN%

"不要做"这一栏是整张卡里最有价值的部分。不写它,助手会按"最佳实践"自由发挥:抽一个公共 hook、加一个状态管理、顺手升级一个依赖。这些从代码质量看都不算错,但会让改动范围失控,评审成本从十分钟涨到一小时。

"验收"这一栏也有讲究:要写"能看到结果的检查",而不是"确保正确"。前者是 total=0 时不能出现 NaN,助手会真的去构造这个边界;后者它只会回答"已确保正确处理边界情况"。

一个反例也要记:不要把所有编码规范塞进规则文件。我们仓库有一份 300 行的样式约定,我一度想整份贴进去,结果规则文件变成 400 行,前两周反而更容易越界——它开始把"示例目录"也当成可以改的地方。规则文件的作用是"排除歧义",不是"承载全部知识";真正需要细节的地方,让它去读具体文档更划算。

七、长会话的上下文预算

一个会话持续两小时后,它会开始忘规则:明明写了"不要改 legacy/",到后面还是改了。这不是随机现象,是上下文里早期内容被挤出窗口。

我的处理是三条:一是每个任务开始时开新会话,把当前任务相关的两三个文件路径重新说明一次;二是把长任务的中间结论落到仓库里的 docs/notes/ 文件,下一个会话直接读文件而不是复述;三是规则文件保持短,控制在 60 行以内,太长的规则文件本身就会占掉宝贵的前缀预算。

一个判断标准:如果我发现自己在第三次解释同一件事,就不该再解释了,应该把它写进规则文件。写进去的内容每次会话都自动生效,比在对话里重复有效得多。

小结

  • 编程助手改错文件通常不是能力问题,是仓库没给边界;dist/、legacy/、公共包这三类要先明确冻结。
  • 规则文件写约束(不能改什么、改完跑什么),不要写项目介绍;控制在 60 行以内。
  • 用 rg 检索命令代替整段粘贴,路径来自真实搜索结果,定位更准且省上下文。
  • 三个文件以上的改动先要计划,重点看有没有越界文件;发现越界比事后回滚便宜。
  • 验证命令要具体到模块和路径,并明确禁止"改测试让测试变绿"。
  • 同一件事解释到第三次,就该写进规则文件,而不是继续在对话里重复。
查看「AI 应用」全部文章 →

同分类文章

查看 0 评论 0

评论

正在加载评论…

留言提交后自动审核:正常内容立即显示,含敏感信息的会转人工复核。

AI 编程助手总改错文件:三份规则文件把范围收住 - 起航社区