agent-frontend-standard

Agent Frontend — 前端工程手册

姊妹篇：后端归 agent-backend-standard(hub)；Git 归 git-workflow-standard；护栏供给回路 canonical = cto-orchestration 的 shock-in-the-loop 篇（电在回路/能电不文）。 本手册条目均有 2026 调研证据背书（Anthropic / Figma / Atlassian 等公开来源，二手数据已标注）。 铁律同 hub："In nearly 100% of cases the prompt will win over the guidelines"（Figma 实证）—— 声明式规则是软的，只有编译器、lint=error 和 CI 是硬的。能电不文。

1. 设计系统即 agent 契约

• 受限组件词表：业务代码只准从少量 vetted DS primitives 组合，禁自由 CSS/裸 HTML 拼装。 机制："LLM 不擅长一致发明，擅长查找"。
• 薄封装收窄 prop 面：禁 app 直接 import 厂商组件库；wrapper 禁 {...rest} 透传——透传=把 厂商全部 API 面暴露给 agent 猜。
• token 语义标注是性价比最高的一招：token 定义处写 role + 反用法（"仅 destructive 操作； 禁用于品牌强调"）。50 个设计系统审计只有 1 家写了 do-not-use——写了 agent 就稳定选对。
• 三条 lint 硬门（=error，warn 等于没有）：
  1. tailwind no-arbitrary-value——agent 不知道你的 token 就会吐 hex/px，任意值=样式漂移主通道；
  2. no-restricted-imports 禁 legacy/厂商直连路径——agent 分不清 ui/ 和 legacy/；
  3. 非法 prop 组合用 discriminated union 灭在类型层——"TS 编译器就是设计系统评审员"。
• 机器可查询 > 散文描述：组件 API 给结构化形态（manifest/story/类型），使用规则才写 Markdown。 格式即成本：JSON 组件元数据比散文省 ~80% token（Indeed 1056-prompt 实测，二手）。

2. 类型端到端契约

• 契约在 agent 编辑范围之外：后端契约生成 client，生成物只读——"编不出不存在的 endpoint"。 配对律：契约改动必须触发再生成（pairing 门），生成物手改必须被拦（starter hook ①②已落）。
• typecheck 是 agent 主反馈环：tsc --noEmit 的 file/line/col 五元组比测试堆栈更适合收敛； 每轮都跑（tsgo 已把成本压到可每轮）。
• 封死逃逸口：agent 会用 any/as/@ts-expect-error 把红变绿。type-coverage 阈值 + 抑制注释必须人类 override commit 才放行。
• 认知边界：类型错误是 agent 最会修的一类（也正因此 typecheck 绿≠正确）；逻辑错误修复率仅 ~45% 且两轮后收益枯竭——正确性预算投给断言强度（mutation/oracle），别再收紧 tsconfig。

3. 视觉验证环

• a11y 树优先、截图兜底（双轨不二选一）：snapshot ~200-400 token/确定性/ref 精确；截图 ~3000-5000 token/坐标脆——动画/图表/文案才用截图。axe 类 a11y 检查是少数客观可机验门 （覆盖 ~57%，是门不是证明）。
• 迭代必须设预算上限：视觉环 ≤5 轮、a11y ≤3 轮，超限熔断上报——无退出条件的 agent "要么跑死要么随机停"，迭代精化可能只烧成本零改善。
• 多轮视觉反馈会引发功能遗忘（第 N 轮修好、第 N-3 轮坏了）——视觉环必须配回归重检： VRT 基线 diff / story interaction test 每轮全量复跑。这是 VRT 在 agent 环里的真正理由。
• "没有 check 时 looks-done 是唯一停止条件"：给 agent 的 UI 任务必须带可跑验证 （story test / screenshot diff / typecheck+lint 组合），同北极星 doctrine。