Spec 驱动开发：让 AI 前端交付更可控、可验证

AI 生成代码的速度很快，但速度不会自动带来正确性。Spec 的作用，是把“看起来合理”变成“有明确标准可以验证”。

Spec 不只是需求文档

一份可执行的 Spec 至少包含目标、非目标、用户流程、数据结构、状态变化、异常边界和验收标准。它既是人和 AI 的共同上下文，也是测试和 Code Review 的依据。

## 功能：隐藏报表页面的面包屑
### 目标
报表页面进入后隐藏面包屑，离开页面自动恢复。
### 约束
不能修改全局默认布局，不能影响其他标签页。
### 验收
- 进入报表页：面包屑不可见
- 导航到普通页面：面包屑恢复
- 刷新页面：状态与路由一致

状态和边界先写清楚

前端复杂度往往来自状态组合，而不是 JSX 数量。可以先用状态表描述 Loading、Empty、Error、Forbidden 和 Success，再让 Agent 生成组件。

1	type ViewState = "loading" \| "empty" \| "ready" \| "forbidden" \| "error";

Spec 如何进入开发闭环

开发前让 Agent 根据 Spec 输出实现计划；开发中逐条勾选；开发后把验收条目转成测试和人工检查。需求变更时先更新 Spec，再修改代码，避免实现和约定分叉。

如何在现有项目中引入 Spec

可以从一个功能目录开始，不要求一次性重写历史需求：

specs/
└── invoice-report/
    ├── requirements.md
    ├── states.md
    ├── api-contract.md
    ├── acceptance.md
    └── decisions.md

requirements.md 写用户目标，states.md 写页面状态，api-contract.md 写前端需要的数据形状，acceptance.md 写可检查的结果，decisions.md 记录为什么选择当前方案。Agent 进入任务后先读 Spec，再读取源码；代码实现完成后逐条回填验收项。

一个页面的状态 Spec

| 状态 | 页面表现 | 用户操作 |
| --- | --- | --- |
| loading | 展示骨架屏 | 不重复提交 |
| empty | 展示空状态和创建入口 | 创建第一条数据 |
| ready | 展示列表和操作 | 查询、编辑、导出 |
| forbidden | 展示无权限说明 | 返回上一级 |
| error | 展示错误和重试 | 重新加载 |

这类表格比一句“做好异常处理”更容易被 AI、开发者和测试人员共同使用。

Spec 的变更与评审

当需求变更时，先在 Spec 中增加决策记录，再修改代码和测试。Review 时同时查看 Spec、实现和验证结果，避免只审查代码风格而漏掉产品行为。Spec 也可以作为发布说明和后续维护的入口。

小结

Spec 不会限制创造力，它把创造力放在正确的位置：先明确问题和边界，再自由选择实现方式。对 AI 开发而言，Spec 是减少返工、提高审阅质量的最低成本工具。