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

54 lines
2.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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编写测试计划和测试报告。