nex_design_system/docs/09-agent-development-rules.md

2.8 KiB
Raw Blame History

09. Agent Development Rules

1. 默认工作方式:轻量开发

每个日常任务只做必要的理解和修改:

  1. 阅读项目根 AGENTS.md、nex.config.yaml 和项目 UI 规范;
  2. 按任务读取相关 NEX 章节;
  3. 找到已有页面模式、Token 和共享组件;
  4. 在明确范围内实现需求;
  5. 在对话中简要说明改动。

不得把每个功能任务都转化为全项目审计、分阶段专项或规范升级。

2. 规范加载

  • 始终读取:本文件、项目根 Agent 指令、项目配置和项目 UI 规范。
  • 视觉原则:按需读 01;Token/主题:读 02;布局/响应式:读 03;组件:读 04;交互:读 05;无障碍:读 06;体验性能:读 07;页面模式:读 08;技术栈:新项目/技术初始化时读 10。
  • 不得默认读取全部 NEX 文档。

3. 先复用再实现

先查看现有布局、组件、Token、主题和相邻页面。已有实现能满足需求时不重复建设。仅当重复模式稳定且有实际复用价值时才抽象共享组件。

4. 变更范围

  • 只修改完成当前任务所需的代码和文档。
  • 不顺手整理无关 CSS、重命名组件或重构其他页面。
  • 不因 NEX 示例而更换颜色、尺寸、断点、组件库或目录结构。
  • 不擅自改业务流程、数据语义和用户操作路径。
  • 涉及全局 Token、应用 Shell、共享组件契约或大范围视觉语言变更时,先用简短说明告知影响范围,再实施。

5. 技术栈约束

  • 新项目按 nex.config.yaml 的默认 stack 创建。
  • 已有项目以真实代码和锁文件为准,保留现有技术栈。
  • 不擅自升级框架、替换 UI 库、迁移 JavaScript/TypeScript 或改变数据库。

6. 文档与辅助文件约束

  • 普通任务结果在对话中汇报,不自动创建 Markdown 报告。
  • 不创建阶段编号报告、reports/ 目录或证据截图目录。
  • 不创建 NEX 专属测试脚本、scripts/ui/ 或额外检查工具。
  • 不为 NEX 引入测试依赖或测试框架。
  • 不复制整套 NEX 文档到项目 docs/ 形成重复规范。
  • 长期有效的项目设计决策应更新已有 UI 规范;确需新增文件时,先确认没有合适的现有文档。

7. 任务说明与完成汇报

普通任务不要求先提交长计划。复杂变更用简短文字说明:改哪些区域、复用哪些组件、主要设计选择。完成后用对话汇报:改动摘要、主要文件、重要设计决定和未解决阻塞。不自动生成长报告。

8. NEX 不定义测试流程

是否运行项目测试、使用什么工具、覆盖哪些场景,由用户指令和项目自身工程规则决定。NEX 不要求 Agent 每次运行测试、浏览器自动化、读屏器或全站视觉回归;也不要求 Agent编写测试计划和测试报告。