前端项目的 AI 改造：把团队经验接入 Skill、Agent 与 Spec 工作流

AI 改造不是在项目里增加一个聊天窗口，而是让团队已有的知识、规范和验证方式能够被 Agent 稳定理解并重复执行。最可靠的路径，是从工程目录、任务流程和交付证据开始渐进接入。

为什么要改造已有前端项目

很多项目已经拥有成熟的代码、组件和发布流程，却依然无法稳定使用 AI。原因通常不是模型不够聪明，而是项目的规则散落在聊天记录、个人习惯、旧文档和 Review 意见里。Agent 看到的是代码，却看不到团队为什么这样做。

AI 改造的目标，是把这些隐含经验转成机器和人都能读取的工程约定：哪些目录可以修改，页面必须遵循什么路由规则，完成后要执行哪些检查，哪些操作必须等待人工确认。

已有项目
   ↓
整理规范与上下文
   ↓
接入团队 Skill + Agent 文档
   ↓
用 Superpowers / Spec 组织任务
   ↓
通过 CI、Review 和发布流程验证

第一层：在根目录建立 Agent 工作说明

根目录的 Agent 文档不应该是一份大而全的百科，而应该是 Agent 每次进入项目都需要知道的最小规则。它可以包括：

• 项目的启动、检查、构建和测试命令
• 目录职责与不可随意修改的区域
• 路由、状态、国际化和组件使用规范
• 修改代码前需要读取的文档
• 触发外部写入、删除、发布时的确认要求
• 交付时必须汇报的文件、命令和风险

# Agent 工作约定

## 开始任务前
- 先读取本文件和相关模块文档
- 先确认工作区状态，不主动拉取或覆盖用户改动

## 完成任务前
- 运行类型检查、测试、Lint 和构建
- 汇报实际修改文件、验证命令和未解决风险

## 高风险操作
- 删除、发布、推送和修改远程配置必须得到明确确认

它的价值不在于限制 Agent，而在于让协作边界透明。人换了、模型换了，项目依然有一份稳定的入口说明。

第二层：引入团队 Skill 仓库

团队 Skill 仓库用于沉淀可复用的方法，不应该存放业务密钥、用户数据或某个项目的私有内容。一个适合前端团队的 Skill 仓库可以按任务组织：

team-skills/
├── create-page/
├── review-component/
├── verify-release/
├── migrate-legacy-route/
└── README.md

每个 Skill 都应该有明确的触发条件、输入、执行步骤、禁止事项和完成标准：

# create-page

## 适用场景
新增一个遵循团队导航和 UI 规范的页面。

## 必须检查
- 菜单 Code 与 URL 层级一致
- 国际化 Key 完整
- 加载、空数据、错误和无权限状态齐全
- 类型检查、测试和生产构建通过

## 输出
变更摘要、验证结果、截图和剩余风险。

团队可以通过 Skill 仓库同步工具或类似 skillshare 的机制，在多个前端项目之间分发经过评审的能力。同步时应保留版本信息和来源，避免一个项目的临时修改悄悄污染所有项目。

Skill、MCP 与 Agent 文档如何分工

三者解决的问题不同：

Agent 文档：这个项目有哪些规则？
Skill：完成这类任务应该遵循什么方法？
MCP：Agent 可以通过什么协议读取或调用外部能力？

例如，Agent 文档规定“所有页面必须执行 pnpm check”；Skill 规定新增页面的完整步骤；MCP 则可以让 Agent 查询真实菜单树或读取接口契约。分工清楚后，项目不会把所有信息都塞进一份越来越长的 Prompt。

第三层：用 Superpowers 组织任务阶段

在已有项目中引入 AI，建议把任务拆成几个稳定阶段，而不是让 Agent 从一句需求直接修改大量文件：

1. 理解：读取项目规则、相关模块和现有实现。
2. Brainstorm：澄清目标、边界、替代方案和风险。
3. Spec：记录选定方案、数据结构、状态和验收标准。
4. Plan：拆成可独立验证的小步骤。
5. Implement：一次只完成当前步骤，并保持改动可审阅。
6. Verify：运行检查、测试、构建和场景回归。
7. Review：总结结果、风险和后续工作。

这类 Superpowers 流程的重点不是某个工具名称，而是让任务过程可暂停、可审阅、可恢复。需求发生变化时，先更新 Spec 和计划，再继续编码。

Spec 应该写到什么程度

Spec 不需要预测每一行实现，但要覆盖会影响验收的事实：

## 需求
在设置门户增加一个批量导出页面。

## 约束
- 沿用现有菜单和权限协议
- 不改变默认门户布局
- 导出操作需要二次确认
- 移动端使用可滚动表格

## 验收
- 有加载、空数据、失败和无权限状态
- 刷新深层 URL 可以恢复
- 导出失败可以重试
- 通过 typecheck、test、build

有了这些内容，Agent 的实现就能被逐条检查；没有通过的条目不会被一句“代码已经完成”掩盖。

第四层：把 AI 接入验证，而不是直接接入发布

AI 可以参与代码生成和检查，但发布权限应该仍然由 CI 和人工审批控制。前端项目至少可以把以下命令纳入统一门禁：

pnpm typecheck
pnpm test
pnpm lint
pnpm format:check
pnpm audit:unused
pnpm build

Agent 可以根据失败日志继续修复，但每次自动修复都应产生可审阅的 diff。涉及依赖升级、权限修改、敏感配置、删除文件和生产发布时，必须停下来请求人工确认。

一个适合旧项目的渐进路线

不建议一次性重构整个前端项目，可以分四步：

第一步：只读接入

增加根目录 Agent 文档和团队 Skill，不开放自动写入。先观察 Agent 是否能正确理解项目。

第二步：局部任务

开放文档、测试、类型修复和小型组件任务，要求每次提供验证命令和结果。

第三步：模块级改造

将路由、菜单、UI 组件和接口契约整理为 Spec，允许 Agent 在明确边界内跨文件修改。

第四步：流水线协作

把代码审查、依赖审计、构建产物和变更说明接入 CI；发布仍由保护分支、审批和凭证策略控制。

小结

前端项目的 AI 改造，本质上是一次知识和流程治理。团队 Skill 仓库负责复用方法，根目录 Agent 文档负责项目边界，Superpowers 负责协作节奏，Spec 负责实现与验收，CI 负责把结果变成证据。

当这些环节连接起来后，AI 才能从一个偶尔提供建议的工具，变成遵循团队规则、能够持续改进、但仍然处于人类控制之下的工程伙伴。