AI 时代，前端工程化要重做一遍

这两年前端圈有个挺微妙的变化。

以前我们讨论工程化，聊的是：

monorepo 怎么拆；
组件库怎么治理；
CI 怎么提速；
ESLint 怎么统一；
E2E 测试怎么不 flaky；
设计系统怎么落地；
构建产物怎么优化。

现在一提 AI，很多讨论突然变成了：

哪个 Coding Agent 最强；
Cursor、Claude Code、Codex CLI 哪个好用；
prompt 怎么写；
怎么让 AI 一次生成整个页面；
前端是不是要被替代。

这两个讨论之间，好像断了一层。

可真正进过复杂业务项目的人都知道：

AI 写 demo 的能力，和它能稳定改一个真实前端仓库，是两回事。

一个干净的新项目，AI 很容易表现得像个资深工程师。

一个跑了三年的业务项目，AI 进去之后经常像个新来的实习生：

不知道哪些组件是团队封装过的；
不知道哪个 API 不能直接调；
不知道哪些目录是生成代码；
不知道哪些样式 token 不能绕过；
不知道为什么这里必须用 Server Component，那里必须用 Client Component；
不知道测试选择器为什么不能随手写 nth-child；
不知道这个包能不能装，装了之后谁来背锅。

于是很多人得出一个结论：

AI 还不够聪明。

这个判断不算错，但只说对了一半。

更准确地说是：

我们过去的前端项目，大多只为"人类开发者"设计，没有为"机器协作者"设计。

这会倒逼前端工程化重构。

不是重构成"AI 写代码，人类点确认"的流程。

而是重构成一个更清晰、更可验证、更可审计、更不依赖口口相传的工程系统。

这篇文章想聊的就是这个问题：

AI 时代，前端工程化到底该怎么重构？

一、问题不在"AI 会不会写代码"，而在"项目有没有把知识显式化"

前端项目里有大量知识，并不在代码本身。

比如一个业务组件：

tsx 复制代码

<OrderSubmitButton />

代码里也许只写了一个按钮。

但团队里的老同学知道：

这个按钮只能在订单确认页使用；
点击前必须校验库存；
有些业务线不能走新接口；
埋点字段不能改；
按钮 loading 状态必须和支付状态绑定；
失败时不能简单 toast，要进入人工兜底流程。

这些知识在哪里？

很多时候在：

老员工脑子里；
飞书历史消息里；
某个过期文档里；
PR 讨论里；
线上事故复盘里；
"大家都知道"的团队习惯里。

人类新人都不一定知道，AI 更不可能知道。

所以 AI 在真实项目里最常见的问题不是"不会 React"，而是：

它不知道你的项目为什么长成现在这样。

过去工程化解决的是"人协作人"的问题。

现在工程化还要解决"人协作机器"的问题。

这会改变前端工程化的核心目标。

以前我们追求：

txt 复制代码

让人更容易开发、测试、构建、发布

现在还要加上：

txt 复制代码

让机器更容易理解、修改、验证、回滚

这不是概念游戏。

它会实实在在影响目录结构、文档方式、组件设计、测试策略、CI 门禁和安全边界。

二、社区已经在吵了：到底是模型不行，还是项目不给上下文？

在社区里，类似争论已经出现很多次。

有 Next.js 开发者讨论过怎么给 AI coding assistant 提供项目上下文。有人觉得只要工具够强，它会自动理解整个 workspace；也有人指出，靠助手自己"猜"上下文并不可靠，文档会过期，记忆也会过期，最后还是要把项目约定明确写下来。这个讨论本质上不是 Next.js 专属，而是所有复杂前端项目都会遇到的问题。参考 Reddit 上关于 Next.js 项目上下文的讨论：

www.reddit.com/r/nextjs/co...

Playwright 社区也有类似争论。很多人吐槽 AI 生成测试时喜欢写：

ts 复制代码

page.locator('div:nth-child(8)').click()

或者：

