nex_docus/AGENTS.md

74 lines
4.4 KiB
Markdown
Raw Permalink 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.

# NEX Design System — Agent Development Rules (0.1.7)
NEX 的目标是统一设计规范并约束 Agent 开发行为。NEX 不负责测试体系、测试覆盖率、自动化测试、质量闸门或测试报告。
> **本仓库的实际安装路径**:NEX 0.1.7 随仓库置于 `nex_design_system/`,
> 因此下文的 `docs/…` 均相对该目录(如 `nex_design_system/docs/01-design-principles.md`)。
> 本文件即项目根 `AGENTS.md`,§1 第 3、4 项指向的项目规则与项目 UI/UX 规范为:
> `frontend/src/styles/design-tokens.css`(Token 权威来源)、
> `frontend/src/theme/antdTheme.ts`(antd 主题映射)、
> `docs/sdd/architecture/standards/nex-conformance-matrix.md`(符合性与例外,按 0.1.6 章节号登记)、
> `docs/sdd/architecture/standards/responsive-breakpoint-registry.md`(断点登记)、
> `docs/quickstart.md` §6(前端约定)。本项目没有独立的「项目设计规范」文档,以上即权威来源。
## 1. 每个任务的最小读取范围
开始任务时读取:
1. 本文件;
2. 项目根目录 `nex.config.yaml`(如存在);
3. 项目根 `AGENTS.md` 中的项目规则;
4. 项目已有的 UI/UX 规范(如存在)。
然后**按任务读取** NEX 文档,不得默认全量读取:
- 视觉风格/页面:`docs/01-design-principles.md`、`docs/08-page-patterns.md`;
- 颜色/主题/Token:`docs/02-design-tokens-and-theme.md`;
- 页面布局/导航/移动端:`docs/03-layout-and-responsive.md`;
- 公共组件:`docs/04-component-system.md`;
- 表单/表格/弹层/反馈:`docs/05-interaction-system.md`;
- 语义/键盘/辅助技术支持:`docs/06-accessibility-design.md`;
- 体验性能/加载呈现:`docs/07-performance-aware-design.md`;
- 新项目技术栈:`docs/10-project-stack-defaults.md`;
- 首次接入:`docs/11-project-adoption.md`。
## 2. 新项目与已有项目
- 新项目:`nex.config.yaml` 的 `stack` 是明确技术选型。按它初始化,不得自行换栈。
- 已有项目:以真实代码、依赖和锁文件为准,保留现有技术栈;不得因为 NEX 默认值不同而迁移。
- 项目具体视觉参数、Token 名称、组件 API、布局尺寸和断点以项目级 UI 规范为准。
## 3. 开发时必须遵守
1. 先理解现有页面和组件,再改代码;优先复用,不重复造组件。
2. 使用项目既有 Token 和主题单一来源,不另建重复变量层。
3. 保持同类页面、组件和交互的一致性。
4. 不擅自改变业务流程、交互路径、默认值或数据语义。
5. 不擅自升级依赖、替换 UI 库、改变语言或重构目录。
6. 仅修改完成当前任务所需的范围;不顺手重构无关页面。
7. 响应式、无障碍和体验性能按对应设计规范实现;不把这些要求扩展成 NEX 自建测试流程。
8. 若项目实现与 NEX 示例不同,先判断是否是合理的项目适配,不强制套用示例尺寸或命名。
9. 设计要求有冲突时,以安全/适用规范底线、项目级 UI 规范和用户明确要求为依据;无法确定时只提出一个关键问题。
## 4. 执行方式
默认采用轻量开发:
- 对当前需求做必要分析;
- 查找相关现有组件、Token、页面模式;
- 读取相关 NEX 章节;
- 直接实施必要修改;
- 在对话中简要汇报文件和行为变化。
只有涉及全局 Token、应用 Shell、导航体系、共享组件 API 或大范围视觉统一时,才先提交简短影响说明和实施计划。
## 5. NEX 的文件和工具边界
- 普通任务不得创建阶段报告、审计报告、`reports/` 目录或截图证据目录。
- 不得为了遵守 NEX 新建 `scripts/ui/`、自定义检查脚本、自动化测试或质量闸门。
- 不得自动引入 Playwright、axe、Vitest、Pytest 或其他测试工具;它们由项目自身工程规范决定。
- 不得启动 VoiceOver、NVDA、Orca 等屏幕阅读器;NEX 不定义其测试流程。
- 不得把 NEX 规范文档复制成项目中的第二套完整 UI 规范。项目只需保留必要的项目专属设计说明。
- 只有用户明确要求,或确有长期设计决策需要留档时,才新增/更新文档。
## 6. 汇报要求
用简洁对话汇报:完成内容、主要文件、关键设计选择、尚未解决的阻塞。除用户明确要求外,不生成长篇报告,不列出与本任务无关的测试证据。