三、前端开发场景实战：从需求到可交付页面
前端为什么特别需要 AGENTS.md
因为前端的“错”，很多时候不是功能错，而是风格、结构、状态、交互细节错。
这些问题放到代码层面不一定报错，但上线后很容易被一眼看出来：
- 组件明明仓库里已经有了，AI 又新写了一套。
- 页面主流程看着能跑，但 loading、empty、error 三态没做。
- 移动端断点崩了。
- 交互写得花，但跟现有设计语言不一致。
前端最怕的不是“完全不会做”，而是“看着八成像，但最后还是得返工”。
AGENTS.md 在前端场景里的价值，就是把这些“最后 20% 的对齐成本”提前说明白。
一个真实点的场景
假设你现在要做一个“订单监控看板”页面。
需求听起来很普通，但如果规则不清楚，AI 很容易这样发挥：
- 直接自己造一套卡片组件。
- 标题字号和现有页面不一致。
- 图表区域只做桌面端。
- 没有空状态。
- 按钮 hover 和 focus 状态漏掉。
这些问题每一条单看都不大，但加起来就是完整的返工套餐。
前端 AGENTS.md 里最值得先写的四类规则
1. 组件复用规则
这类规则要尽早写，不然后面设计系统会被一点点打碎。
比如：
## 前端规则
- 先看现有组件能不能复用，再决定要不要新建
- 新增可复用组件时，至少补一个使用示例
- 间距、颜色、字号先沿用当前主题里的现成值
这三条看着简单，实际能挡掉很多问题。
2. 状态完整性规则
前端最常漏的不是主流程，而是边缘状态。
你可以明确写：
- 新页面至少把 loading、空状态、报错状态补齐
- 表单要写清校验和按钮禁用时机
这比口头提醒稳定得多。
3. 响应式和可访问性规则
如果不写，AI 很容易默认只做“眼前这个分辨率”。
比如：
- 新页面至少看一遍桌面端和移动端
- 可点击元素要能用键盘操作
- 不要只靠颜色表达状态
4. 汇报格式规则
前端改动经常会涉及视觉变化，如果汇报格式不统一，review 会很累。
可以直接写：
- 有视觉改动时附截图，或者把页面变化说清楚
- 哪些状态还没补完、哪些要后续跟进，要明说
一个前端团队真能用的写法
# AGENTS.md## 作用范围
- apps/web 是主前端应用
- 想做新 UI 之前，先去 components/ 看有没有现成的## 必跑命令
- pnpm lint
- pnpm test
- pnpm build## UI 规则
- 能复用老组件就别新写
- 颜色、间距、字号都先跟现有主题走
- 新页面把 loading、空状态、报错状态补齐
- 新页面至少检查桌面端和移动端表现## 最终汇报
- 先说页面上看得见的变化
- 再说验证步骤
- 最后说还没补完的状态或风险
一个具体例子：登录页为什么容易返工
登录页看起来简单，但特别容易做得“功能有了，产品不满意”。
常见返工点包括：
- 输入框尺寸和已有表单系统不一致。
- 主按钮颜色不符合品牌色。
- 错误提示只在逻辑里有，界面里没表现。
- 忘记密码、注册入口放错层级。
如果你的 AGENTS.md 里提前把这类事写清楚，AI 的输出稳定性会高很多。
例如：
- 登录注册这类页面，间距和字号跟现有表单保持一致
- 校验报错要直接显示在界面上，不能只停在日志里
- 主按钮沿用产品当前的主操作样式
坏例子和好例子
坏例子：
请保持页面美观、现代、统一。
这句话的问题不是方向错，而是没法执行。
什么叫现代？谁来判断统一？统一到哪里？
好例子：
- 卡片、输入框、按钮优先用 ui/ 里现成的
- 不要顺手加一套新的间距值
- 只要是列表页，就把空状态文案补上
这才是能落地的规则。
一个更像实战的组件规则
假设你们有一套现成的卡片组件，那你可以这样写：
- 看板里的统计卡统一复用 `StatCard`
- 没确认之前，不要在页面里自己再造一个统计卡变体
这样 AI 遇到看板页面时，优先会去复用，而不是现场重新造。
代码层面的一个小示例
下面这个例子不是为了展示多高级，而是想说明“先复用、后扩展”的思路。
type StatCardProps = {title: string;value: string;hint?: string;
};export function StatCard({ title, value, hint }: StatCardProps) {return (<section className="stat-card" aria-label={title}><div className="stat-card__title">{title}</div><div className="stat-card__value">{value}</div>{hint ? <div className="stat-card__hint">{hint}</div> : null}</section>);
}
如果 AGENTS.md 里已经写明“看板统计卡优先复用 StatCard”，那 AI 做新页面时就会更稳。
什么时候该在前端子目录单独放一份 AGENTS.md
如果仓库是 monorepo，而且前端规则和后端规则差很多，最好拆开。
比如：
repo/AGENTS.mdapps/web/AGENTS.mdservices/api/AGENTS.md
根目录写通用规则：
- Git 边界
- 输出格式
- 高风险文件确认机制
前端目录写自己的：
- 组件复用
- 设计变量
- 响应式验证
- 状态覆盖
这样比把所有规则挤在一个文件里清楚很多。
前端团队维护 AGENTS.md 的好办法
我比较推荐从 review 评论反推。
如果你们最近老在 review 里说这些话：
- “这个组件仓库里已经有了。”
- “这个状态没做全。”
- “这个页面移动端看过没有？”
- “这个颜色不是我们主题里的。”
那这些就已经说明，规则值得沉淀。
别再继续用口头提醒了，直接进 AGENTS.md。
最后说一个前端场景特别重要的原则
别把 AGENTS.md 写成“视觉审美说明书”。
前端的审美当然重要，但真正适合写进 AGENTS.md 的，应该优先是这些：
- 什么能复用。
- 什么不能乱改。
- 什么状态必须做。
- 什么验证必须跑。
审美方向可以写一点，但别让它盖过工程规则。
小结
前端场景里，AGENTS.md 最值钱的作用，不是让页面“更有设计感”，而是让页面少返工、少跑偏、少重新造轮子。
你只要先把组件复用、状态完整性、响应式和输出格式这几件事写清楚，效果就会很明显。