ts 复制代码

page.getByRole('button', { name: 'Add to Cart' }).nth(8)

为什么？

不是因为 AI 不懂测试，而是页面本身没有稳定语义。组件外面套了一堆 div，按钮没有清楚的 accessible name，业务动作没有稳定的测试标识，AI 只能从 DOM 结构里"捞"一个看起来能点的元素。

有开发者专门讨论过 AI agent 为什么会写 nth(8) 或父级遍历选择器，并指出问题经常出在非语义化组件结构上：

www.reddit.com/r/Playwrigh...

Playwright 官方文档也一直强调 locator 的稳定性，推荐优先使用基于 role、label、文本、test id 等用户可感知或稳定语义的定位方式，而不是脆弱的 CSS 路径。

参考 Playwright Locator 文档：

playwright.dev/docs/api/cl...

这些争论背后是同一个问题：

AI 只是把项目里原本模糊、隐性、不稳定的部分放大了。

你不给人清晰的工程边界，人会靠经验补。

你不给 AI 清晰的工程边界，它只能猜。

猜对一次，不代表它理解了系统。

猜错一次，可能就是一个线上事故。

三、AI 时代的前端工程化，不是"自动化"，而是"可理解性工程"

我觉得接下来前端工程化会从传统的几件事：

规范；
构建；
测试；
发布；
监控；

扩展到一个新的核心能力：

可理解性工程。

什么叫可理解性？

不是文档写得多。

而是项目里的关键知识，能不能被人和机器用同一种方式稳定获取。

一个项目是否可理解，可以问几个问题：

新同学进来，能不能知道哪些目录能改、哪些不能改？
AI Agent 进来，能不能知道组件库应该怎么用？
测试工具能不能通过语义找到按钮，而不是靠 DOM 层级？
CI 能不能判断一次依赖变更是否高风险？
Code Review 能不能区分确定性问题和经验性建议？
线上出错后，Agent 能不能拿到足够上下文定位问题？
业务规则有没有沉淀成稳定入口，而不是散落在聊天记录里？

如果答案是否定的，那不是 AI 的问题。

这是工程系统自己的问题。

AI 到来之后，这个问题变得更急了。

四、第一层重构：项目入口文档要从 README 走向 AGENTS.md

很多项目都有 README，但 README 通常是写给人看的：

md 复制代码

如何安装
如何启动
如何构建
如何部署

这还不够。

AI Agent 进入项目时，最需要的不是"这个项目怎么启动"，而是：

这个项目的技术边界是什么；
哪些模式是推荐的；
哪些模式是禁止的；
常见任务应该怎么做；
失败后应该先看哪里；
哪些文件不能碰；
修改完成后必须跑哪些检查。

所以我建议前端项目增加一个明确的入口文档：

txt 复制代码

AGENTS.md

它不是给老板看的愿景文档，也不是给新人看的长篇教程。

它应该像一份"项目操作说明书"。

例如：

md 复制代码

# AGENTS.md

## 项目简介

这是一个面向订单和支付场景的 Next.js 项目，使用 App Router。
项目包含服务端渲染页面、客户端交互组件、BFF API 调用封装和 Playwright E2E 测试。

## 技术栈

- Next.js
- React
- TypeScript
- pnpm
- Tailwind CSS
- Playwright
- Vitest

## 目录约定

- `src/app`：路由和页面入口
- `src/components`：通用组件
- `src/features`：业务模块
- `src/lib/api`：所有 API 调用封装
- `src/generated`：自动生成代码，禁止手动修改
- `tests/e2e`：端到端测试

## 编码规则

- 默认使用 Server Component
- 只有需要浏览器交互、状态或事件监听时才使用 Client Component
- 不允许在组件中直接请求外部接口，必须经过 `src/lib/api`
- 不允许直接写颜色值，必须使用设计 token
- 不允许绕过权限判断逻辑
- 新增页面必须补充基本 E2E 测试

## 组件使用规则

