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