3.3 KiB
3.3 KiB
09. Agent Execution Rules
1. Agent 的角色
Agent 不应在每次任务中重新发明项目设计。它应先理解项目已有规范和资产,再在明确范围内完成实现,并提供可验证的结果。
2. Preflight:实施前检查
任何涉及 UI/UX 的任务开始前:
- 读取 NEX Core 与项目根 Agent 指令。
- 读取
nex.config.yaml和项目级 UI 规范。 - 从真实依赖/锁文件/构建配置确认技术栈,不根据过期 README 猜测。
- 找到 Token 权威来源和派生链路。
- 盘点现有组件和同类页面。
- 确认主题、断点、布局尺寸和交互基线。
- 找到项目现有质量门禁、视觉截图和回归流程。
- 产出差异映射,使用
COMPLIANT、ADOPTED、ADAPTED、DEFERRED、NOT_APPLICABLE。
若用户要求只审计,本阶段之后停止,不得修改代码。
3. Plan:实施计划
跨组件、跨页面、主题、布局或设计 Token 的改动,先列出:
- 目标与非目标;
- 修改文件/组件/页面范围;
- 复用资产与需要新增的内容;
- 对业务交互和布局的影响;
- 风险和回滚方式;
- 质量检查和视觉验收方法。
用户已明确授权的阶段可在授权范围内执行;不得将授权自动扩展到后续阶段。
4. Implement:实现规则
- 先复用项目资产,后新增;先修正权威 Token/主题或共享组件,再改页面。
- 不机械套用参考项目的技术栈、尺寸、断点、品牌色或组件 API。
- 不强制增加第二套 Token、主题或组件系统。
- 不擅自修改业务交互、默认值、数据语义和用户操作路径。
- 对真实缺陷采用最小修复;保留原有交互意图,并补充必要的可访问性行为。
- 将项目不存在的页面/工作区标记为
NOT_APPLICABLE,不引入无关功能。 - 不对页面进行无差别批量替换;先确认设计值语义和实际消费位置。
5. Verify:验证规则
- 只运行仓库中真实存在的脚本和工具。
- 不把启动成功当作完整 UI 验收。
- 视觉检查范围由实际受影响路由、主题、视口和组件决定;复用项目现有回归矩阵。
- 对无自动化覆盖的项目,明确人工检查范围和无法验证事项。
- 比较基线时区分既有问题、此次引入问题和环境差异。
- 对主题、键盘、拖拽替代路径、状态文本、滚动和溢出进行适用性检查。
6. Report:交付报告
至少汇报:
- 修改摘要和文件清单;
- 规范映射状态及偏离理由;
- 复用/新增/调整的组件;
- 交互和视觉变化;
- 实际运行的命令及结果;
- 受影响的路由、主题、视口和截图;
- 未解决问题、风险和下一阶段建议。
7. 分阶段控制
建议按以下阶段推进,但项目可根据实际问题裁剪:
- 阶段 0:规范与基线对齐(原则上只读/只改文档)。
- 阶段 1:高优先级、可复现的视觉/状态缺陷。
- 阶段 2:键盘和可访问性问题。
- 阶段 3:层级、Token、主题等基础治理。
- 阶段 4:共享组件和页面模式改进。
- 阶段 5:分模块页面迁移。
- 阶段 6:视觉回归和质量门禁完善。
阶段不是强制顺序模板;具体由审计证据和用户授权决定。每阶段结束应形成可验收交付,不默认自动进入下一阶段。