- 表单统一使用 `AppForm`
- 弹窗统一使用 `AppModal`
- 主按钮使用 `Button variant="primary"`
- 危险操作必须使用 `ConfirmDialog`
- 金额展示必须使用 `MoneyText`

## 测试规则

- 优先使用 `getByRole`
- 复杂业务元素允许使用 `data-testid`
- 禁止使用 `nth-child`、动态 class、深层 CSS selector
- 新增核心流程必须补充 Playwright 测试

## 常用命令

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm test:e2e
pnpm build

禁止事项

不要修改 src/generated
不要移除鉴权中间件
不要直接改全局样式
不要引入未解释理由的新依赖
不要为了修测试而降低断言质量

yaml 复制代码

这份文档看起来很朴素，但它的价值很大。

它把团队里的隐性知识变成显性知识。  
人可以读，AI 也可以读。  
新人可以读，CI bot 也可以读。  
Code Review 时还能拿它做依据。

这就是 AI 时代工程化的第一个变化：

> 文档不再只是知识库，而是工程系统的一部分。

---

## 五、第二层重构：组件库文档不能只写 API，要写"什么时候用"和"什么时候不用"

很多组件库文档长这样：

```md
Button

Props:
- type
- size
- disabled
- loading

这对人类开发者勉强够用，对 AI Agent 不够。

因为 AI 最容易犯的错误不是 prop 写错，而是场景用错。

比如：

该用业务封装的 UserSelect，它用了基础 Select；
该用带权限的 AuthButton，它用了普通 Button；
该用统一表单容器，它自己拼了一套；
该走设计 token，它直接写 hex；
该有确认弹窗，它只写了 window.confirm。

组件库文档要重写一遍。

不是变得更长，而是变得更有判断力。

一个面向 AI 协作的组件文档，至少要包含：

md 复制代码

# AppModal

## 用途

用于业务弹窗，包括确认、编辑、详情查看等场景。

## 适合使用

- 用户需要在当前页面完成短流程操作
- 表单字段不超过 8 个
- 操作完成后回到当前上下文

## 不适合使用

- 长流程向导
- 多步骤支付流程
- 需要独立 URL 分享的页面
- 大量表格内容展示

## 必须遵守

- 危险操作必须配合 ConfirmDialog
- 弹窗内表单必须支持 ESC 关闭前确认
- 提交按钮必须有 loading 状态
- 异步错误必须展示在弹窗内，而不是只 toast

## 示例

正确示例：
...

错误示例：
...

## 测试建议

- 弹窗标题使用 role="dialog" accessible name
- 主按钮使用明确文本
- 关键容器添加 data-testid

这类文档一开始看起来像"啰嗦"。

但当 AI 参与开发之后，它会变成上下文燃料。

过去组件库文档回答的是：

这个组件怎么用？

现在还要回答：

什么时候不该用？用了之后必须满足哪些业务约束？

这会直接影响 AI 生成代码的质量。

六、第三层重构：测试不是"防 AI 写错"，而是给 AI 一个反馈回路

很多人对 AI 生成代码的期待是：

一次写对。

这个期待不现实。

更现实的工程目标是：

它可以写错，但必须能快速得到反馈、修正，并且不能把错误带出边界。

这就要求测试体系变成 AI 协作的反馈回路。

传统测试对人类开发者来说，是质量保障。

对 AI Agent 来说，测试还是"环境反馈"。

如果项目没有测试，AI 改完代码以后只能靠语言自信。

如果项目有稳定测试，AI 至少能知道：

类型有没有错；
lint 有没有过；
单测有没有挂；
E2E 流程有没有断；
构建有没有失败。

但这里有个坑：

测试本身也要足够稳定，否则 AI 会学会绕测试。

如果 E2E 测试里到处是：

ts 复制代码

page.locator('.css-1abcxyz').click()
page.locator('div > div > div:nth-child(3)').click()
page.waitForTimeout(3000)

AI 修失败测试时，大概率会继续堆 timeout、改 selector、降低断言。

所以 AI 时代的前端测试要调整重点：

1. 选择器要语义化

优先：

ts 复制代码

page.getByRole('button', { name: '提交订单' })
page.getByLabel('手机号')
page.getByTestId('order-submit-button')

少用：

ts 复制代码

page.locator('.btn-primary')
page.locator('div:nth-child(4)')

这不是洁癖。

这是让测试工具和 AI 都能理解页面。

2. 断言要表达业务意图

不要只断言"出现了一个 div"。

更好的断言是：

ts 复制代码

await expect(page.getByText('订单提交成功')).toBeVisible()
await expect(page.getByRole('button', { name: '继续支付' })).toBeEnabled()

测试的语义越明确，AI 越不容易为了过测试而乱改。

3. 测试失败信息要可读

一个好的测试失败信息，应该让人和 AI 都能定位问题。

例如：

ts 复制代码

await expect(submitButton, '库存不足时提交按钮应该禁用').toBeDisabled()

比一个裸断言更好。

4. 不要把 flaky 当成小问题

flaky 测试在 AI 协作里伤害更大。

因为 AI 可能会把偶发失败理解成真实失败，然后做出错误修改。

社区里关于 Playwright flaky selector 的讨论非常多，有人认为 role-based locator 能显著减少结构变更导致的测试脆弱，也有人提醒它并不是银弹，运行时状态、hydration、异步事件绑定同样会导致 flaky。这个争论很有价值：测试稳定性不是换一个 API 就结束了，而是页面语义、异步状态和断言策略一起治理。

参考讨论：

www.reddit.com/r/Playwrigh...

七、第四层重构：MCP 会让"前端上下文"从文档变成可调用能力

如果说 AGENTS.md 解决的是静态上下文，MCP 解决的是动态上下文。

MCP，也就是 Model Context Protocol，本质上是让模型通过统一协议访问外部工具、资源和提示模板。官方文档里把 MCP server 的能力分为 tools、resources、prompts 等：tools 用来执行动作，resources 用来暴露上下文数据，prompts 用来提供可复用任务模板。

参考 MCP 官方文档：

modelcontextprotocol.io/docs/learn/...

这对前端团队的意义很大。

因为前端项目里很多上下文不是静态文档能表达的。

比如：

当前 dev server 有没有编译错误；
当前页面路由是什么；
浏览器控制台有什么 runtime error；
当前组件库有哪些组件；
某个设计 token 是否存在；
当前接口 mock 数据是什么；
页面可访问性树是什么；
Playwright 当前能看到哪些元素；
某个业务 API 的 schema 是什么。

这些东西如果只靠 AI 自己读代码，很容易猜错。

如果通过 MCP 暴露成结构化能力，它就能少猜很多。

Next.js 已经在这方面往前走了。Next.js MCP Server 允许 coding agent 连接运行中的 Next.js 实例，读取应用相关上下文、错误信息等。参考 Next.js MCP Server 文档：

nextjs.org/docs/app/gu...

这给前端工程化一个很强的信号：

未来优秀的前端框架和前端项目，不只提供给浏览器运行的接口，也会提供给 Agent 理解项目的接口。

前端团队可以从很小的地方开始做自己的 MCP 能力。

例如做一个 Design System MCP：

txt 复制代码

resource: design-tokens
返回当前可用颜色、间距、字体、圆角 token

resource: component-catalog
返回组件库列表、使用规则、禁止用法

tool: find-component-usage
查询某个组件在哪些页面使用

tool: validate-design-token
检查代码里是否使用了不存在的 token

prompt: create-form-page
提供创建表单页面的固定流程和约束

再比如做一个 Frontend Project MCP：

txt 复制代码

tool: get-routes
返回项目路由表

tool: get-runtime-errors
返回当前 dev server 和浏览器错误

tool: search-api-contract
查询业务 API schema

tool: run-quality-check
执行 lint/typecheck/test 并返回结构化结果

resource: project-rules
返回项目工程规则

这不是为了炫技。

它解决的是一个很实际的问题：

不要让 AI 在复杂项目里靠猜上下文。

八、第五层重构：依赖治理要默认假设"AI 也会 npm install"

前端供应链安全过去已经够复杂了。

现在多了一个新变量：AI Agent。

以前装包的人是开发者。

至少人知道自己为什么装。

现在很多工作流里，AI 可能会主动建议：

bash 复制代码

pnpm add xxx

甚至在某些工具里直接执行。

这会带来新问题：

它会不会选择低质量依赖？
它会不会安装维护状态很差的包？
它会不会忽略 lockfile diff？
它会不会被 README、issue、prompt 影响？
它会不会为了完成任务引入一个大而全的库？
它会不会执行带有风险的 install script？
它会不会为了省事绕过已有工具函数？

所以 AI 时代的依赖治理要升级。

不是简单地说"不准 AI 装包"。

这不现实。

更合理的是建立依赖变更协议。

例如：

md 复制代码

# Dependency Change Policy

任何新增依赖必须说明：

1. 为什么需要新增依赖？
2. 项目内是否已有替代方案？
3. 是否可以用原生 API 或已有工具实现？
4. 包的维护状态如何？
5. 最近发布时间是否异常？
6. 是否包含 install/postinstall script？
7. bundle size 影响是多少？
8. license 是否可接受？
9. lockfile diff 是否符合预期？
10. 是否通过安全扫描？

对应 CI 可以做一些硬门禁：

新增依赖必须触发额外检查；
lockfile diff 必须被标记；
禁止未知 registry；
禁止生命周期脚本或要求人工确认；
高风险包要求 owner review；
自动跑 OSV / npm audit / Socket / Snyk 类扫描；
大体积依赖要求 bundle size 说明。

这类治理以前也该做。

只是 AI 让它变得更紧急。

因为 AI 的一个特点是：

它很擅长给出"看起来合理"的理由。

如果没有制度化检查，人很容易被说服。

九、第六层重构：Code Review 要从"看代码"变成"看证据链"

AI 参与开发后，Code Review 的重点也会变。

过去 Review 主要看：

代码风格；
逻辑正确性；
是否符合业务；
是否有测试；
是否影响性能。

现在还要看：

这段代码是基于什么上下文生成的；
AI 是否修改了不该改的文件；
是否引入新依赖；
是否绕过已有抽象；
是否删除了看似无用但实际有业务意义的代码；
是否补了测试；
测试是不是为了过而过；
是否有运行结果；
是否有回滚方案。

我建议 AI 参与的 PR，增加一个非常简单的模板：

md 复制代码

## 变更目的

说明本次改动解决什么问题。

## 修改范围

列出主要修改文件和模块。

## AI 参与情况

- 是否使用 AI 辅助：是 / 否
- AI 主要参与：生成代码 / 重构 / 测试 / 文档 / 排查问题
- 人工确认过的关键点：

## 验证结果

- [ ] pnpm lint
- [ ] pnpm typecheck
- [ ] pnpm test
- [ ] pnpm test:e2e
- [ ] pnpm build

## 风险点

- 是否新增依赖：
- 是否修改鉴权：
- 是否修改支付 / 订单 / 权限核心流程：
- 是否修改 generated 文件：
- 是否影响埋点：

## 回滚方式

说明如何回滚，是否有配置开关。

这不是形式主义。

AI 时代的 Review 不能只看 diff。

还要看"这次修改是否有足够证据证明它是安全的"。

这就是从代码审查走向证据链审查。

十、第七层重构：前端可观测性要覆盖 AI 交互链路

如果你的产品里已经有 AI 功能，传统前端监控也不够了。

以前监控：

JS error；
API latency；
LCP；
CLS；
route change；
click；
blank screen。

AI 功能上线后，还要监控：

first token latency；
streaming 中断率；
用户取消率；
retry 次数；
tool call 成功率；
fallback 率；
用户复制率；
用户二次编辑率；
生成结果被撤销的比例；
敏感内容拦截次数；
模型错误类型；
前端渲染 partial response 的耗时；
用户是否在等待期间离开页面。

这不是后端或算法团队的事。

很多指标发生在前端交互层。

例如：

用户点了"生成报告"，等了 12 秒，然后关掉弹窗。

后端也许觉得请求成功了。

但前端应该知道：这个体验失败了。

再比如：

模型流式返回很快，但前端渲染策略不好，每次 token 都触发大组件重渲染。

用户看到的还是卡顿。

所以 AI 产品里的前端工程化，要把"生成体验"也纳入可观测性。

一个最小可落地的埋点可以是：

ts 复制代码

type AiInteractionEvent = {
  traceId: string
  feature: string
  action:
    | 'submit'
    | 'first_token'
    | 'stream_end'
    | 'abort'
    | 'retry'
    | 'fallback'
    | 'copy'
    | 'edit'
    | 'regenerate'
    | 'error'
  duration?: number
  errorType?: string
  model?: string
  toolName?: string
}

不一定一开始就做很复杂。

但至少要知道 AI 功能到底有没有被顺利用完。

十一、前端团队可以马上落地的 12 件事

说了这么多，最后还是要落地。

如果你是前端负责人，或者正在维护一个复杂业务项目，可以从下面 12 件事开始。

1. 给项目加 `AGENTS.md`

先不要追求完美。

把以下内容写清楚：

技术栈；
目录结构；
常用命令；
组件使用规范；
API 调用规范；
测试规范；
禁止修改区域；
新增依赖规则；
必须验证的命令。

2. 给组件库补"使用场景"和"禁止用法"

不要只写 props。

重点写：

什么时候用；
什么时候不用；
常见错误；
业务约束；
测试建议；
可访问性要求。

3. 治理测试选择器

把高频业务流程里的脆弱 selector 改掉。

优先治理：

登录；
下单；
支付；
权限；
核心表单；
核心列表操作。

4. 建立 AI 生成测试规范

明确告诉 AI：

优先 getByRole；
允许稳定 data-testid；
禁止 nth-child；
禁止裸 waitForTimeout；
断言必须表达业务语义。

5. 新增依赖必须有理由

只要 PR 里改了 package.json 或 lockfile，就要求说明：

为什么加；
替代方案；
安全检查；
bundle 影响；
是否有 install script。

6. CI 标记敏感变更

自动识别：

鉴权逻辑变更；
支付逻辑变更；
权限逻辑变更；
新增依赖；
删除测试；
修改 generated；
修改全局样式；
修改构建配置。

这些 PR 要求更严格 Review。

7. 给 AI PR 加 Review 模板

不需要很重。

但要让作者说明：

AI 做了什么；
人工确认了什么；
跑了哪些验证；
风险点是什么。

8. 把项目约定放进仓库，而不是放进聊天记录

聊天记录不是工程资产。

仓库里的文档、规则、测试、脚本才是。

9. 把常见错误变成 lint 或测试

如果一个问题出现三次，就不要再靠口头提醒。

把它变成：

ESLint rule；
TypeScript 类型；
单元测试；
E2E 测试；
CI 检查；
codemod；
PR bot 提醒。

10. 为核心业务流程建立可观测性

至少知道：

用户有没有完成流程；
哪一步失败；
是接口慢、前端卡，还是生成慢；
用户有没有取消；
有没有反复重试。

11. 小范围尝试 MCP

不用一上来做平台。

可以先做一个最小 MCP server，只暴露：

项目规则；
组件列表；
路由表；
设计 token；
当前错误；
常用命令执行结果。

12. 定期清理"AI 容易误读"的工程角落

比如：

命名混乱的组件；
过期文档；
多套 API 封装；
重复业务逻辑；
无语义 DOM；
过时测试；
不明用途的工具函数；
无 owner 的核心模块。

这些地方人类也会误读，只是 AI 会更快踩坑。

十二、一个可以直接使用的 Frontend AI-Ready Checklist

下面这份清单可以直接放进团队文档。

md 复制代码

# Frontend AI-Ready Checklist

## 项目上下文

- [ ] 是否有 AGENTS.md？
- [ ] 是否说明技术栈和框架版本？
- [ ] 是否说明目录结构？
- [ ] 是否说明哪些目录禁止修改？
- [ ] 是否说明常用命令？
- [ ] 是否说明业务边界？

## 组件与设计系统

- [ ] 组件文档是否包含适用场景？
- [ ] 是否包含不适用场景？
- [ ] 是否包含错误示例？
- [ ] 是否说明设计 token 使用规则？
- [ ] 是否说明可访问性要求？
- [ ] 是否说明测试选择器建议？

## 测试

- [ ] E2E 是否优先使用语义化 locator？
- [ ] 是否避免 nth-child 和动态 class？
- [ ] 核心流程是否有测试覆盖？
- [ ] 测试失败信息是否可读？
- [ ] 是否治理 flaky 测试？
- [ ] AI 生成测试是否有规范？

## 依赖治理

- [ ] 新增依赖是否需要说明理由？
- [ ] 是否检查 lockfile diff？
- [ ] 是否扫描安全风险？
- [ ] 是否检查 install script？
- [ ] 是否评估 bundle size？
- [ ] 是否有依赖白名单或高风险提示？

## Code Review

- [ ] AI 参与的 PR 是否标记？
- [ ] 是否说明验证结果？
- [ ] 是否标记敏感变更？
- [ ] 是否有人类 owner 确认？
- [ ] 是否有回滚方案？

## 可观测性

- [ ] 是否监控关键用户流程？
- [ ] AI 功能是否监控 first token latency？
- [ ] 是否记录 abort / retry / fallback？
- [ ] 是否能关联前端 trace 和后端请求？
- [ ] 是否能定位生成体验失败点？

## Agent / MCP

- [ ] 是否有机器可读项目规则？
- [ ] 是否暴露组件库上下文？
- [ ] 是否暴露路由和 API contract？
- [ ] 是否能读取运行时错误？
- [ ] 是否限制工具权限？

这份清单不是为了追求形式。

它的作用是让团队知道：哪些地方一旦不清楚，AI 就会靠猜。

十三、几个可能引起争论的观点

最后，我想留几个观点。

它们未必都对，但值得讨论。

观点一：AI 不会消灭前端工程化，它会教育工程化差的团队

很多人说 AI 会让工程化不重要。

我反而觉得相反。

项目越混乱，AI 越容易放大混乱。

项目越清晰，AI 越容易成为生产力。

AI 更像压力测试。

它会把你项目里那些本来就存在的问题暴露出来：

文档过期；
组件边界混乱；
测试脆弱；
依赖治理缺失；
业务规则靠人脑；
CI 门禁形同虚设。

这些不是 AI 带来的问题。

AI 只是让它们更快爆出来。

观点二：未来高级前端的一部分工作，是设计"机器可理解的工程系统"

过去高级前端负责：

架构；
性能；
工程效率；
组件体系；
质量保障。

以后还要负责：

项目上下文如何组织；
Agent 能访问哪些信息；
Agent 不能做什么；
什么知识要写进规则；
什么错误要变成自动检查；
什么变更必须人工确认。

这不是 prompt engineer。

这是工程系统设计。

观点三：最好的 AI 协作不是让它自由发挥，而是让它在边界内高效工作

很多失败的 AI Coding 实践，问题都出在"自由度太高"。

让 AI 随便扫仓库、随便改文件、随便装包、随便跑命令，然后期待它稳，这不现实。

更靠谱的方式是：

txt 复制代码

明确任务
明确上下文
明确边界
明确验证方式
明确失败后的处理

这其实就是工程化。

观点四：面向 AI 的文档，最终会反过来改善人类协作

AGENTS.md 不是只给 AI 用。

组件禁止用法不是只给 AI 看。

测试语义化也不是只为了 AI。

这些东西最终都会让新人更快上手，让 Review 更有依据，让事故更少，让项目更容易维护。

也就是说：

为 AI 补的工程化债，最后会还给整个团队。

十四、结语：前端工程化的下一步，是把"经验"变成"系统"

过去很多前端团队靠经验运转。

老同学知道哪些坑不能踩。

Tech Lead 知道哪些代码不能乱动。

组件库维护者知道哪些组件不能滥用。

测试负责人知道哪些 selector 会炸。

安全同学知道哪些包不能随便装。

但 AI 不知道。

新人也不知道。

跨团队协作的人也不知道。

所以 AI 时代真正要做的，不是简单地"让 AI 写更多代码"。

而是把这些经验沉淀成系统：

写进文档；
写进组件规范；
写进测试；
写进 lint；
写进 CI；
写进 PR 模板；
写进依赖治理；
写进可观测性；
写进 MCP 工具；
写进项目的每一次反馈回路。

这才是前端工程化的重构方向。

不是从"人写代码"走向"AI 写代码"。

而是从"靠人记住规则"走向"系统显式表达规则"。

如果一个项目只有熟人才能改，那 AI 改不好很正常。

如果一个项目新人也能快速理解，测试能稳定反馈，CI 能守住边界，文档能说明上下文，组件能表达语义，那么 AI 也会更容易成为帮手，而不是风险源。

所以我更愿意把这场变化总结成一句话：

AI 时代，前端工程化的核心不是自动生成代码，而是让复杂项目变得可理解、可验证、可审计、可安全修改。

这件事不炫酷。

但它会决定 AI 到底是团队的加速器，还是事故制造机。

AI 时代，前端工程化要重做一遍

一、问题不在"AI 会不会写代码"，而在"项目有没有把知识显式化"

二、社区已经在吵了：到底是模型不行，还是项目不给上下文？

三、AI 时代的前端工程化，不是"自动化"，而是"可理解性工程"

四、第一层重构：项目入口文档要从 README 走向 AGENTS.md

禁止事项

六、第三层重构：测试不是"防 AI 写错"，而是给 AI 一个反馈回路

1. 选择器要语义化

2. 断言要表达业务意图

3. 测试失败信息要可读

4. 不要把 flaky 当成小问题

七、第四层重构：MCP 会让"前端上下文"从文档变成可调用能力

八、第五层重构：依赖治理要默认假设"AI 也会 npm install"

九、第六层重构：Code Review 要从"看代码"变成"看证据链"

十、第七层重构：前端可观测性要覆盖 AI 交互链路

十一、前端团队可以马上落地的 12 件事

1. 给项目加 AGENTS.md

2. 给组件库补"使用场景"和"禁止用法"

3. 治理测试选择器

4. 建立 AI 生成测试规范

5. 新增依赖必须有理由

6. CI 标记敏感变更

7. 给 AI PR 加 Review 模板

8. 把项目约定放进仓库，而不是放进聊天记录

9. 把常见错误变成 lint 或测试

10. 为核心业务流程建立可观测性

11. 小范围尝试 MCP

12. 定期清理"AI 容易误读"的工程角落

十二、一个可以直接使用的 Frontend AI-Ready Checklist

十三、几个可能引起争论的观点

观点一：AI 不会消灭前端工程化，它会教育工程化差的团队

观点二：未来高级前端的一部分工作，是设计"机器可理解的工程系统"

观点三：最好的 AI 协作不是让它自由发挥，而是让它在边界内高效工作

观点四：面向 AI 的文档，最终会反过来改善人类协作

十四、结语：前端工程化的下一步，是把"经验"变成"系统"

1. 给项目加 `AGENTS.md`