让 AI 在两天内参与重构两万行 Vue 项目，真正值得关注的并不是“0 行手写代码”，而是如何让生成代码变得可控。核心方法可以概括为三层：用 Skills 注入领域知识，用 AGENTS.md 固化项目规则，再把评审中发现的问题写回约束，让同类错误只出现一次。
这套思路把 AI 从临时问答工具变成了受项目规范约束的执行者。速度来自模型，稳定性则来自人建立的工程系统。
大规模重构为什么不能只靠提示词
一次性的提示词很容易描述目标，却很难覆盖项目中的隐含规则。例如，“把旧页面迁移到新组件库”没有说明：
- 应该使用 Composition API 还是 Options API；
- 状态应该留在组件内，还是进入 Pinia；
- API 错误如何转换成用户提示；
- 哪些旧组件必须替换，哪些兼容层暂时不能动；
- 完成修改后需要执行哪些类型检查和测试。
开发者理解这些上下文，是因为长期工作形成了项目记忆。AI 没有这份记忆，便会在每个任务中重新猜测。猜测一多，生成速度越快，返工规模反而越大。
因此，高质量指令不只是写得更长，而是把信息分层：
| 层级 | 承载内容 | 典型载体 |
|---|---|---|
| 项目级 | 目录边界、技术选型、禁用模式、验证命令 | AGENTS.md |
| 领域级 | Vue 迁移步骤、组件映射、接口约定 | Skills 技能包 |
| 任务级 | 本次修改范围、验收条件、禁止触碰的文件 | 单次任务指令 |
项目规则不必在每次对话里重复，领域流程也不应散落在聊天记录中。单次指令只需要描述这次要完成的增量。
把规范写成 AI 能执行的合同
AGENTS.md 的价值不在于介绍项目，而在于明确决策边界。类似“保持代码优雅”这样的表述无法验证；“组件必须使用 <script setup lang="ts">，提交前运行 npm run typecheck”才是可执行规则。
下面是一套可以这样实践的最小示例。假设项目使用 Vue 3、TypeScript、Pinia 和 Vitest，请根据真实仓库调整目录及命令：
# AGENTS.md
## Scope
- Application code lives under `src/`.
- Do not edit generated files under `src/api/generated/`.
- Keep each change limited to the requested feature.
## Vue conventions
- New and migrated components must use `<script setup lang="ts">`.
- Use `defineProps` and `defineEmits`; do not introduce Options API code.
- Shared server state belongs in an existing Pinia store.
- Do not mutate props.
## Migration rules
- Preserve route paths, query parameters, and emitted event names.
- Replace deprecated `LegacyButton` with `AppButton`.
- Add behavior tests before removing a compatibility wrapper.
## Verification
Run all commands before reporting completion:
```bash
npm run lint
npm run typecheck
npm run test -- --run
npm run build
Report changed files, command results, and any remaining uncertainty.
这份文件需要短、明确、可验证。若规则只适用于某个子目录，可以在该目录放置更具体的说明，避免全局文件膨胀成无人维护的百科全书。
## 用 Skill 封装重复出现的迁移流程
`AGENTS.md` 回答“这个仓库允许怎样写代码”，Skill 则回答“某类任务应该按什么步骤完成”。对于批量 Vue 重构，可以把组件迁移整理成技能包。
不同 AI 编码工具加载 Skill 的方式可能不同。下面采用通用的 Markdown 伪项目结构，重点是内容组织，不把目录名视为某个工具的固定 API：
```text
.ai/
└── skills/
└── migrate-vue-component/
├── SKILL.md
└── component-map.md
AGENTS.md
src/
SKILL.md 可以这样写：
# Migrate Vue Component
## Input
- One legacy component path
- Its direct tests and imported local components
## Procedure
1. Read the component, tests, route entry, and referenced store.
2. Record existing props, events, slots, URL behavior, and loading states.
3. Add or update tests that capture observable behavior.
4. Migrate to Vue 3 `<script setup lang="ts">`.
5. Apply mappings from `component-map.md`.
6. Run focused tests, typecheck, lint, and build.
7. Stop if behavior is ambiguous; report the exact uncertainty.
## Constraints
- Do not rename public props or emitted events without explicit approval.
- Do not modify unrelated components to make checks pass.
- Do not delete compatibility code until its callers are identified.
## Output
- Changed files
- Preserved behavior checklist
- Verification command results
- Risks requiring human review
任务指令于是可以保持紧凑：
使用 migrate-vue-component Skill 迁移 src/views/orders/OrderDetail.vue。
保持路由、props、事件和接口调用行为不变。
只修改该组件、它的直接依赖和测试。
满足 AGENTS.md 中的全部验证要求；若旧行为无法确定，停止并列出证据，不要猜测。
这里最重要的一句往往是“无法确定时停止”。AI 擅长补全缺口，但大规模重构中，未经证实的补全可能悄悄改变业务行为。
建立“错误只犯一次”的飞轮
约束体系不是一次写完的。更现实的过程是：AI 执行任务，测试或评审发现错误，人判断错误是否具有重复性，再把结论写回规范。
例如，第一次迁移后发现分页参数从 pageIndex 被改成了 page。只修当前文件还不够；如果其他页面也采用相同协议，就应把规则加入 Skill：
## API invariants
- Preserve request field `pageIndex`; never rename it to `page`.
- Preserve zero-based pagination unless the endpoint contract says otherwise.
随后用仓库命令检查这个约束是否被破坏。下面的脚本可直接改造为 scripts/check-migration.sh，运行前把目录和组件名替换成项目实际值：
#!/usr/bin/env bash
set -euo pipefail
npm run lint
npm run typecheck
npm run test -- --run
if rg -n "LegacyButton|page: currentPage" src/views/orders; then
echo "Migration check failed: deprecated component or pagination mapping found." >&2
exit 1
fi
npm run build
echo "Migration checks passed."
人工经验因此逐步转化为三类资产：文字规则负责指导生成，测试负责验证行为，静态检查负责拦截已知反模式。只有文字而没有自动检查，规则仍可能被忽略；只有检查而没有规则，AI 会反复生成同一种错误，再等待流水线拒绝。
“0 行手写代码”不等于“0 人工工程”
即使代码全部由 AI 生成，人仍然需要承担架构和验收责任：选择重构边界、定义不可变行为、补齐测试基线、处理冲突，并判断生成结果是否值得合入。“没有亲手敲代码”描述的是输入方式，不代表工作量、责任或风险消失。
采用这套方法时，可以用以下清单控制节奏：
- 先挑一个依赖少、测试较完整的垂直切片验证流程；
- 将规范写成可判断的动作和禁止项，删除模糊形容词；
- 每个任务限制文件范围，并要求报告超出范围的需求；
- 把路由、接口字段、事件和视觉交互列为显式验收项；
- 每次评审后只沉淀可复用规则，避免记录偶然细节；
- 保留类型检查、单元测试、构建和人工评审这几道门槛；
- 分批合入，确保每一批都能独立回滚。
AI 可以显著提高代码变更吞吐量，但吞吐量并不是重构成功的标准。真正可靠的系统，是把项目知识放在明确位置，把任务拆成可验证步骤，并让每次失败都为下一次执行增加一道护栏。